Skip to main content
The NGINX integration requires CXDOT Collector 1.4.0 or greater. NGINX is a web server, reverse proxy, and load balancer. Use the NGINX CXDOT Collector integration with the CXDOT Collector to collect connection and request metrics from NGINX servers running in your environment.

Supported telemetry types

The NGINX CXDOT Collector integration supports these telemetry types:

Prerequisites

The NGINX CXDOT Collector integration has the following prerequisites:
  • Use an NGINX build that includes the ngx_http_stub_status_module. To confirm that your build includes the module, run:
  • Make the NGINX status endpoint reachable from the CXDOT Collector.

Configure

The NGINX CXDOT Collector integration is enabled by default. You can configure targets either by annotating pods in your Kubernetes cluster or by listing static endpoints in your Helm values. To configure the integration, follow these steps:
  1. Configure NGINX to expose status information at /status. For example, add the following location to the NGINX server configuration:
  2. To collect from NGINX pods in Kubernetes, add a CXDOT integration annotation to the pod template. The annotation key must end with the container name. For example, add the following annotation to your NGINX workload:
    The Collector replaces ${target.host} with the pod IP address and ${target.port.status} with the container port named status. The Collector also discovers NGINX pods that carry the app.kubernetes.io/name: nginx label and listen on port 80. A CXDOT integration annotation takes precedence over the label for its container. To stop collecting from a container, set nginx: {enabled: false} in the annotation. For more information, see autodiscovery.
  3. Optional: To collect from NGINX servers outside your Kubernetes cluster, configure static targets. For example, add the following to the values.yaml for your CXDOT Collector Helm chart:
    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 annotated pods and static targets. For example, add the following to the values.yaml for your CXDOT Collector Helm chart:
    The nginx/edge key defines a named instance for the static targets. The bare nginx key continues to discover pods.

Validate

To validate the NGINX CXDOT Collector integration, follow these steps:
  1. In the Live Telemetry Analyzer, filter for cxdot.integration.name="nginx" and __name__="cxdot.integration.target.health". Confirm that the metric reports 1 for each reachable NGINX target.
  2. In Metrics Explorer, run the following query while the NGINX servers receive traffic:
    Confirm that the query returns the expected time series for each target.

Configuration reference

Configure one NGINX integration instance with the following settings. In Helm values, place these settings under collection.cxdot.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. Default: []. 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.
  • 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.