NGINX monitoring integration

Our NGINX integration collects and sends inventory, logs, 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.

To install the NGINX monitoring integration, you must run through the following steps:

Enable your NGINX Server.
Install and activate the integration.
Configure the integration.
Find and use data.
Optionally, see NGINX's configuration settings.

Important

For best results, regularly update the integration package and the infrastructure agent.

Compatibility and requirements

Our integration is compatible with both NGINX Open Source and NGINX Plus. Before installing the integration, ensure 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 Enable your NGINX Server section.
If NGINX is not running on Kubernetes or Amazon ECS, you must install the infrastructure agent on a Linux or Windows OS host that's running NGINX. Otherwise:
- If running on Kubernetes, see these requirements.
- If running on Amazon ECS, see these requirements.

Supported operating systems

Windows
Linux

For a comprehensive list of specific Windows and Linux versions, check the table of compatible operating systems.

Enable your NGINX Server

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

For NGINX Open Source, see HTTP stub status module.
For NGINX Plus, see HTTP status module and HTTP API module.

Install and activate the integration

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

Linux installation

Install the infrastructure agent, and replace the INTEGRATION_FILE_NAME variable with nri-nginx.
Change the directory to the integrations configuration folder by running:
bash
```
$cd /etc/newrelic-infra/integrations.d
```
Copy the sample configuration file by running:
bash
```
$sudo cp nginx-config.yml.sample nginx-config.yml
```
Edit the nginx-config.yml configuration file with your favorite editor. Check out some configuration file examples..
Restart the infrastructure agent. See how to restart the infrastructure agent in different Linux environments.
To enable automatic NGINX access and error log parsing and forwarding, copy (or rename) the nginx-log.yml.example file to nginx-log.yml. No need to restart the agent.
bash
```
$sudo cp /etc/newrelic-infra/logging.d/nginx-log.yml.example /etc/newrelic-infra/logging.d/nginx-log.yml
```

Other environments

Download the nri-nginx .MSI installer image from:
https://download.newrelic.com/infrastructure_agent/windows/integrations/nri-nginx/nri-nginx-amd64.msi
To install from the Windows command prompt, run:
bash
```
$msiexec.exe /qn /i PATH\TO\nri-nginx-amd64.msi
```
or double-click the file in Explorer.
In the Integrations directory, C:\Program Files\New Relic\newrelic-infra\integrations.d\, create a copy of the sample configuration file by running:
bash
```
$copy nginx-config.yml.sample nginx-config.yml
```
Edit the nginx-config.yml file as described in the configuration settings.
To enable automatic NGINX access and error log parsing and forwarding, copy (or rename) the nginx-log-win.yml.example file to nginx-log.yml.
bash
```
$copy nginx-log-win.yml.example nginx-log.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.

Did this doc help with your installation?

Configure the integration

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

If it was enabled via Kubernetes, see Monitor services running on Kubernetes.
If it was enabled via Amazon ECS, see Monitor services running on ECS.
If it was installed on-host, edit the integration's nginx-config.yml configuration file. An integration's YAML-format configuration is where you can place required login credentials and configure how data is collected. The options you change depend on your setup and preference. The configuration file has common settings applicable to all integrations such as interval, timeout, or inventory_source. To read about these common settings, see configuration format.

Important

If you are still using our Legacy configuration and definition files, 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-config.yml sample files

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

Configuration options for the integration

For more on how to find and use your data, see NGINX's configuration settings.

Find and use data

After you've configured and installed the integration, you can start monitoring:

Data from this service, which is reported to an integration dashboard.
Metrics that are attached to the NginxSample event type. You can query this data for troubleshooting purposes or to create custom charts and dashboards.
Logs will be visible in the logs UI.

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

Metrics collected by the integration

The NGINX integration collects the following metrics:

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

New Relic's 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

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

Important

Compatibility and requirements

Supported operating systems

Enable your NGINX Server

Install and activate the integration

Linux installation

Other environments

Amazon ECS installation

Kubernetes installation

Windows

Did this doc help with your installation?

Configure the integration

Important

nginx-config.yml sample files

Basic configuration

HTTP Basic authentication

Metrics with only one self-signed certificate

Environment variables replacement

Multi-instance monitoring

Configuration options for the integration

Find and use data

Metrics collected by the integration

NGINX Open Source

NGINX Plus

Inventory data

Tip

System metadata