On each NGINX server, create a status.conf file in the directory that contains your other NGINX configuration files, such as /etc/nginx/conf.d/.

server {
  listen 81;
  server_name localhost;

  access_log off;
  allow 127.0.0.1;
  deny all;

  location /nginx_status {
    # Choose your status module

    # freely available with open source NGINX
    stub_status;

    # for open source NGINX < version 1.7.5
    # stub_status on;

    # available only with NGINX Plus
    # status;

    # ensures the version information can be retrieved
    server_tokens on;
  }
}

NGINX Plus

NGINX Plus users can also use stub_status, but since that module provides fewer metrics, Datadog recommends using status.

For NGINX Plus releases 15+, the status module is deprecated. Use the http_api_module instead. For example, enable the /api endpoint in your main NGINX configuration file (/etc/nginx/conf.d/default.conf):

server {
  listen 8080;
  location /api {
    api write=on;
  }
}

To get more detailed metrics with NGINX Plus (such as 2xx / 3xx / 4xx / 5xx response counts per second), set a status_zone on the servers you want to monitor. For example:

server {
  listen 80;
  status_zone <ZONE_NAME>;
  ...
}

Reload NGINX to enable the status or API endpoint. There’s no need for a full restart.

sudo nginx -t && sudo nginx -s reload

Add the following snippet to your configuration ConfigMaps to expose the metrics endpoint in a different port:

kind: ConfigMap
metadata:
  name: nginx-conf
data:
[...]
  status.conf: |
    server {
      listen 81;

      location /nginx_status {
        stub_status on;
      }

      location / {
        return 404;
      }
    }    

Then, in your NGINX pod, expose the 81 endpoint and mount that file in the NGINX configuration folder:

spec:
  containers:
    - name: nginx
      ports:
        - containerPort: 81
      volumeMounts:
        - mountPath: /etc/nginx/conf.d/status.conf
          subPath: status.conf
          readOnly: true
          name: "config"
  volumes:
    - name: "config"
      configMap:
          name: "nginx-conf"

Host

To configure this check for an Agent running on a host:

Follow the instructions below to configure this check for an Agent running on a host. For containerized environments, see the Docker, Kubernetes, or ECS sections.

Metric collection

1. Set the nginx_status_url parameter to http://localhost:81/nginx_status/ in your nginx.d/conf.yaml file to start gathering your NGINX metrics. See the sample nginx.d/conf.yaml for all available configuration options.

   NGINX Plus:

   • For NGINX Plus releases 13+, set the parameter use_plus_api to true in your nginx.d/conf.yaml configuration file.

   • Stream stats API calls are included by default for NGINX Plus. If you want to disable them, set the parameter use_plus_api_stream to false in your nginx.d/conf.yaml configuration file.

   • If you are using http_api_module, set the parameter nginx_status_url to the server’s /api location in your nginx.d/conf.yaml configuration file, for example:

     nginx_status_url: http://localhost:8080/api
     

2. Optional - If you are using the NGINX vhost_traffic_status module, set the parameter use_vts to true in your nginx.d/conf.yaml configuration file.

3. Restart the Agent to start sending NGINX metrics to Datadog.

Log collection

Available for Agent versions >6.0

1. Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml file:

   logs_enabled: true
   

2. Add this configuration block to your nginx.d/conf.yaml file to start collecting your NGINX Logs:

   logs:
     - type: file
       path: /var/log/nginx/access.log
       service: nginx
       source: nginx
   
     - type: file
       path: /var/log/nginx/error.log
       service: nginx
       source: nginx
   

   Change the service and path parameter values and configure them for your environment. See the sample nginx.d/conf.yaml for all available configuration options.

3. Restart the Agent.

Note: The default NGINX log format does not have a request response time. To include it into your logs, update the NGINX log format by adding the following configuration block in the http section of your NGINX configuration file (/etc/nginx/nginx.conf):

http {
	#recommended log format
	log_format nginx '\$remote_addr - \$remote_user [\$time_local] '
                  '"\$request" \$status \$body_bytes_sent \$request_time '
                  '"\$http_referer" "\$http_user_agent"';

	access_log /var/log/nginx/access.log;
}

Docker

To configure this check for an Agent running on a container:

Metric collection

Set Autodiscovery Integration Templates as Docker labels on your application container:

LABEL "com.datadoghq.ad.check_names"='["nginx"]'
LABEL "com.datadoghq.ad.init_configs"='[{}]'
LABEL "com.datadoghq.ad.instances"='[{"nginx_status_url": "http://%%host%%:81/nginx_status/"}]'

Note: This instance configuration works only with NGINX Open Source. If you are using NGINX Plus, inline the corresponding instance configuration.

Log collection

Collecting logs is disabled by default in the Datadog Agent. To enable it, see Docker Log Collection.

Then, set Log Integrations as Docker labels:

LABEL "com.datadoghq.ad.logs"='[{"source":"nginx","service":"nginx"}]'

Kubernetes

To configure this check for an Agent running on Kubernetes:

Metric collection

Set Autodiscovery Integrations Templates as pod annotations on your application container. Alternatively, you can configure templates with a file, configmap, or key-value store.

Annotations v1 (for Datadog Agent < v7.36)

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  annotations:
    ad.datadoghq.com/nginx.check_names: '["nginx"]'
    ad.datadoghq.com/nginx.init_configs: '[{}]'
    ad.datadoghq.com/nginx.instances: |
      [
        {
          "nginx_status_url":"http://%%host%%:81/nginx_status/"
        }
      ]      
  labels:
    name: nginx

Annotations v2 (for Datadog Agent v7.36+)

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  annotations:
    ad.datadoghq.com/nginx.checks: |
      {
        "nginx": {
          "init_config": {},
          "instances": [
            {
              "nginx_status_url":"http://%%host%%:81/nginx_status/"
            }
          ]
        }
      }      
  labels:
    name: nginx

Note: This instance configuration works only with NGINX Open Source. If you are using NGINX Plus, inline the corresponding instance configuration.

Log collection

Collecting logs is disabled by default in the Datadog Agent. To enable it, see Kubernetes Log Collection.

Then, set Log Integrations as pod annotations. Alternatively, you can configure this with a file, configmap, or key-value store.

Annotations v1/v2

apiVersion: v1
kind: Pod
metadata:
  name: nginx
  annotations:
    ad.datadoghq.com/nginx.logs: '[{"source":"nginx","service":"nginx"}]'
  labels:
    name: nginx

ECS

To configure this check for an Agent running on ECS:

Metric collection

Set Autodiscovery Integrations Templates as Docker labels on your application container:

{
  "containerDefinitions": [{
    "name": "nginx",
    "image": "nginx:latest",
    "dockerLabels": {
      "com.datadoghq.ad.check_names": "[\"nginx\"]",
      "com.datadoghq.ad.init_configs": "[{}]",
      "com.datadoghq.ad.instances": "[{\"nginx_status_url\":\"http://%%host%%:81/nginx_status/\"}]"
    }
  }]
}

Note: This instance configuration works only with NGINX Open Source. If you are using NGINX Plus, inline the corresponding instance configuration.

Log collection

Collecting logs is disabled by default in the Datadog Agent. To enable it, see ECS Log Collection.

Then, set Log Integrations as Docker labels:

{
  "containerDefinitions": [{
    "name": "nginx",
    "image": "nginx:latest",
    "dockerLabels": {
      "com.datadoghq.ad.logs": "[{\"source\":\"nginx\",\"service\":\"nginx\"}]"
    }
  }]
}