> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# NGINX

> NGINX connection and request metrics scraped from the stub_status endpoint.

The NGINX integration requires CXDOT Collector 1.4.0 or greater.

[NGINX](https://nginx.org/) is a web server, reverse proxy, and load balancer. Use the
NGINX integration with the Chronosphere XDOT Collector to collect connection and request
metrics from NGINX servers running in your environment.

The NGINX integration supports NGINX 1.26 or greater.

## Supported telemetry types

The NGINX integration supports these telemetry types:

| Type    | Supported |
| ------- | --------- |
| Logs    | No        |
| Metrics | Yes       |
| Traces  | No        |
| Events  | No        |

## Prerequisites

The NGINX integration has the following prerequisites:

* Use an NGINX build that includes the
  [`ngx_http_stub_status_module`](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html).
  To confirm that your build includes the module, run:

  ```shell theme={null}
  nginx -V 2>&1 | grep -- --with-http_stub_status_module
  ```

* Make the NGINX status endpoint reachable from the collector.

## Configure

To configure the NGINX integration, follow these steps:

1. Configure NGINX to expose status information at `/status`. For example, add the
   following location to the NGINX server configuration:

   ```nginx theme={null}
   location = /status {
       stub_status;
   }
   ```

2. Choose how the collector finds your NGINX servers:

   * For NGINX pods that listen on port `80`, add the
     `app.kubernetes.io/name: nginx` label to the pod template.
   * For NGINX pods or Services that use another port or status path, add
     autodiscovery annotations that provide the NGINX status URL.

   For more information, see
   [autodiscovery](https://docs.chronosphere.io/ingest/cxdot-collector/autodiscovery).

3. Optional: Configure static targets to collect metrics from NGINX servers outside
   your Kubernetes cluster. For example, add the following to the `values.yaml` for
   your Helm chart:

   ```yaml theme={null}
   config:
     integrations:
       nginx:
         endpoints:
           - endpoint: 10.0.0.5:80
   ```

   When you configure static targets, this integration instance collects from exactly
   those targets instead of discovered targets.

4. Optional: Configure a second integration instance to collect from both discovered
   pods and static targets. For example, add the following to the `values.yaml` for
   your Helm chart:

   ```yaml theme={null}
   config:
     integrations:
       nginx: {}
       nginx/edge:
         endpoints:
           - endpoint: 10.0.0.5:80
   ```

   The `nginx/edge` key defines a named instance for the static targets. The bare
   `nginx` key continues to use autodiscovery.

### Validate

To validate the NGINX integration, follow these steps:

1. In the Live Telemetry Analyzer, filter for `cxdot.integration.name=nginx`. Confirm
   that the NGINX metric names appear.

2. In Metrics Explorer, run the following query while the NGINX servers receive
   traffic:

   ```text theme={null}
   sum by ("server.address", "server.port") (rate({"nginx.requests"}[$__rate_interval]))
   ```

   Confirm that the query returns the expected time series for each target.

For more information about diagnosing a failing integration, see
[Troubleshooting](https://docs.chronosphere.io/ingest/cxdot-collector/troubleshooting).

## Configuration reference

Configure one NGINX integration instance with the following settings. In Helm values, place
these settings under `config.integrations.nginx`. In a Collector configuration file, place them
under `cxdot.integrations.nginx`.

### Optional settings

* **`enabled`**
  Type: `boolean`. Optional. Default: `true`.
  Whether to enable this NGINX integration instance. If true, the Collector runs the instance.
  If false, the Collector doesn't run it.

* **`endpoints`**
  Type: `array of object`. Optional.
  Static NGINX targets. When this list is empty or omitted, the integration uses autodiscovery.
  When the list contains targets, this integration instance collects from exactly those targets
  and doesn't use autodiscovery. Configure a second named instance to use both methods. For a
  `host:port` value, the Collector requests `http://<host>:<port>/status`. For a full URL, the
  Collector requests the URL as written. An `https` URL must include the status path.

* **`endpoints[].endpoint`**
  Type: `string`. Required.
  NGINX endpoint as either `host:port` or a full HTTP or HTTPS URL. For `host:port`, the
  Collector requests the `/status` path over HTTP.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `10s`.
  How often the Collector collects metrics from each NGINX endpoint.

* **`timeout`**
  Type: `duration`. Optional. Default: `10s`.
  Maximum time the Collector waits for an NGINX endpoint to respond during one collection. This
  value must not exceed `collection_interval`. If the deadline expires, that collection fails.

* **`disable_keep_alives`**
  Type: `boolean`. Optional. Default: `true`.
  Close the scrape connection after each collection instead of holding it open with keep-alive.
  A held connection remains in the NGINX `waiting` state for `keepalive_timeout` and inflates
  `nginx.connections_current{state="waiting"}`, so connections close by default. Set this value
  to `false` to reuse one connection across collections. Annotation-discovered endpoints instead
  take connection persistence from the annotation's `persist_connections`,
  `tls_use_host_header`, `headers`, and `extra_headers` fields.

* **`tls`**
  Type: `object`. Optional.
  TLS settings for connections to NGINX endpoints. These settings apply only to endpoints that
  use `https`. The Collector verifies server certificates by default.

* **`tls.ca_file`**
  Type: `string`. Optional.
  Path to a PEM-encoded certificate authority (CA) certificate file used to verify the NGINX
  server certificate. If omitted, the Collector uses the system certificate authority pool.

* **`tls.ca_pem`**
  Type: `string`. Optional.
  PEM-encoded certificate authority certificate content used to verify the NGINX server
  certificate.

* **`tls.cert_file`**
  Type: `string`. Optional.
  Path to the PEM-encoded client certificate file to present when the NGINX endpoint requires
  mutual TLS authentication.

* **`tls.cert_pem`**
  Type: `string`. Optional.
  PEM-encoded client certificate content to present when the NGINX endpoint requires mutual TLS
  authentication.

* **`tls.cipher_suites`**
  Type: `array of string`. Optional.
  TLS cipher suites that the Collector can use, in preference order. If omitted, the Collector
  uses the secure defaults from the Go TLS library. For supported names, see
  [https://go.dev/src/crypto/tls/cipher\_suites.go](https://go.dev/src/crypto/tls/cipher_suites.go).

* **`tls.curve_preferences`**
  Type: `array of string`. Optional.
  Elliptic curves that the Collector can use for an elliptic curve Diffie-Hellman ephemeral
  handshake, in preference order. If omitted, the Collector uses the Go TLS library defaults.

* **`tls.include_system_ca_certs_pool`**
  Type: `boolean`. Optional.
  Whether to add certificates from the system certificate authority pool to the configured
  certificate authorities. If true, the Collector trusts both sources. If false, the Collector
  trusts only the configured certificate authorities.

* **`tls.insecure`**
  Type: `boolean`. Optional.
  Whether to disable transport security. If true, the Collector uses an unencrypted connection.
  If false, the Collector uses TLS for HTTPS endpoints.

* **`tls.insecure_skip_verify`**
  Type: `boolean`. Optional.
  Whether to skip verification of the NGINX server certificate. If true, the connection is
  encrypted but isn't authenticated and is vulnerable to man-in-the-middle attacks. If false,
  the Collector verifies the certificate.

* **`tls.key_file`**
  Type: `string`. Optional.
  Path to the PEM-encoded client private key file used with `cert_file` for mutual TLS
  authentication.

* **`tls.key_pem`**
  Type: `string`. Optional.
  PEM-encoded client private key content used with `cert_pem` for mutual TLS authentication.

* **`tls.max_version`**
  Type: `string`. Optional.
  Maximum TLS protocol version the Collector can use. If omitted, the Collector uses the maximum
  version supported by the Go TLS library.

* **`tls.min_version`**
  Type: `string`. Optional.
  Minimum TLS protocol version the Collector can use. If omitted, the minimum version is TLS
  1.2.

* **`tls.reload_interval`**
  Type: `duration`. Optional.
  How often the Collector reloads certificate and key files. If omitted, the Collector doesn't
  reload the files.

* **`tls.server_name_override`**
  Type: `string`. Optional.
  Server name to verify in the NGINX certificate instead of the endpoint hostname. Use this
  setting when the certificate name differs from the endpoint hostname.

* **`tls.tpm`**
  Type: `object`. Optional.
  Trusted platform module settings for the TLS private key.

* **`tls.tpm.auth`**
  Type: `string`. Optional.
  Authorization value for the trusted platform module key.

* **`tls.tpm.enabled`**
  Type: `boolean`. Optional.
  Whether to use a trusted platform module for the TLS private key. If true, the Collector loads
  the key from the configured device or socket. If false, the Collector uses the configured key
  file or in-memory key.

* **`tls.tpm.owner_auth`**
  Type: `string`. Optional.
  Owner authorization value for the trusted platform module.

* **`tls.tpm.path`**
  Type: `string`. Optional.
  Path to the trusted platform module device or Unix domain socket, such as `/dev/tpm0` or
  `/dev/tpmrm0`.


## Related topics

- [Control your log data](/control/shaping/shape-logs/control-logs.md)
- [Parsers](/ingest/pipeline/v2/build/parsers.md)
- [Logging query syntax](/investigate/querying/query-logs/query-syntax.md)
- [Create links to related information](/investigate/querying/create-links.md)
- [Datadog Logs destination plugin](/ingest/pipeline/plugins/destination-plugins/datadog.md)