diff --git a/src/content/docs/opentelemetry/nginx-plus/nginx-plus-otel.mdx b/src/content/docs/opentelemetry/nginx-plus/nginx-plus-otel.mdx new file mode 100644 index 00000000000..07b95e4c3d0 --- /dev/null +++ b/src/content/docs/opentelemetry/nginx-plus/nginx-plus-otel.mdx @@ -0,0 +1,1174 @@ +--- +title: 'Monitor self-hosted NGINX Plus with OpenTelemetry' +metaDescription: 'Send your NGINX Plus metrics to New Relic using the OpenTelemetry contrib collector.' +redirects: + - /docs/infrastructure/host-integrations/host-integrations-list/nginx/nginx-plus-otel +freshnessValidatedDate: never +--- + +Monitor your NGINX Plus servers running on a host using the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib) to send metrics and telemetry data to New Relic. + +This integration leverages the OpenTelemetry [prometheusreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver) and [nginx-prometheus-exporter](https://github.com/nginx/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. + +Image of the NGINX dashboard + +
+ Dashboard available through the [New Relic NGINX OpenTelemetry Monitor quickstart](https://newrelic.com/instant-observability/nginx-otel). +
+ +## Before you begin [#prerequisites] + +Before you begin, ensure you have: + +- A [New Relic account](https://newrelic.com/signup) with a +- NGINX Plus version [R13](https://docs.nginx.com/nginx/releases/#r13) or higher +- NGINX Plus with the [HTTP API](https://nginx.org/en/docs/http/ngx_http_api_module.html) module enabled +- [NGINX Prometheus exporter](https://github.com/nginx/nginx-prometheus-exporter) installed and running alongside your NGINX Plus instance to expose HTTP API metrics in Prometheus format +- [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases/latest) 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](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) 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-nginx] + +Configure and enable the [HTTP API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) 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: + + ```nginx + server { + listen 8080; + server_name localhost; + + location /api { + api write=on; + # Restrict access as needed + allow 127.0.0.1; + deny all; + } + } + ``` + + + + After updating `nginx.conf`, test and reload the service: + + ```bash + sudo nginx -t && sudo nginx -s reload + ``` + + + + 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-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](https://github.com/nginx/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: + + ```yaml + 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_.*" + - "nginxplus_server_.*" + - "nginxplus_location_zone_.*" + - "nginxplus_cache_.*" + exclude: + match_type: regexp + metric_names: + - "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: + action: insert + - key: nginx.deployment.name + value: + 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") + exporters: + otlphttp/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] + exporters: [otlphttp/newrelic] + ``` + + Save the file and ensure the `otelcol-contrib` system user can read it. + + + +## Step 3: Set environment variables for the collector [#set-environment] + +Inject your New Relic and OTLP endpoint into the collector service so the exporter can authenticate. + + + + Create a systemd override directory: + ```bash + sudo mkdir -p /etc/systemd/system/otelcol-contrib.service.d + ``` + + + + 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](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) to select the right endpoint. + + ```bash + cat < + + + Reload systemd and restart the collector: + ```bash + sudo systemctl daemon-reload + sudo systemctl restart otelcol-contrib.service + ``` + + + +## Step 4: Verify data collection [#verify-data] + +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 + + + + Generate test traffic to create metrics: + + ```bash + # Make a few requests to your NGINX Plus server + curl http://localhost + ``` + + + + Access your [NGINX dashboard](/docs/opentelemetry/nginx/find-and-query-your-data#find-data) to verify data collection. + + + +## Step 5: (Optional) Forward NGINX logs [#forward-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](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/) for guidance on configuring access and error logs. + +### Configure the OpenTelemetry Collector for log forwarding + +1. 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`. + +2. Update `/etc/otelcol-contrib/config.yaml` to add a `filelog` receiver and log pipeline: + + ```yaml + 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] + exporters: [otlphttp/newrelic] + logs/nginx-access: + receivers: [filelog/nginx_access_logs] + processors: [batch, resource/nginx, transform/nginx_access_logs] + exporters: [otlphttp/newrelic] + logs/nginx-error: + receivers: [filelog/nginx_error_logs] + processors: [batch, resource/nginx, transform/nginx_error_logs] + exporters: [otlphttp/newrelic] + ``` + +3. 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 + ``` + +4. Restart the collector to apply the changes: + + ```bash + sudo systemctl restart otelcol-contrib + ``` + +## Find and use data [#find-data] + +1. Go to **[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents**. +2. Select **Dashboards**, and click **NGINX OTel overview** dashboard. +3. In the popup window, select your account. +4. Click View dashboard, and see your NGINX Plus data in New Relic. + +The NGINX Plus metrics are attached to the `Metric` [event type](/docs/using-new-relic/data/understand-data/new-relic-data-types#events-new-relic). You can [query this data](/docs/using-new-relic/data/understand-data/query-new-relic-data) for troubleshooting purposes or to create custom charts and dashboards. + +## Metrics collected [#metrics] + +The OpenTelemetry Collector scrapes metrics from the [NGINX Prometheus exporter](https://github.com/nginx/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 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 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 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 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 +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 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](https://docs.newrelic.com/docs/logs/ui-data/built-log-parsing-rules/#nginx). This attribute is only available when log forwarding is enabled. + + `nginx` (for access logs), `nginx-error` (for error logs) +
+ + + + +## Next steps [#next-steps] + +**Learn more about your data:** +- [Find and query your NGINX data](/docs/opentelemetry/nginx/find-and-query-your-data/) - Access dashboards, create custom queries, and set up alerts +- [Introduction to NRQL](/docs/nrql/get-started/introduction-nrql-new-relics-query-language/) - Learn New Relic's query language for advanced data analysis +- [Create NRQL alert conditions](/docs/alerts/create-alert/create-alert-condition/create-nrql-alert-conditions/) - Set up custom alerts based on your NGINX Plus metrics + +**Explore related monitoring:** +- [Monitor self-hosted NGINX with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-host/) - For standard NGINX deployments +- [Monitor NGINX on Kubernetes with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-kubernetes/) - For containerized environments +- [NGINX OpenTelemetry overview](/docs/opentelemetry/nginx/nginx-otel-overview/) - Understand collected metrics, attributes, and use cases +- [OpenTelemetry best practices](/docs/opentelemetry/best-practices/opentelemetry-otlp/) - Optimize your OpenTelemetry setup + +**NGINX Plus resources:** +- [NGINX Prometheus exporter documentation](https://github.com/nginx/nginx-prometheus-exporter?tab=readme-ov-file#metrics-for-nginx-plus) - Technical details and advanced configuration +- [NGINX Plus API documentation](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/) - Complete API reference and features diff --git a/src/content/docs/opentelemetry/nginx/find-and-query-your-data.mdx b/src/content/docs/opentelemetry/nginx/find-and-query-your-data.mdx new file mode 100644 index 00000000000..836e23fc641 --- /dev/null +++ b/src/content/docs/opentelemetry/nginx/find-and-query-your-data.mdx @@ -0,0 +1,77 @@ +--- +title: 'Find and query your NGINX data in New Relic' +metaDescription: 'Learn how to access NGINX dashboards, query metrics with NRQL, create alerts, and troubleshoot data visibility issues in New Relic.' +freshnessValidatedDate: never +--- + +## View your NGINX data in New Relic [#find-data] + +Once your setup is complete and data is flowing, you can view your NGINX metrics and logs in New Relic and create custom alerts. + +**Method 1: Through Integrations & Agents** +1. Go to [one.newrelic.com](https://one.newrelic.com) > **Integrations & Agents** +2. Click **Dashboards** +3. Find and click **NGINX OTel overview** dashboard +4. Select your account and click **View dashboard** + +**Method 2: Through Infrastructure monitoring** +1. Go to [one.newrelic.com](https://one.newrelic.com) > **On-host integrations** +2. Search for your NGINX server by deployment name (e.g., `production-web-01`) +3. Click on your server to see detailed metrics + +## Query your data with NRQL + +You can create custom queries to analyze your NGINX data: + +**Example queries:** + +```sql +-- View request rate over time +FROM Metric SELECT rate(sum(nginx.requests), 1 minute) +WHERE nginx.deployment.name = 'production-web-01' +TIMESERIES + +-- Check connection states +FROM Metric SELECT latest(nginx.connections_current) +WHERE nginx.deployment.name = 'production-web-01' +FACET state + +-- Analyze log patterns (if log forwarding enabled) +FROM Log SELECT count(*) +WHERE nginx.deployment.name = 'production-web-01' +FACET status SINCE 1 hour ago +``` + +## Troubleshoot data visibility + +If you don't see data: + +1. Allow some time - Initial data ingestion can take a few minutes +2. Check the time range - Ensure you're looking at recent data +3. Verify deployment name - Use the exact name from your Collector config +4. Check for data with NRQL: + ```sql + FROM Metric SELECT * WHERE nginx.deployment.name LIKE '%production%' LIMIT 1 + ``` + +If data appears intermittent: + +1. Check Collector logs for errors: + ```bash + sudo journalctl -u otelcol-contrib -n 50 + ``` +2. Verify NGINX is generating traffic - Test with `curl http://localhost` +3. Check authentication - Ensure license key and endpoint are correct + +## Next steps [#next-steps] + +**Learn more about your data:** +- [NGINX OpenTelemetry metrics and attributes reference](/docs/opentelemetry/nginx/nginx-otel-metrics-reference/) - Complete metrics reference with descriptions and examples +- [Introduction to NRQL](/docs/nrql/get-started/introduction-nrql-new-relics-query-language/) - Learn New Relic's query language for advanced data analysis +- [Create NRQL alert conditions](/docs/alerts/create-alert/create-alert-condition/create-nrql-alert-conditions/) - Set up custom alerts based on your NGINX metrics + +**Setup guides:** +- [Monitor self-hosted NGINX with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-host/) - Complete setup for on-host deployments +- [Monitor NGINX on Kubernetes with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-kubernetes/) - Complete setup for Kubernetes deployments +- [NGINX OpenTelemetry overview](/docs/opentelemetry/nginx/nginx-otel-overview/) - Understand collected metrics, attributes, and use cases + diff --git a/src/content/docs/opentelemetry/nginx/nginx-otel-host.mdx b/src/content/docs/opentelemetry/nginx/nginx-otel-host.mdx new file mode 100644 index 00000000000..f4861900855 --- /dev/null +++ b/src/content/docs/opentelemetry/nginx/nginx-otel-host.mdx @@ -0,0 +1,544 @@ +--- +title: 'Monitor self-hosted NGINX with OpenTelemetry' +metaDescription: 'Complete step-by-step guide to configure NGINX monitoring with OpenTelemetry. Includes prerequisites, configuration, environment setup, and troubleshooting.' +redirects: + - /docs/infrastructure/host-integrations/host-integrations-list/nginx/nginx-otel-host +freshnessValidatedDate: never +--- + +This guide provides complete setup instructions for monitoring self-hosted NGINX with OpenTelemetry. Follow these steps to configure your NGINX server, OpenTelemetry Collector, and New Relic integration. + +{/* + **Before you start**: Review the [NGINX OpenTelemetry overview](/docs/opentelemetry/nginx/nginx-otel-overview/) to understand what you'll monitor and the benefits of this integration. + + **Other NGINX monitoring options:** + - To monitor **NGINX Plus**, see [Monitor NGINX Plus with OpenTelemetry](/docs/opentelemetry/nginx-plus/nginx-plus-otel/). + - To monitor **NGINX on Kubernetes**, see [Monitor NGINX on Kubernetes with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-kubernetes/). + + + +**Setup time**: approximately 20 minutes | **Skill level**: Intermediate (requires basic Linux/NGINX knowledge) + */} + +## Before you begin [#prerequisites] + +Before you start, ensure you have: + +- A [New Relic account](https://newrelic.com/signup) with a +- NGINX with the [HTTP stub status](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html) module enabled +- [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases/latest) installed and running on a Linux host +- Network access from the Linux host to: + - NGINX HTTP stub status endpoint + - New Relic's [OTLP endpoint](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) + +### Verify your setup + +Check NGINX status module: +```bash +nginx -V 2>&1 | grep -o with-http_stub_status_module +``` +Expected output: `with-http_stub_status_module` + +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:443 +``` +Expected output: HTTP response headers (not connection refused) + + +If any verification step fails, install the missing components before continuing. Need help installing the Collector? Check the [OpenTelemetry Collector installation guide](https://github.com/open-telemetry/opentelemetry-collector-contrib). + + +## Step 1: Configure NGINX stub status [#configure-nginx] + +Configure the [stub_status](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html) module to expose metrics from your NGINX server. This module provides basic performance statistics that OpenTelemetry will collect. + + + + Add this configuration to your NGINX config file (`/etc/nginx/nginx.conf`): + + ```nginx + server { + listen 8080; + server_name localhost; + + location /nginx_status { + stub_status on; + access_log off; # Don't log monitoring requests + allow 127.0.0.1; # Only allow localhost access + allow ::1; # Allow IPv6 localhost + deny all; # Deny all other access + } + } + ``` + + + + 1. Test your NGINX configuration: + ```bash + sudo nginx -t + ``` + + 2. If the test passes, reload NGINX: + ```bash + sudo nginx -s reload + ``` + + + + Test the endpoint: + ```bash + curl http://127.0.0.1:8080/nginx_status + ``` + + Expected output: + ``` + Active connections: 1 + server accepts handled requests + 16 16 16 + Reading: 0 Writing: 1 Waiting: 0 + ``` + + Test the HTTP response: + ```bash + curl -I http://127.0.0.1:8080/nginx_status + ``` + + Expected output: Should start with `HTTP/1.1 200 OK` + + + +## Step 2: Configure the OpenTelemetry Collector [#configure-collector] + +Configure the OpenTelemetry Collector to scrape metrics from your NGINX stub status endpoint and send them to New Relic. + + + + The OpenTelemetry Collector uses three main components for NGINX monitoring: + + - **Receivers** - Connect to your NGINX stub status endpoint to collect metrics + - **Processors** - Add server identification and batch metrics for efficient transmission + - **Exporters** - Send the processed metrics to your New Relic account via OTLP HTTP + + + + Before editing the configuration, you'll need two key pieces of information: + + 1. **Your stub status URL** - From Step 1 (default: `http://127.0.0.1:8080/nginx_status`) + 2. **A unique deployment name** - Choose a name that identifies this specific NGINX server (e.g., `production-web-01`, `staging-api`, `prod-lb-01`) + + The deployment name will appear in New Relic dashboards and helps you identify specific servers when you have multiple NGINX instances. + + + + + **Before editing:** Back up your existing configuration: `sudo cp /etc/otelcol-contrib/config.yaml /etc/otelcol-contrib/config.yaml.backup` + + + Edit your Collector configuration file (typically `/etc/otelcol-contrib/config.yaml`) and add the following sections. If you already have receivers, processors, or exporters sections, merge these with your existing configuration: + + **1. Configure the NGINX receiver:** + ```yaml + receivers: + nginx: + endpoint: http://127.0.0.1:8080/nginx_status # Replace with your stub status URL + collection_interval: 30s # How often to collect metrics + metrics: + nginx.requests: + enabled: true + nginx.connections_accepted: + enabled: true + nginx.connections_handled: + enabled: true + nginx.connections_current: + enabled: true + ``` + + **2. Configure processors for metadata and batching:** + ```yaml + processors: + # Detect system information (hostname, etc.) + resourcedetection: + detectors: [system] + system: + resource_attributes: + host.name: + enabled: true + host.id: + enabled: true + + # Add NGINX-specific identification + resource: + attributes: + - key: nginx.server.endpoint + value: "http://127.0.0.1:8080/nginx_status" # Replace with your endpoint + action: upsert + - key: nginx.deployment.name + value: "production-web-01" # Replace with your server name + action: upsert + + # Batch metrics for efficient sending + batch: + timeout: 30s + send_batch_size: 1024 + + # Transform metrics for better display in New Relic + transform/nginx_metrics: + metric_statements: + - context: resource + statements: + # Customize the display name as needed for your New Relic dashboard + - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":")) + ``` + + **3. Configure the New Relic exporter:** + ```yaml + exporters: + # Send metrics to New Relic via OTLP + otlphttp/newrelic: + endpoint: ${env:NEWRELIC_OTLP_ENDPOINT} + headers: + api-key: ${env:NEWRELIC_LICENSE_KEY} + ``` + + **4. Connect everything with a pipeline:** + ```yaml + service: + pipelines: + metrics: + receivers: [nginx] + processors: [resourcedetection, resource, batch, transform/nginx_metrics] + exporters: [otlphttp/newrelic] + ``` + + + + **Replace these values in the configuration above:** + + 1. **Endpoint URL**: Change `http://127.0.0.1:8080/nginx_status` to match your stub status configuration from Step 1 + 2. **Deployment name**: Replace `production-web-01` with a unique identifier for this NGINX server + + **Choosing a good deployment name:** + - Use descriptive names like `production-web-01`, `staging-api`, or `prod-lb-01` + - Must be unique across all NGINX servers within your New Relic account + - This name will appear in dashboards and help you identify specific servers + - Keep it short but meaningful for easy filtering and alerting + + + + + +## Step 3: Set up authentication [#set-environment] + +Configure secure authentication so the OpenTelemetry Collector can send data to your New Relic account. This step sets up environment variables to keep your credentials secure. + + + + Before configuring authentication, gather these two pieces of information: + + 1. ** Your License Key:** + - Go to [one.newrelic.com](https://one.newrelic.com) → **API Keys** + - Find "Ingest - License" section → Click **Show key** + - Copy the license key (starts with "NRAK-...") + + 2. ** Your OTLP Endpoint:** + Use the appropriate endpoint for your New Relic region. See [Configure endpoint, port, and protocol](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) for the complete list of endpoints and supported ports for your region. + For example: + - **US region**: `https://otlp.nr-data.net:4318` + - **EU region**: `https://otlp.eu01.nr-data.net:4318` + + + + + 1. **Create a systemd override directory:** + ```bash + sudo mkdir -p /etc/systemd/system/otelcol-contrib.service.d + ``` + + 2. **Create the environment configuration file:** + ```bash + cat < + + +## Step 4: Start monitoring [#start-monitoring] + +Now that everything is configured, start the OpenTelemetry Collector and verify that data is flowing to New Relic. + + + + 1. **Apply the configuration changes:** + ```bash + sudo systemctl daemon-reload + sudo systemctl restart otelcol-contrib.service + ``` + + 2. **Verify the service is running:** + ```bash + sudo systemctl status otelcol-contrib.service + ``` + Expected output: `Active: active (running)` with no recent errors + + + + 3. **Check startup logs:** + ```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 NGINX + - ✅ `"Exporting metrics"` - Successfully sending to New Relic + + 4. **Generate test traffic (to create metrics):** + ```bash + # Make a few requests to your NGINX server + curl http://localhost + ``` + + 5. Allow time for initial data to appear in New Relic, then [access your NGINX dashboard](/docs/opentelemetry/nginx/find-and-query-your-data#find-data) to verify data collection. + + + + +## Step 5: (Optional) Forward NGINX logs [#forward-logs] + +In addition to metrics, you can send NGINX [access and error logs](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/) to New Relic for comprehensive monitoring and troubleshooting. These logs complement the [core NGINX metrics](/docs/opentelemetry/nginx/nginx-otel-metrics-reference#core-metrics) and provide detailed request-level insights. + + +**Skip this step if:** You only need basic NGINX metrics and don't require detailed request logs. + + + + + First, configure NGINX to output JSON-formatted logs that are easier to parse and query. + + **Add this to your NGINX configuration (`/etc/nginx/nginx.conf`):** + + ```nginx + http { + # JSON log format for better parsing + log_format json_combined escape=json + '{' + '"time":"$time_local",' + '"remote_addr":"$remote_addr",' + '"request":"$request",' + '"status":$status,' + '"bytes_sent":$body_bytes_sent,' + '"request_time":$request_time,' + '"referer":"$http_referer",' + '"user_agent":"$http_user_agent"' + '}'; + + # Use the JSON format for access logs + access_log /var/log/nginx/access.log json_combined; + error_log /var/log/nginx/error.log warn; + + # Your existing configuration... + } + ``` + + **Reload NGINX to apply the changes:** + ```bash + sudo nginx -t && sudo nginx -s reload + ``` + + + + **Add these sections to your `/etc/otelcol-contrib/config.yaml`:** + + ```yaml + receivers: + # Your existing nginx receiver... + nginx: + # existing configuration... + + # Add log receivers + filelog/nginx_access: + include: + - /var/log/nginx/access.log + + filelog/nginx_error: + include: + - /var/log/nginx/error.log + + processors: + # Your existing processors... + + # Add log processor + 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") + + service: + pipelines: + # Your existing metrics pipeline... + metrics: + receivers: [nginx] + processors: [resourcedetection, resource, batch, transform/nginx_metrics] + exporters: [otlphttp/newrelic] + + # Add log pipelines + logs/nginx-access: + receivers: [filelog/nginx_access] + processors: [resource, batch, transform/nginx_access_logs] + exporters: [otlphttp/newrelic] + + logs/nginx-error: + receivers: [filelog/nginx_error] + processors: [resource, batch, transform/nginx_error_logs] + exporters: [otlphttp/newrelic] + ``` + + + + **Allow the Collector to read NGINX log files:** + ```bash + # Add collector user to adm group (has read access to logs) + sudo usermod -a -G adm otelcol-contrib + + # Ensure log files are readable + sudo chmod 644 /var/log/nginx/access.log + sudo chmod 644 /var/log/nginx/error.log + ``` + + **Restart the Collector:** + ```bash + sudo systemctl restart otelcol-contrib.service + ``` + + + + +## View your data in New Relic [#find-data] + +Once your setup is complete and data is flowing, you can access your NGINX metrics in New Relic dashboards and create custom alerts. + +For complete instructions on accessing dashboards, querying data with NRQL, and creating alerts, see [Find and query your NGINX data](/docs/opentelemetry/nginx/find-and-query-your-data). + +## Troubleshooting [#troubleshooting] + +If you encounter issues during setup, use this troubleshooting guide to diagnose and resolve common problems. + + + + **Getting 404 Not Found:** + ```bash + curl http://127.0.0.1:8080/nginx_status + ``` + + **Solutions:** + - Check that the location path matches your request URL + - Verify the configuration was added to the correct server block + - Run `sudo nginx -T | grep -A5 nginx_status` to confirm configuration is loaded + + **Getting 403 Forbidden:** + - Ensure you're testing from localhost (127.0.0.1) + - Check your `allow`/`deny` directives in the NGINX configuration + - Verify no other access restrictions are blocking the request + + **Connection refused:** + - Check if NGINX is running: `sudo systemctl status nginx` + - Verify port 8080 isn't blocked: `sudo netstat -tlnp | grep :8080` + - Check firewall rules if applicable + + + + **Check service status:** + ```bash + sudo systemctl status otelcol-contrib.service + sudo journalctl -u otelcol-contrib.service -n 50 + ``` + + **Common causes and fixes:** + - **YAML syntax errors** - Fix indentation and syntax issues + - **Missing environment variables** - Verify credentials are set in environment file + - **File permission issues** - Run `sudo chown otelcol-contrib:otelcol-contrib /etc/otelcol-contrib/config.yaml` + - **Invalid endpoint URLs** - Check NGINX endpoint and New Relic OTLP endpoint + - **Missing component configurations** - Ensure all receivers, processors, and exporters referenced in the service pipelines section are actually defined in their respective configuration sections above + + **Restart after fixes:** + ```bash + sudo systemctl restart otelcol-contrib.service + ``` + + + + **Step-by-step diagnosis:** + + 1. **Verify NGINX stub status works:** + ```bash + curl http://127.0.0.1:8080/nginx_status + ``` + Should return connection statistics. + + 2. **Check Collector is running and healthy:** + ```bash + sudo systemctl status otelcol-contrib.service + sudo journalctl -u otelcol-contrib -n 20 + ``` + The logs will provide detailed context if there are any configuration or runtime issues with the OpenTelemetry Collector. + + 3. **Check for data with NRQL:** + ```sql + FROM Metric SELECT * WHERE nginx.deployment.name LIKE '%production%' LIMIT 1 + ``` + + + + **No logs appearing in New Relic:** + ```bash + # Check Collector logs for file errors + sudo journalctl -u otelcol-contrib -f | grep -i "filelog\|error" + ``` + **Common issues:** + - **File permission errors** - Add collector to adm group: `sudo usermod -a -G adm otelcol-contrib` + - **Wrong file paths** - Verify log file locations in your config + + + +### Get help + +If you continue experiencing issues: + +1. Review [New Relic's OpenTelemetry best practices](/docs/opentelemetry/best-practices/opentelemetry-otlp/) +2. Search the [New Relic Explorers Hub](https://discuss.newrelic.com/) for similar issues + +## Next steps [#next-steps] + +**Learn more about your data:** +- [Find and query your NGINX data](/docs/opentelemetry/nginx/find-and-query-your-data/) - Access dashboards, create custom queries, and set up alerts +- [NGINX OpenTelemetry metrics and attributes reference](/docs/opentelemetry/nginx/nginx-otel-metrics-reference/) - Complete metrics reference with descriptions and examples +- [NGINX OpenTelemetry overview](/docs/opentelemetry/nginx/nginx-otel-overview/) - Understand collected metrics, attributes, and use cases +- [NGINX receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/nginxreceiver/documentation.md) - Technical details and advanced configuration + +**Explore related monitoring:** +- [Monitor NGINX Plus with OpenTelemetry](/docs/opentelemetry/nginx-plus/nginx-plus-otel/) - For commercial NGINX Plus deployments +- [Monitor NGINX on Kubernetes](/docs/opentelemetry/nginx/nginx-otel-kubernetes/) - For containerized environments + diff --git a/src/content/docs/opentelemetry/nginx/nginx-otel-kubernetes.mdx b/src/content/docs/opentelemetry/nginx/nginx-otel-kubernetes.mdx new file mode 100644 index 00000000000..4802c48a9e7 --- /dev/null +++ b/src/content/docs/opentelemetry/nginx/nginx-otel-kubernetes.mdx @@ -0,0 +1,221 @@ +--- +title: 'Monitor NGINX on Kubernetes with OpenTelemetry' +metaDescription: 'Send your NGINX metrics from Kubernetes to New Relic using the OpenTelemetry Collector.' +redirects: + - /docs/infrastructure/host-integrations/host-integrations-list/nginx/nginx-otel-kubernetes +freshnessValidatedDate: never +--- + +Monitor your NGINX servers running in Kubernetes clusters using the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib) to send metrics and telemetry data to New Relic. + +This Kubernetes-specific integration automatically discovers NGINX pods in your cluster and collects metrics without manual configuration for each instance. It leverages the OpenTelemetry [nginxreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/nginxreceiver) and [receivercreator](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/receivercreator) to dynamically monitor NGINX performance metrics, connection statistics, and server health across your containerized environment. + +## Before you begin [#prerequisites] + +Ensure you have: + +- A [New Relic account](https://newrelic.com/signup) with a +- Enable the [HTTP stub status](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html) module on NGINX pod that needs to be monitored +- Add labels `app` and `role` to each NGINX pod that needs to be monitored + +## Install and configure the OpenTelemetry Collector [#install-collector] + +Deploy the OpenTelemetry Collector to your Kubernetes cluster using Helm. The collector will automatically discover and scrape metrics from your NGINX pods. + + + + Create a Kubernetes secret to store your New Relic credentials. Replace `YOUR_LICENSE_KEY` and `YOUR_OTLP_ENDPOINT` with your actual values. Refer to the OTLP endpoint configuration [documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) to select the appropriate endpoint for your region. + + ```bash + kubectl create secret generic newrelic-licenses --from-literal=NEWRELIC_LICENSE_KEY=YOUR_LICENSE_KEY --from-literal=NEWRELIC_OTLP_ENDPOINT=YOUR_OTLP_ENDPOINT -n newrelic --create-namespace + ``` + + + + Create a `values.yaml` file to configure the OpenTelemetry Collector. Update the placeholders for your cluster name, NGINX pod labels, stub status port and path. + + ```yaml + opentelemetry-collector: + mode: deployment + + image: + repository: otel/opentelemetry-collector-contrib + pullPolicy: IfNotPresent + + command: + name: otelcol-contrib + + resources: + limits: + cpu: 500m + memory: 300Mi + requests: + cpu: 100m + memory: 100Mi + + extraEnvs: + - name: NEWRELIC_LICENSE_KEY + valueFrom: + secretKeyRef: + name: newrelic-licenses + key: NEWRELIC_LICENSE_KEY + - name: NEWRELIC_OTLP_ENDPOINT + valueFrom: + secretKeyRef: + name: newrelic-licenses + key: NEWRELIC_OTLP_ENDPOINT + - name: K8S_NODE_NAME + valueFrom: + fieldRef: + fieldPath: spec.nodeName + - name: K8S_CLUSTER_NAME + value: nginx-cluster # Update with your cluster name + + clusterRole: + create: true + rules: + - apiGroups: [""] + resources: ["pods", "nodes", "nodes/stats", "nodes/proxy"] + verbs: ["get", "list", "watch"] + - apiGroups: ["apps"] + resources: ["replicasets"] + verbs: ["get", "list", "watch"] + clusterRoleBinding: + name: "" + + config: + extensions: + health_check: + endpoint: 0.0.0.0:13133 + k8s_observer: + auth_type: serviceAccount + observe_pods: true + observe_nodes: true + + receivers: + receiver_creator/nginx: + watch_observers: [k8s_observer] + receivers: + nginx: + rule: type == "pod" && labels["app"] == "nginx" && labels["role"] == "reverse-proxy" # Update with your labels + config: + endpoint: 'http://`endpoint`:/status' + metrics: + nginx.requests: + enabled: true + nginx.connections_accepted: + enabled: true + nginx.connections_handled: + enabled: true + nginx.connections_current: + enabled: true + collection_interval: 30s + resource_attributes: + nginx.server.endpoint: 'http://`endpoint`:/status' + nginx.port: '' + + processors: + batch: + send_batch_size: 1024 + timeout: 30s + + resource/cluster: + attributes: + - key: k8s.cluster.name + value: "${env:K8S_CLUSTER_NAME}" + action: insert + + transform/nginx: + metric_statements: + - context: resource + statements: + - set(attributes["nginx.display.name"], Concat([ + "server", + "k8s", + attributes["k8s.cluster.name"], + attributes["k8s.namespace.name"], + "pod", + attributes["k8s.pod.name"], + "nginx", + attributes["nginx.port"] + ], ":")) + - set(attributes["nginx.deployment.name"], attributes["k8s.pod.name"]) + + exporters: + otlphttp: + endpoint: "${env:NEWRELIC_OTLP_ENDPOINT}" + headers: + api-key: "${env:NEWRELIC_LICENSE_KEY}" + + service: + extensions: [health_check, k8s_observer] + pipelines: + metrics/nginx: + receivers: [receiver_creator/nginx] + processors: [batch, resource/cluster, transform/nginx] + exporters: [otlphttp] + ``` + + + + Install the [Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts) using your values.yaml file. + + ```bash + helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts + helm repo update + helm upgrade --install nginx-otel-collector open-telemetry/opentelemetry-collector --namespace newrelic --create-namespace -f values.yaml + ``` + + + + 1. **Ensure the pods have successfully spun up:** + + ```bash + kubectl get pods -n newrelic --watch + ``` + + You should see pods with names like `nginx-otel-collector-` in a `Running` state in the `newrelic` namespace. + + 2. **Run an NRQL query in New Relic to confirm data is arriving.** Replace the cluster name with the value you set in the values file: + + ```sql + FROM Metric + SELECT * + WHERE metricName LIKE 'nginx.%' + AND instrumentation.provider = 'opentelemetry' + AND k8s.cluster.name = 'nginx-cluster' + SINCE 10 minutes ago + ``` + + + +## Find and use data [#find-data] + +1. Go to **[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents**. +2. Select **Dashboards**, and click **NGINX OTel overview dashboard**. +3. In the popup window, select your account. +4. Click View dashboard, and see your NGINX data in New Relic. + +The NGINX metrics are attached to the `Metric` [event type](/docs/using-new-relic/data/understand-data/new-relic-data-types#events-new-relic). You can [query this data](/docs/using-new-relic/data/understand-data/query-new-relic-data) for troubleshooting purposes or to create custom charts and dashboards. + +## Metrics and attributes reference [#metrics] + +This integration collects the same core NGINX metrics as the on-host deployment, with additional Kubernetes-specific resource attributes for cluster, namespace, and pod identification. + +**For complete metrics and attributes reference:** See [NGINX OpenTelemetry metrics and attributes reference](/docs/opentelemetry/nginx/nginx-otel-metrics-reference/) for detailed descriptions of all metrics, types, and resource attributes for Kubernetes deployments. + +## Next steps [#next-steps] + +**Learn more about your data:** +- [Find and query your NGINX data](/docs/opentelemetry/nginx/find-and-query-your-data/) - Access dashboards, create custom queries, and set up alerts +- [NGINX OpenTelemetry metrics and attributes reference](/docs/opentelemetry/nginx/nginx-otel-metrics-reference/) - Complete metrics reference with descriptions and examples +- [NGINX OpenTelemetry overview](/docs/opentelemetry/nginx/nginx-otel-overview/) - Understand collected metrics, attributes, and use cases +- [NGINX receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/nginxreceiver/documentation.md) - Technical details and advanced configuration + +**Explore related monitoring:** +- [Monitor NGINX Plus with OpenTelemetry](/docs/opentelemetry/nginx-plus/nginx-plus-otel/) - For commercial NGINX Plus deployments +- [Monitor self-hosted NGINX with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-host/) - For traditional server deployments +- [OpenTelemetry best practices](/docs/opentelemetry/best-practices/opentelemetry-otlp/) - Optimize your OpenTelemetry setup + +**Kubernetes-specific resources:** +- [OpenTelemetry Collector on Kubernetes](https://opentelemetry.io/docs/kubernetes/) - Advanced collector configurations diff --git a/src/content/docs/opentelemetry/nginx/nginx-otel-metrics-reference.mdx b/src/content/docs/opentelemetry/nginx/nginx-otel-metrics-reference.mdx new file mode 100644 index 00000000000..f0bb225325e --- /dev/null +++ b/src/content/docs/opentelemetry/nginx/nginx-otel-metrics-reference.mdx @@ -0,0 +1,299 @@ +--- +title: 'NGINX OpenTelemetry metrics and attributes reference' +metaDescription: 'Complete reference of NGINX metrics collected via OpenTelemetry, including resource attributes for both on-host and Kubernetes deployments.' +freshnessValidatedDate: never +--- + +This reference covers all metrics and attributes collected by the OpenTelemetry NGINX receiver, applicable to both on-host and Kubernetes deployments. + +## Core NGINX metrics [#core-metrics] + +The OpenTelemetry Collector Contrib's [nginxreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/nginxreceiver) collects the following metrics from the NGINX stub status module: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Metric + + Description + + Type +
+ `nginx.connections_accepted` + + The total number of accepted client connections. Use this to track connection acceptance rates over time. + + Sum +
+ `nginx.connections_handled` + + The total number of handled connections. Generally, the parameter value is the same as nginx.connections_accepted unless some resource limits have been reached (for example, the worker_connections limit). A gap between accepted and handled suggests resource constraints. + + Sum +
+ `nginx.connections_current` + + The current number of nginx connections by state. States include: active (total active connections), reading (reading request headers), writing (writing responses), waiting (keep-alive connections waiting for next request). + + Sum +
+ `nginx.requests` + + Total number of requests made to the server since it started. Use rate calculations to derive requests per second for performance monitoring. + + Sum +
+ +**Capacity planning tips:** +- High `waiting` connections may indicate keep-alive tuning opportunities +- Gap between `accepted` and `handled` connections suggests resource constraints +- Request-to-connection ratios help optimize worker configurations + +## Resource attributes [#resource-attributes] + +Resource attributes provide context about your NGINX deployment and vary depending on whether you're using on-host or Kubernetes deployment. + +### Common attributes [#common-attributes] + + + + + + + + + + + + + + + + + + + + + +
+ Attribute + + Description + + Example Values +
+ `state` + + The state of a connection (applicable to `nginx.connections_current` metric) + + `active`, `reading`, `writing`, `waiting` +
+ `nginx.server.endpoint` + + The NGINX stub status endpoint URL + + `http://localhost:8080/stub_status` +
+ +### On-host deployment attributes [#on-host-attributes] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Attribute + + Description + + Example Values +
+ `nginx.deployment.name` + + A unique name to identify this NGINX 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 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](https://docs.newrelic.com/docs/logs/ui-data/built-log-parsing-rules/#nginx). This attribute is only available when log forwarding is enabled. + + `nginx` (for access logs), `nginx-error` (for error logs) +
+ +### Kubernetes deployment attributes [#kubernetes-attributes] + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Attribute + + Description + + Example Values +
+ `k8s.cluster.name` + + The name of the Kubernetes cluster + + `nginx-cluster`, `production-k8s` +
+ `k8s.namespace.name` + + The Kubernetes namespace where the NGINX pod is running + + `default`, `web-services`, `production` +
+ `k8s.pod.name` + + The name of the Kubernetes pod running NGINX + + `nginx-deployment-7d4b8c6f9-x5z8w` +
+ `nginx.deployment.name` + + Set to the pod name for Kubernetes deployments + + `nginx-deployment-7d4b8c6f9-x5z8w` +
+ `nginx.display.name` + + A comprehensive display name including cluster, namespace, and pod information + + `server:k8s:nginx-cluster:default:pod:nginx-deployment-7d4b8c6f9-x5z8w:nginx:8080` +
+ +## Metric collection details [#collection-details] + +### Collection frequency +- **Default interval**: 30 seconds +- **Configurable**: Can be adjusted in the OpenTelemetry Collector configuration + +### Data source +All metrics are collected from the NGINX [stub_status module](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html), which must be enabled and configured to expose an HTTP endpoint. + +### Metric types +- **Sum metrics**: Cumulative values that represent totals over time +- **Rate calculations**: Use New Relic's `rate()` function to convert cumulative metrics to per-second rates for monitoring + +## Related documentation [#related-docs] + +**Setup guides:** +- [Monitor NGINX on self-hosted environments](/docs/opentelemetry/nginx/nginx-otel-host/) - Complete setup for on-host deployments +- [Monitor NGINX on Kubernetes](/docs/opentelemetry/nginx/nginx-otel-kubernetes/) - Complete setup for Kubernetes deployments + +**Data usage:** +- [Find and query your NGINX data](/docs/opentelemetry/nginx/find-and-query-your-data/) - Dashboards, NRQL queries, and alerts + +**Technical reference:** +- [NGINX receiver documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/nginxreceiver/documentation.md) - OpenTelemetry technical details \ No newline at end of file diff --git a/src/content/docs/opentelemetry/nginx/nginx-otel-overview.mdx b/src/content/docs/opentelemetry/nginx/nginx-otel-overview.mdx new file mode 100644 index 00000000000..c2755dd9a4d --- /dev/null +++ b/src/content/docs/opentelemetry/nginx/nginx-otel-overview.mdx @@ -0,0 +1,66 @@ +--- +title: 'NGINX OpenTelemetry monitoring overview' +metaDescription: 'Learn about monitoring self-hosted NGINX with OpenTelemetry, its benefits, use cases, and collected metrics for comprehensive observability.' +redirects: + - /docs/infrastructure/host-integrations/host-integrations-list/nginx/nginx-otel-overview +freshnessValidatedDate: never +--- + +Get complete visibility into your NGINX web servers with OpenTelemetry integration. This solution uses the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib) and [nginxreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/nginxreceiver) to automatically collect and send performance data, connection statistics, and operational insights to New Relic. + +Image of the NGINX dashboard + +
+ Dashboard available through the [New Relic NGINX OpenTelemetry Monitor quickstart](https://newrelic.com/instant-observability/nginx-otel). +
+ + + - To monitor **NGINX Plus**, see [Monitor NGINX Plus with OpenTelemetry](/docs/opentelemetry/nginx-plus/nginx-plus-otel/). + - To monitor **NGINX on Kubernetes**, see [Monitor NGINX on Kubernetes with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-kubernetes/). + - Ready to implement? Continue to [NGINX OpenTelemetry setup guide](/docs/opentelemetry/nginx/nginx-otel-host/). + + +## Why monitor NGINX with OpenTelemetry? [#why-monitor] + +NGINX monitoring is essential for maintaining web application performance and reliability. OpenTelemetry provides a standardized approach to collect and analyze this critical data. + +### Key benefits + +- **Performance optimization**: Identify bottlenecks, track response times, make data-driven scaling decisions +- **Proactive monitoring**: Get alerts before user impact, detect issues early +- **Operational insights**: Understand traffic patterns, track SLA compliance, maintain audit trails +- **Future-proof**: Open-source OpenTelemetry standard, vendor-neutral integration + +### Use case + +Whether you're running an e-commerce website, API gateway, or content delivery platform, NGINX monitoring helps you maintain fast, reliable web services. Get notified when your checkout process slows down, detect when your API endpoints are overwhelmed, or identify which geographic regions are experiencing issues. This monitoring is essential for websites handling customer transactions, mobile app backends, microservices architectures, and any web application where downtime or slow performance directly impacts your users and business. + +## Available metrics [#metrics] + +The OpenTelemetry Collector automatically collects key NGINX performance metrics including connection statistics, request counts, and server health indicators. + +**Key metrics collected:** +- **Connection metrics** - Active, accepted, handled connections and their states +- **Request metrics** - Total requests and request rates over time +- **Server health** - Connection efficiency and performance indicators + +**For complete metrics and attributes reference:** See [NGINX OpenTelemetry metrics and attributes reference](/docs/opentelemetry/nginx/nginx-otel-metrics-reference/) for detailed descriptions, metric types, and resource attributes for both on-host and Kubernetes deployments. + +## Next steps [#next-steps] + +Ready to start monitoring your NGINX servers? + +**Continue to the implementation guide:** +- [NGINX OpenTelemetry setup guide](/docs/opentelemetry/nginx/nginx-otel-host/) - Complete step-by-step instructions for configuration, setup, and troubleshooting + +**Explore related monitoring options:** +- [Monitor NGINX Plus with OpenTelemetry](/docs/opentelemetry/nginx-plus/nginx-plus-otel/) - For commercial NGINX Plus deployments +- [Monitor NGINX on Kubernetes](/docs/opentelemetry/nginx/nginx-otel-kubernetes/) - For containerized environments + +**Learn more about OpenTelemetry:** +- [OpenTelemetry best practices](/docs/opentelemetry/best-practices/opentelemetry-otlp/) - Optimize your OpenTelemetry setup +- [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/) - Comprehensive collector reference \ No newline at end of file diff --git a/src/install/nginx/whatsNext.mdx b/src/install/nginx/whatsNext.mdx index 06725ce1423..7c32582579b 100644 --- a/src/install/nginx/whatsNext.mdx +++ b/src/install/nginx/whatsNext.mdx @@ -453,3 +453,9 @@ The NGINX integration collects the following metrics: + +--- + + + - To monitor NGINX using OpenTelemetry, see [Monitor NGINX with OpenTelemetry](/docs/opentelemetry/nginx/nginx-otel-overview/). + diff --git a/src/nav/opentelemetry.yml b/src/nav/opentelemetry.yml index da4af694dca..4bc981e3104 100644 --- a/src/nav/opentelemetry.yml +++ b/src/nav/opentelemetry.yml @@ -43,3 +43,21 @@ pages: path: /docs/opentelemetry/best-practices/opentelemetry-best-practices-resources - title: Manage data ingest volume path: /docs/opentelemetry/best-practices/opentelemetry-manage-data-ingest-volume + - title: OpenTelemetry integrations + pages: + - title: NGINX integration + pages: + - title: Overview + path: /docs/opentelemetry/nginx/nginx-otel-overview + - title: Self-hosted + path: /docs/opentelemetry/nginx/nginx-otel-host + - title: Kubernetes + path: /docs/opentelemetry/nginx/nginx-otel-kubernetes + - title: Find and query your data + path: /docs/opentelemetry/nginx/find-and-query-your-data + - title: Metrics and attributes reference + path: /docs/opentelemetry/nginx/nginx-otel-metrics-reference + - title: NGINX Plus integration + pages: + - title: Self-hosted + path: /docs/opentelemetry/nginx-plus/nginx-plus-otel diff --git a/static/images/opentelemetry_screenshot-nginx-dashboard.webp b/static/images/opentelemetry_screenshot-nginx-dashboard.webp new file mode 100644 index 00000000000..929061adada Binary files /dev/null and b/static/images/opentelemetry_screenshot-nginx-dashboard.webp differ