NGINX monitoring integration

Our NGINX integration collects and sends inventory and metrics from your NGINX server to our platform, where you can see data on connections and client requests so that you can find the source of any problems.

Read on to install the integration, and to see what data we collect.

Compatibility and requirements

Our integration is compatible with both NGINX Open Source and NGINX Plus.

Before installing the integration, make sure that you meet the following requirements:

A New Relic account. Don't have one? Sign up for free! No credit card required.
NGINX extension enabled, as described in the Configure the integration section.
If NGINX is not running on Kubernetes or Amazon ECS, you must install the infrastructure agent on a Linux OS host that's running NGINX. Otherwise:
- If running on Kubernetes, see these requirements.
- If running on ECS, see these requirements.

Quick start

Instrument your NGINX server quickly and send your telemetry data with guided install. Our guided install creates a customized CLI command for your environment that downloads and installs the New Relic CLI and the infrastructure agent.

Ready to get started? Click one of these button to try it out.

Guided install

EU Guided install

Our guided install uses the infrastructure agent to set up the NGINX integration. Not only that, it discovers other applications and log sources running in your environment and then recommends which ones you should instrument.

The guided install works with most setups. But if it doesn't suit your needs, you can find other methods below to get started monitoring your NGINX server.

Install and activate the integration

To install the NGINX integration, follow the instructions for your environment:

Follow the general instructions for installing an integration, using the filename nri-nginx. Then continue on to the steps below.
Change the directory to the integrations configuration folder:
```
cd /etc/newrelic-infra/integrations.d
```

Copy the sample configuration file:

sudo cp nginx-config.yml.sample nginx-config.yml

Edit the configuration file nginx-config.yml.
Restart the infrastructure agent.

Additional notes:

Advanced: Integrations are also available in tarball format to allow for install outside of a package manager.
On-host integrations do not automatically update. For best results, regularly update the integration package and the infrastructure agent.

Configuration

Enabling your NGINX Server

To capture data from the NGINX integration, you must first enable and configure the applicable extension module:

For NGINX Open Source: HTTP stub status module
For NGINX Plus: HTTP status module and HTTP API module

Configure the integration

There are several ways to configure the integration, depending on how it was installed:

If enabled via Kubernetes: see Monitor services running on Kubernetes.
If enabled via Amazon ECS: see Monitor services running on ECS.
If installed on-host: edit the config in the integration's YAML config file, nginx-config.yml.

An integration's YAML-format configuration is where you can place required login credentials and configure how data is collected. Which options you change depend on your setup and preference.

The configuration file has common settings applicable to all integrations like interval, timeout, inventory_source. To read all about these common settings refer to our Configuration Format document.

Important

If you are still using our Legacy configuration/definition files please refer to this document for help.

Specific settings related to NGINX are defined using the env section of the configuration file. These settings control the connection to your NGINX instance as well as other security settings and features. The list of valid settings is described in the next section of this document.

NGINX Instance Settings

The NGINX integration collects both Metrics and Inventory information. Check the Applies To column below to find which settings can be used for each specific collection:

Setting	Description	Default	Applies To
STATUS_URL	The URL set up to provide the metrics using the status module.	http://127.0.0.1/status	Metrics/Inventory
STATUS_MODULE	Name of NGINX status module. Valid options are: discover ngx_http_stub_status_module ngx_http_status_module ngx_http_api_module"	discover	Metrics
CONNECTION_TIMEOUT	Connection timeout to the NGINX instance in seconds.	5	Metrics
VALIDATE_CERTS	Set to `false` if the status URL is HTTPS with a self-signed certificate.	true	Metrics
CONFIG_PATH	The path to the NGINX configuration file.	N/A	Inventory
REMOTE_MONITORING	Enable multi-tenancy monitoring.	true	Metrics/Inventory
METRICS	Set to `true` to enable Metrics only collection.	false
INVENTORY	Set to `true` to enable Inventory only collection.	false

The values for these settings can be defined in several ways:

Adding the value directly in the config file. This is the most common way.
Replacing the values from environment variables using the {{}} notation. This requires infrastructure agent v1.14.0+. Read more here or see example below.
Using Secrets management. Use this to protect sensible information such as passwords to be exposed in plain text on the configuration file. For more information, see Secrets management.

Labels/Custom Attributes

You can further decorate your metrics using labels. Labels allow you to add key/value pairs attributes to your metrics which you can then use to query, filter or group your metrics on.
Our default sample config file includes examples of labels but, as they are not mandatory, you can remove, modify or add new ones of your choice.

labels:
   env: production
   role: load_balancer

Example configurations

This is the very basic configuration to collect Metrics and Inventory from your localhost:

integrations:
  - name: nri-nginx
    env:
      METRICS: "true"
      STATUS_URL: http://127.0.0.1/status
      STATUS_MODULE: discover
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      env: production
      role: load_balancer

  - name: nri-nginx
    env:
      INVENTORY: "true"
      STATUS_URL: http://127.0.0.1/status
      CONFIG_PATH: /etc/nginx/nginx.conf
      REMOTE_MONITORING: true
    interval: 60s
    labels:
      env: production
      role: load_balancer
    inventory_source: config/nginx

This configuration collects Metrics and Inventory from your localhost protected with basic authentication. Replace the username and password on the STATUS_URL with your credentials:

integrations:
  - name: nri-nginx
    env:
      METRICS: "true"
      STATUS_URL: http://username:password@127.0.0.1/status
      STATUS_MODULE: discover
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      env: production
      role: load_balancer

  - name: nri-nginx
    env:
      INVENTORY: "true"
      STATUS_URL: http://username:password@127.0.0.1/status
      CONFIG_PATH: /etc/nginx/nginx.conf
      REMOTE_MONITORING: true
    interval: 60s
    labels:
      env: production
      role: load_balancer
    inventory_source: config/nginx

In this configuration we only have 1 integration block with METRICS: true to collect only metrics and added VALIDATE_CERTS: false to prevent validation of the server's SSL certificate when using a self-signed one:

integrations:
  - name: nri-nginx
    env:
      METRICS: "true"
      STATUS_URL: https://my_nginx_host/status
      STATUS_MODULE: discover
      VALIDATE_CERTS: false
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      env: production
      role: load_balancer

In this configuration we are using the environment variable NGINX_STATUS to populate the STATUS_URL setting of the integration:

integrations:
  - name: nri-nginx
    env:
      METRICS: "true"
      STATUS_URL: {{NGINX_STATUS}}
      STATUS_MODULE: discover
      VALIDATE_CERTS: false
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      env: production
      role: load_balancer

In this configuration we are monitoring multiple NGINX servers from the same integration. For the first instance (STATUS_URL: https://1st_nginx_host/status) we are collecting metrics and inventory while for the second instance (STATUS_URL: https://2nd_nginx_host/status) we will only collect metrics.

integrations:
  - name: nri-nginx
    env:
      METRICS: "true"
      STATUS_URL: https://1st_nginx_host/status
      STATUS_MODULE: discover
      VALIDATE_CERTS: false
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      env: production
      role: load_balancer
  - name: nri-nginx
    env:
      INVENTORY: "true"
      STATUS_URL: https://1st_nginx_host/status
      CONFIG_PATH: /etc/nginx/nginx.conf
      REMOTE_MONITORING: true
    interval: 60s
    labels:
      env: production
      role: load_balancer
    inventory_source: config/nginx

  - name: nri-nginx
    env:
      METRICS: "true"
      STATUS_URL: http://2nd_nginx_host/status
      STATUS_MODULE: discover
      VALIDATE_CERTS: false
      REMOTE_MONITORING: true
    interval: 30s
    labels:
      env: production
      role: load_balancer

Find and use data

Data from this service is reported to an integration dashboard.

Metrics are attached to the NginxSample event type. You can query this data for troubleshooting purposes or to create custom charts and dashboards.

For more on how to find and use your data, see Understand integration data.

Metrics

The NGINX integration collects the following metric data attributes. To find these attributes, query the NginxSample event type.

NGINX Open Source

Metric	Description
`net.connectionsActive`	Number of connections that are currently active
`net.connectionsAcceptedPerSecond`	Number of accepted client connections per second
`net.connectionsDroppedPerSecond`	Number of connections per second that were accepted but could not he handled and hence dropped
`net.connectionsReading`	Current number of connections where NGINX is reading the request header
`net.connectionsWaiting`	Current number of idle client connections waiting for a request
`net.connectionsWriting`	Current number of connections where NGINX is writing the response back to the client
`net.requestsPerSecond`	Total number of client requests per second

NGINX Plus

Our integration retrieves all available metric data from the following HTTP API endpoints: /nginx, /processes, /connections, /http/requests, and /ssl.

Metric	Description
`net.connectionsAcceptedPerSecond`	Accepted client connections as requests per second
`net.connectionsDroppedPerSecond`	Dropped client connections as requests per second
`net.connectionsActive`	Current number of active client connections
`net.connectionsIdle`	Current number of idle client connections
`net.requests`	Current number of requests
`net.requestsPerSecond`	Current number of requests per second
`processes.respawned`	Current number of abnormally terminated and respawned child processes
`ssl.handshakes`	Current number for successful SSL handshakes
`ssl.failedHandshakes`	Current number of failed SSL handshakes
`ssl.sessionReuses`	Current number of session reuses during SSL handshake

Inventory data

The integration captures configuration options defined in the NGINX master config file (usually nginx.conf).

Tip

The master NGINX config file can contain "include OTHER_FILE_NAME" commands for splitting the configuration into multiple files. The Infrastructure agent ignores (does not parse) configuration set via include commands.

System metadata

The integration collects these additional attributes about the NGINX service:

Name	Description
`software.edition`	The NGINX edition: either `"open source"` or `"plus"`.
`software.version`	The version of NGINX.

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.

For more help

If you need more help, check out these support and learning resources:

Browse the Explorers Hub to get help from the community and join in discussions.
Find answers on our sites and learn how to use our support portal.
Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
Review New Relic's data security and licenses documentation.

Compatibility and requirements

Quick start

Install and activate the integration

ECS

Kubernetes

Linux

Configuration

Enabling your NGINX Server

Configure the integration

Important

NGINX Instance Settings

Labels/Custom Attributes

Example configurations

BASIC CONFIGURATION

HTTP BASIC AUTHENTICATION

METRICS ONLY WITH SELF-SIGNED CERTIFICATE

ENVIRONMENT VARIABLES REPLACEMENT

MULTI-INSTANCE MONITORING

Find and use data

Metrics

NGINX Open Source

NGINX Plus

Inventory data

Tip

System metadata

Check the source code

For more help

NGINX monitoring integration

Compatibility and requirements

Quick start

Install and activate the integration

Kubernetes

Linux

Configuration

Enabling your NGINX Server

Configure the integration

Important

NGINX Instance Settings

Labels/Custom Attributes

Example configurations

BASIC CONFIGURATION

HTTP BASIC AUTHENTICATION

METRICS ONLY WITH SELF-SIGNED CERTIFICATE

ENVIRONMENT VARIABLES REPLACEMENT

MULTI-INSTANCE MONITORING

Find and use data

Metrics

NGINX Open Source

NGINX Plus

Inventory data

Tip

System metadata

Check the source code

.css-3u3y73{fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}.css-1bvd50p{width:1rem;height:1rem;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}For more help

For more help