Monitor self-hosted NGINX Plus with OpenTelemetry

Monitor your NGINX Plus servers running on a host using the OpenTelemetry Collector to send metrics and telemetry data to New Relic.

This integration leverages the OpenTelemetry prometheusreceiver and nginx-prometheus-exporter to monitor your NGINX Plus performance metrics, connection statistics, and server health. The rich HTTP API in NGINX Plus provides significantly more detailed metrics compared to the basic stub status module in standard NGINX.

Dashboard available through the New Relic NGINX OpenTelemetry Monitor quickstart.

Before you begin

Before you begin, ensure you have:

A New Relic account with a
NGINX Plus version R13 or higher
NGINX Plus with the HTTP API module enabled
NGINX Prometheus exporter installed and running alongside your NGINX Plus instance to expose HTTP API metrics in Prometheus format
OpenTelemetry Collector Contrib installed and running on a linux host
Network access from the linux host to:
- NGINX Plus HTTP API endpoint
- Anyone of the New Relic OTLP enpoint

Verify your setup

Check NGINX Plus version:

bash

$nginx -V 2>&1 | grep -o "nginx/[0-9.]*"

Expected output: nginx/1.25.0 or higher (R13+)

Check OpenTelemetry Collector:

bash

$otelcol-contrib --version

Expected output: Version information (minimum v0.88.0 required)

Test network connectivity:

bash

$# For US region
$curl -I https://otlp.nr-data.net:4318/v1/metrics
$# For EU region
$curl -I https://otlp.eu01.nr-data.net:4318/v1/metrics

Expected output: HTTP/2 405 (method not allowed is expected)

Step 1: Configure NGINX Plus

Configure and enable the HTTP API module to expose metrics from your NGINX Plus server.

Add the HTTP API configuration to your nginx.conf file. Typically add this within the http block:

server {
    listen 8080;
    server_name localhost;

    location /api {
        api write=on;
        # Restrict access as needed
        allow 127.0.0.1;
        deny all;
    }
}

Confirm the API endpoint path (including version) exposed in your configuration. Record the full API endpoint path (without the leading slash) and the port that serves it. Common defaults are api/9 on port 8080.

Use curl to confirm your API endpoint is reachable:

bash

$curl -I http://127.0.0.1:8080/api/9 2>/dev/null | head -n 1 | cut -d$' ' -f1,2

Expected output:

HTTP/1.1 200

If you see a different response, verify your NGINX Plus configuration and ensure the API module is properly enabled.

Step 2: Configure the OpenTelemetry Collector

Configure the OpenTelemetry Collector to scrape metrics from your NGINX Plus Prometheus exporter and send them to New Relic.

Install and configure the NGINX Prometheus exporter to expose NGINX Plus API metrics in Prometheus format:

bash

$# Download and install the exporter
$wget https://github.com/nginx/nginx-prometheus-exporter/releases/latest/download/nginx-prometheus-exporter_linux_amd64.tar.gz
$tar -xzf nginx-prometheus-exporter_linux_amd64.tar.gz
$sudo mv nginx-prometheus-exporter /usr/local/bin/
$
$# Run the exporter (customize the -nginx.scrape-uri as needed)
$nginx-prometheus-exporter -nginx.scrape-uri=http://127.0.0.1:8080/api

By default, the exporter runs on port 9113 and exposes metrics at /metrics.

Update your OpenTelemetry Collector configuration (typically located at /etc/otelcol-contrib/config.yaml). In the configuration snippet below:

Update the nginx.deployment.name value with a unique name to identify this NGINX Plus server in your New Relic account
Update the targets value to match your Prometheus exporter host and port (default is 127.0.0.1:9113)
Update the nginx.server.endpoint value to match your API status path and port

Update the filter/nginx_metrics as per your requirement to ingest additional metrics

Merge the receivers, processors, exporters, and service pipelines from the snippet below into your current configuration:

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: 'nginx-plus'
          scrape_interval: 30s
          static_configs:
            - targets: ['127.0.0.1:9113']
processors:
  batch:
    send_batch_size: 1024
    timeout: 30s
  filter/nginx_metrics:
    metrics:
      include:
        match_type: regexp
        metric_names:
          - "nginxplus_connections_.*"
          - "nginxplus_http_requests_.*"
          - "nginxplus_ssl_.*"
      exclude:
        match_type: regexp
        metric_names:
          - "nginxplus_server_.*"
          - "nginxplus_location_zone_.*"
          - "nginxplus_cache_.*"
          - "nginxplus_stream_server_.*"
          - "nginxplus_upstream_.*"
          - "nginxplus_stream_upstream_.*"
          - "nginxplus_stream_zone_sync_zone_.*"
          - "nginxplus_resolver_.*"
          - "nginxplus_limit_request_.*"
          - "nginxplus_limit_connection_.*"
          - "nginxplus_stream_limit_connection_.*"
          - "nginxplus_worker_.*"
  resource/nginx:
    attributes:
      - key: nginx.server.endpoint
        value: <API_ENDPOINT>
        action: insert
      - key: nginx.deployment.name
        value: <DEPLOYMENT_NAME>
        action: insert
  resourcedetection:
    detectors: [system]
    system:
      resource_attributes:
        host.name:
          enabled: true
        host.id:
          enabled: true
  transform/nginx:
    metric_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))
      - context: resource
        statements:
          - delete_key(attributes, "service.name")
  transform/metadata_nullify:
    metric_statements:
      - context: metric
        statements:
          - set(description, "")
          - set(unit, "")
exporters:
  otlp_http/newrelic:
    endpoint: ${env:NEWRELIC_OTLP_ENDPOINT}
    headers:
      api-key: ${env:NEWRELIC_LICENSE_KEY}
service:
  pipelines:
    metrics/nginx:
      receivers: [prometheus]
      processors: [batch, filter/nginx_metrics, resourcedetection, resource/nginx, transform/nginx, transform/metadata_nullify]
      exporters: [otlp_http/newrelic]

Save the file and ensure the otelcol-contrib system user can read it.

By default, the configuration collects only core metrics (connections, HTTP requests, and SSL). To enable additional metric categories like server zones, location zones, or cache metrics:

Identify the metrics you want to enable from the metrics list below. Note which category they belong to (e.g., HTTP Server Zones, Location Zones, Cache).

Move the corresponding metric prefix from exclude to include in the filter/nginx_metrics processor.

Example: Enable HTTP Server Zones metrics

Find this line in the exclude section:

filter/nginx_metrics:
  metrics:
    include:
    # existing include metrics
    exclude:
      match_type: regexp
      metric_names:
        - "nginxplus_server_.*"

Move it to the include section:

filter/nginx_metrics:
  metrics:
    include:
      match_type: regexp
      metric_names:
        - "nginxplus_connections_.*"
        - "nginxplus_http_requests_.*"
        - "nginxplus_ssl_.*"
        - "nginxplus_server_.*"  # Added to enable server zone metrics
    exclude:
      match_type: regexp
      metric_names:
        # Remove "nginxplus_server_.*" from here
        - "nginxplus_location_zone_.*"
        - "nginxplus_cache_.*"
        # ... rest of exclude list

Restart the collector after making changes:
bash
```
$sudo systemctl restart otelcol-contri.service
```

Step 3: Set environment variables for the collector

Inject your New Relic and OTLP endpoint into the collector service so the exporter can authenticate.

Write environment.conf with your OTLP endpoint. Replace YOUR_LICENSE_KEY with the New Relic license key and YOUR_OTLP_ENDPOINT with the appropriate endpoint for your region. Refer to the OTLP endpoint configuration documentation to select the right endpoint.

bash

$cat <<EOF | sudo tee /etc/systemd/system/otelcol-contrib.service.d/environment.conf
$[Service]
$Environment="NEWRELIC_OTLP_ENDPOINT=YOUR_OTLP_ENDPOINT"
$Environment="NEWRELIC_LICENSE_KEY=YOUR_LICENSE_KEY"
$EOF

Step 4: Verify data collection

Confirm that the OpenTelemetry Collector is successfully collecting NGINX Plus metrics and sending them to New Relic.

Monitor the collector logs to ensure it's running without errors:

bash

$sudo journalctl -u otelcol-contrib.service -n 20

Look for these success indicators:

✅ "Everything is ready. Begin running and processing data."
✅ "Scraping metrics" - Successfully collecting from Prometheus exporter
✅ "Exporting metrics" - Successfully sending to New Relic

Step 5: (Optional) Forward NGINX logs

Extend your collector configuration to include access and error logs if you want log events alongside metrics.

Configure NGINX Plus log format

Before forwarding logs, configure NGINX Plus to use a structured log format. Refer to the NGINX logging documentation for guidance on configuring access and error logs.

Configure the OpenTelemetry Collector for log forwarding

Note the full paths to your NGINX access and error log files. Defaults are usually /var/log/nginx/access.log and /var/log/nginx/error.log.

Update /etc/otelcol-contrib/config.yaml to add a filelog receiver and log pipeline:

receivers:
  prometheus:
    # existing Prometheus receiver configuration
  filelog/nginx_access_logs:
    include:
      - /var/log/nginx/access.log
  filelog/nginx_error_logs:
    include:
      - /var/log/nginx/error.log

processors:
  batch:
    # existing settings
  filter/nginx_metrics:
    # existing settings
  resourcedetection:
    # existing settings
  resource/nginx:
    # existing settings
  transform/nginx_metrics:
    # existing settings
  transform/nginx_access_logs:
    log_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))
          - set(attributes["logtype"], "nginx")
  transform/nginx_error_logs:
    log_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))
          - set(attributes["logtype"], "nginx-error")

exporters:
  # existing exporter setup

service:
  pipelines:
    metrics/nginx:
      receivers: [prometheus]
      processors: [batch, filter/nginx_metrics, resourcedetection, resource/nginx, transform/nginx_metrics, transform/metadata_nullify]
      exporters: [otlp_http/newrelic]
    logs/nginx-access:
      receivers: [filelog/nginx_access_logs]
      processors: [batch, resource/nginx, transform/nginx_access_logs]
      exporters: [otlp_http/newrelic]
    logs/nginx-error:
      receivers: [filelog/nginx_error_logs]
      processors: [batch, resource/nginx, transform/nginx_error_logs]
      exporters: [otlp_http/newrelic]

Grant the otelcol-contrib user read access to the log files:

bash

$sudo usermod -a -G adm otelcol-contrib
$sudo chmod 644 /var/log/nginx/access.log
$sudo chmod 644 /var/log/nginx/error.log

Restart the collector to apply the changes:
bash
```
$sudo systemctl restart otelcol-contrib
```

Find and use data

Go to one.newrelic.com > Integrations & Agents.
Select Dashboards, and click NGINX OTel overview dashboard.
In the popup window, select your account.
Click View dashboard, and see your NGINX Plus data in New Relic.

The NGINX Plus metrics are attached to the Metric event type. You can query this data for troubleshooting purposes or to create custom charts and dashboards.

Metrics collected

The OpenTelemetry Collector scrapes metrics from the NGINX Prometheus exporter, which exposes NGINX Plus HTTP API metrics in Prometheus format.

Below are the available NGINX Plus metrics:

Metric	Description	Type
`nginxplus_connections_accepted`	Accepted client connections	Sum
`nginxplus_connections_active`	Active client connections	Gauge
`nginxplus_connections_dropped`	Dropped client connections	Sum
`nginxplus_connections_idle`	Idle client connections	Gauge

Metric	Description	Type
`nginxplus_http_requests_total`	Total http requests	Sum
`nginxplus_http_requests_current`	Current http requests	Gauge

Metric	Description	Type
`nginxplus_ssl_handshakes`	Successful SSL handshakes	Sum
`nginxplus_ssl_handshakes_failed`	Failed SSL handshakes	Sum
`nginxplus_ssl_session_reuses`	Session reuses during SSL handshake	Sum

Important

Note: These metrics are disabled by default. To enable them, see (Optional) Enable additional metrics for OpenTelemetry Collector Contrib.

Metric	Description	Type
`nginxplus_server_zone_processing`	Client requests that are currently being processed	Gauge
`nginxplus_server_zone_requests`	Total client requests	Sum
`nginxplus_server_zone_responses`	Total responses sent to clients	Sum
`nginxplus_server_zone_responses_codes`	Total responses sent to clients by code	Sum
`nginxplus_server_zone_discarded`	Requests completed without sending a response	Sum
`nginxplus_server_zone_received`	Bytes received from clients	Sum
`nginxplus_server_zone_sent`	Bytes sent to clients	Sum
`nginxplus_server_ssl_handshakes`	Successful SSL handshakes	Sum
`nginxplus_server_ssl_handshakes_failed`	Failed SSL handshakes	Sum
`nginxplus_server_ssl_session_reuses`	Session reuses during SSL handshake	Sum

Important

Note: These metrics are disabled by default. To enable them, see (Optional) Enable additional metrics for OpenTelemetry Collector Contrib.

Metric	Description	Type
`nginxplus_location_zone_requests`	Total client requests	Sum
`nginxplus_location_zone_responses`	Total responses sent to clients	Sum
`nginxplus_location_zone_responses_codes`	Total responses sent to clients by code	Sum
`nginxplus_location_zone_discarded`	Requests completed without sending a response	Sum
`nginxplus_location_zone_received`	Bytes received from clients	Sum
`nginxplus_location_zone_sent`	Bytes sent to clients	Sum

Important

Note: These metrics are disabled by default. To enable them, see (Optional) Enable additional metrics for OpenTelemetry Collector Contrib.

Metric	Description	Type
`nginxplus_cache_size`	Total size of the cache	Gauge
`nginxplus_cache_max_size`	Maximum size of the cache	Gauge
`nginxplus_cache_cold`	Is the cache considered cold	Gauge
`nginxplus_cache_hit_responses`	Total number of cache hits	Sum
`nginxplus_cache_hit_bytes`	Total number of bytes returned from cache hits	Sum
`nginxplus_cache_stale_responses`	Total number of stale cache hits	Sum
`nginxplus_cache_stale_bytes`	Total number of bytes returned from stale cache hits	Sum
`nginxplus_cache_updating_responses`	Total number of cache hits while cache is updating	Sum
`nginxplus_cache_updating_bytes`	Total number of bytes returned from cache while cache is updating	Sum
`nginxplus_cache_revalidated_responses`	Total number of cache revalidations	Sum
`nginxplus_cache_revalidated_bytes`	Total number of bytes returned from cache revalidations	Sum
`nginxplus_cache_miss_responses`	Total number of cache misses	Sum
`nginxplus_cache_miss_bytes`	Total number of bytes returned from cache misses	Sum
`nginxplus_cache_expired_responses`	Total number of cache hits with expired TTL	Sum
`nginxplus_cache_expired_bytes`	Total number of bytes returned from cache hits with expired TTL	Sum
`nginxplus_cache_expired_responses_written`	Total number of cache hits with expired TTL written to cache	Sum
`nginxplus_cache_expired_bytes_written`	Total number of bytes written to cache from cache hits with expired TTL	Sum
`nginxplus_cache_bypass_responses`	Total number of cache bypasses	Sum
`nginxplus_cache_bypass_bytes`	Total number of bytes returned from cache bypasses	Sum
`nginxplus_cache_bypass_responses_written`	Total number of cache bypasses written to cache	Sum
`nginxplus_cache_bypass_bytes_written`	Total number of bytes written to cache from cache bypasses	Sum

Attribute	Description	Example Values
`server_zone`	The name of the server zone (applies to HTTP Server Zones metrics)	`example.com`, `api.example.com`
`code`	HTTP response status code (applies to response metrics)	`1xx`, `2xx`, `3xx`, `4xx`, `5xx`, `200`, `404`, `500`
`location_zone`	The name of the location zone	`/api`, `/images`, `/static`
`cache`	The name of the cache	`my_cache`, `static_cache`
`nginx.server.endpoint`	The NGINX Plus API endpoint URL	`http://localhost:8080/api`
`nginx.deployment.name`	A unique name to identify this NGINX Plus deployment	`production-web-01`, `staging-api`
`nginx.display.name`	A display-friendly name combining "server" prefix with deployment name	`server:production-web-01`
`host.name`	The hostname of the system where NGINX Plus is running	`web-server-01.example.com`
`host.id`	The unique identifier of the host system	`i-1234567890abcdef0`
`logtype`	The type of log being collected (applicable to logs only). Used by New Relic's built-in parsing rules. This attribute is only available when log forwarding is enabled.	`nginx` (for access logs), `nginx-error` (for error logs)

Next steps

Learn more about your data:

Find and query your NGINX data - Access dashboards, create custom queries, and set up alerts
Introduction to NRQL - Learn New Relic's query language for advanced data analysis
Create NRQL alert conditions - Set up custom alerts based on your NGINX Plus metrics

Explore related monitoring:

Monitor self-hosted NGINX with OpenTelemetry - For standard NGINX deployments
Monitor NGINX on Kubernetes with OpenTelemetry - For containerized environments
NGINX OpenTelemetry overview - Understand collected metrics, attributes, and use cases
OpenTelemetry best practices - Optimize your OpenTelemetry setup

NGINX Plus resources:

NGINX Prometheus exporter documentation - Technical details and advanced configuration
NGINX Plus API documentation - Complete API reference and features

Monitor self-hosted NGINX Plus with OpenTelemetry

Before you begin

Verify your setup

Step 1: Configure NGINX Plus

Enable HTTP API module

Test and reload configuration

Verify API endpoint

Step 2: Configure the OpenTelemetry Collector

Install NGINX Prometheus exporter

Configure collector configuration

(Optional) Enable additional metrics

Step 3: Set environment variables for the collector

Create systemd override directory

Set New Relic credentials

Restart the collector

Step 4: Verify data collection

Check collector logs

Generate test traffic

Verify data in New Relic

Step 5: (Optional) Forward NGINX logs

Configure NGINX Plus log format

Configure the OpenTelemetry Collector for log forwarding

Find and use data

Metrics collected

Connections

HTTP

SSL

HTTP Server Zones

Important

Location Zones

Important

Cache

Important

Attributes

Next steps

Monitor self-hosted NGINX Plus with OpenTelemetry

Before you begin .css-21sua1{background:none;border:none;width:0;padding:0;}

Verify your setup

Step 1: Configure NGINX Plus

Test and reload configuration

Verify API endpoint

Step 2: Configure the OpenTelemetry Collector

Install NGINX Prometheus exporter

Configure collector configuration

(Optional) Enable additional metrics

Step 3: Set environment variables for the collector

Create systemd override directory

Set New Relic credentials

Restart the collector

Step 4: Verify data collection

Check collector logs

Generate test traffic

Verify data in New Relic

Step 5: (Optional) Forward NGINX logs

Configure NGINX Plus log format

Configure the OpenTelemetry Collector for log forwarding

Find and use data

Metrics collected

Connections

HTTP

SSL

HTTP Server Zones

Location Zones

Cache

Attributes

Next steps

Before you begin