Monitor NGINX on Kubernetes with OpenTelemetry

Monitor your NGINX servers running in Kubernetes clusters using the NRDOT collector (recommended) or 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 and receivercreator to dynamically monitor NGINX performance metrics, connection statistics, and server health across your containerized environment.

Set up NGINX monitoring

Choose your preferred collector and follow the steps:

Before you begin

Ensure you have:

Valid New Relic license key
Enable the HTTP stub status module on NGINX pod that needs to be monitored
Add labels app and role to each NGINX pod that needs to be monitored
For manifest install: complete the base Kubernetes OpenTelemetry manifest installation
For helm install: complete the base Kubernetes OpenTelemetry helm installation

Configure the NRDOT collector

Install the NRDOT collector using Kubernetes manifests or Helm.

After completing the base Kubernetes OpenTelemetry manifest installation, configure NGINX monitoring by following these steps:

Update the collector image to use NRDOT collector.
In both deployment.yaml and daemonset.yaml files in your local rendered directory, update the image to:
```
image: newrelic/nrdot-collector:latest
```

Update the deployment-configmap.yaml for NGINX monitoring:

Choose one of the following configuration options based on your monitoring requirements:

Important

This option monitors NGINX only and removes other Kubernetes metrics collection. You'll delete additional collectors later to prevent unwanted metric ingestion.

Replace the content under deployment-config.yaml: | with the below NGINX-specific configuration:

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`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
          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`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
          nginx.port: '<YOUR_STUB_STATUS_PORT>'  # Update to match your configuration

processors:
  batch:
    send_batch_max_size: 1000
    timeout: 30s
    send_batch_size: 800

  memory_limiter:
    check_interval: 1s
    limit_percentage: 80
    spike_limit_percentage: 25

  resource/cluster:
    attributes:
      - key: k8s.cluster.name
        value: "<CLUSTER_NAME>"  # Replace with your 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"])
  
  transform/metadata_nullify:
    metric_statements:
      - context: metric
        statements:
          - set(description, "")
          - set(unit, "")

exporters:
  otlp_http/newrelic:
    endpoint: "<YOUR_NEWRELIC_OTLP_ENDPOINT>"
    headers:
      api-key: ${env:NR_LICENSE_KEY}

service:
  extensions: [health_check, k8s_observer]
  pipelines:
    metrics/nginx:
      receivers: [receiver_creator/nginx]
      processors: [batch, resource/cluster, transform/nginx, transform/metadata_nullify, memory_limiter]
      exporters: [otlp_http/newrelic]

Configuration parameters

The following table describes the key configuration parameters:

Parameter	Description
`<YOUR_STUB_STATUS_PORT>`	Replace with your NGINX stub status port (for example 80, 8080)
`<YOUR_STUB_STATUS_PATH>`	Replace with your NGINX stub status path (for example basic_status)
`<CLUSTER_NAME>`	Replace with your Kubernetes cluster name for identification in New Relic
`<YOUR_NEWRELIC_OTLP_ENDPOINT>`	Update with your region's OTLP endpoint. See OTLP endpoint documentation
`app` and `role` labels	Pod labels used to identify NGINX pods (update the rule to match your labels)
`collection_interval`	Interval in seconds to collect metrics. The default value is set to `30s`
`send_batch_max_size`	Maximum number of metrics to batch before sending. The default value is set to `1000`
`timeout`	Timeout in seconds to wait before sending batched metrics. The default value is set to `30s`

Add the following sections to your existing deployment-configmap.yaml:

Extensions to add:

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  k8s_observer:
    auth_type: serviceAccount
    observe_pods: true
    observe_nodes: true

Receivers to add:

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`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
          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`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
          nginx.port: '<YOUR_STUB_STATUS_PORT>'  # Update to match your configuration

Processors to add:

processors:
  resource/cluster:
    attributes:
      - key: k8s.cluster.name
        value: "<CLUSTER_NAME>"  # Replace with your 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"])
  
  transform/metadata_nullify:
    metric_statements:
      - context: metric
        statements:
          - set(description, "")
          - set(unit, "")

Service pipelines to add:

service:
  extensions: [health_check, k8s_observer]  # Add to existing extensions
  pipelines:
    metrics/nginx:
      receivers: [receiver_creator/nginx]
      processors: [batch, resource/cluster, transform/nginx, transform/metadata_nullify, memory_limiter]
      exporters: [otlphttp/newrelic]

Configuration parameters

The following table describes the key configuration parameters:

Parameter	Description
`<YOUR_STUB_STATUS_PORT>`	Replace with your NGINX stub status port (for example 80, 8080)
`<YOUR_STUB_STATUS_PATH>`	Replace with your NGINX stub status path (for example basic_status)
`<CLUSTER_NAME>`	Replace with your Kubernetes cluster name for identification in New Relic
`app` and `role` labels	Pod labels used to identify NGINX pods (update the rule to match your labels)
`collection_interval`	Interval in seconds to collect metrics. The default value is set to `30s`
`memory_limiter`	Processor used in existing Kubernetes configuration to limit memory usage

Apply the updated manifests and restart the deployment.
1. For NGINX-only monitoring, run these commands:
  bash
```
$kubectl apply -n newrelic -R -f rendered
$kubectl delete daemonset nr-k8s-otel-collector-daemonset -n newrelic
$kubectl delete deployment nr-k8s-otel-collector-kube-state-metrics -n newrelic
$kubectl rollout restart deployment nr-k8s-otel-collector-deployment -n newrelic
```
2. For K8s + NGINX monitoring, run these commands:
  bash
```
$kubectl apply -n newrelic -R -f rendered
$kubectl rollout restart deployment nr-k8s-otel-collector-deployment -n newrelic
```

Update your values.yaml for the nr-k8s-otel-collector Helm chart with the following changes:

a. Update the collector image repository and tag to use NRDOT:

images:
  collector:
    repository: newrelic/nrdot-collector
    tag: latest

b. Add the following sections under deployment.extraConfig:

Important

In deployment.extraConfig, pipelines: must be defined at the root level — not nested under service:. The helm chart template maps extraConfig.pipelines into service.pipelines, and extraConfig.service.extensions into service.extensions.

Extensions:

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  k8s_observer:
    auth_type: serviceAccount
    observe_pods: true
    observe_nodes: true

Receivers:

receivers:
  receiver_creator/nginx:
    watch_observers: [k8s_observer]
    receivers:
      nginx:
        rule: type == "pod" && labels["app"] == "nginx" && labels["role"] == "reverse-proxy"  # Update with your labels
        resource_attributes:
          nginx.server.endpoint: 'http://`endpoint`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
          nginx.port: '<YOUR_STUB_STATUS_PORT>'  # Update to match your configuration
        config:
          endpoint: 'http://`endpoint`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
          metrics:
            nginx.requests:
              enabled: true
            nginx.connections_accepted:
              enabled: true
            nginx.connections_handled:
              enabled: true
            nginx.connections_current:
              enabled: true
          collection_interval: 30s

Processors:

processors:

  resource/cluster:
    attributes:
      - key: k8s.cluster.name
        value: "<CLUSTER_NAME>"  # Replace with your 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"])

  transform/metadata_nullify:
    metric_statements:
      - context: metric
        statements:
          - set(description, "")
          - set(unit, "")

Service extensions:

service:
  extensions: [health_check, k8s_observer]

Pipelines:

pipelines:
  metrics/nginx:
    receivers: [receiver_creator/nginx]
    processors: [batch, resource/cluster, transform/nginx, transform/metadata_nullify, memory_limiter]
    exporters: [otlphttp/newrelic]

Configuration parameters

The following table describes the key configuration parameters:

Parameter	Description
`<YOUR_STUB_STATUS_PORT>`	Replace with your NGINX stub status port (for example 80, 8080)
`<YOUR_STUB_STATUS_PATH>`	Replace with your NGINX stub status path (for example basic_status)
`<CLUSTER_NAME>`	Replace with your Kubernetes cluster name for identification in New Relic
`app` and `role` labels	Pod labels used to identify NGINX pods (update the rule to match your labels)
`collection_interval`	Interval in seconds to collect metrics. The default value is set to `30s`
`send_batch_max_size`	Maximum number of metrics to batch before sending. The default value is set to `1000`
`timeout`	Timeout in seconds to wait before sending batched metrics. The default value is set to `30s`
`memory_limiter`	Processor used to limit memory usage. `limit_percentage` sets the maximum memory percentage before limiting begins

Apply the updated values to your running Helm release:

bash

$helm upgrade nr-k8s-otel-collector newrelic/nr-k8s-otel-collector \
>  --namespace newrelic \
>  --reuse-values \
>  -f values.yaml

Before you begin

Ensure you have:

Valid New Relic license key
Enable the HTTP stub status module on NGINX pod that needs to be monitored
Add labels app and role to each NGINX pod that needs to be monitored
Helm installed

Configure the OpenTelemetry Collector

Deploy the OpenTelemetry Collector to your Kubernetes cluster using Helm. The collector will automatically discover and scrape metrics from your NGINX pods.

Download or create a custom values.yaml file based on the OpenTelemetry Collector values.yaml.

Update the following sections in your values.yaml file:

Set mode to deployment:
```
mode: deployment
```

Replace the image repository:

image:
  repository: otel/opentelemetry-collector-contrib

Configure cluster role:

clusterRole:
  create: true
  rules:
    - apiGroups: [""]
      resources: ["pods", "nodes", "nodes/stats", "nodes/proxy"]
      verbs: ["get", "list", "watch"]
    - apiGroups: ["apps"]
      resources: ["replicasets"]
      verbs: ["get", "list", "watch"]

Configure resource limits:

resources:
  limits:
    cpu: 250m
    memory: 512Mi

Replace the entire config section with NGINX monitoring configuration:

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`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
               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`:<YOUR_STUB_STATUS_PORT>/<YOUR_STUB_STATUS_PATH>'  # Update port and path as needed
               nginx.port: '<YOUR_STUB_STATUS_PORT>'  # Update to match your configuration

     processors:
       batch:
         send_batch_size: 1024
         timeout: 30s

       resource/cluster:
         attributes:
           - key: k8s.cluster.name
             value: "<CLUSTER_NAME>"  # Replace with your 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"])

       transform/metadata_nullify:
         metric_statements:
           - context: metric
             statements:
               - set(description, "")
               - set(unit, "")

     exporters:
       otlp_http/newrelic:
         endpoint: "<YOUR_NEWRELIC_OTLP_ENDPOINT>"  # Update for your region
         headers:
           api-key: "<YOUR_NEW_RELIC_LICENSE_KEY>"  # Replace with your New Relic license key

     service:
       extensions: [health_check, k8s_observer]
       pipelines:
         metrics/nginx:
           receivers: [receiver_creator/nginx]
           processors: [batch, resource/cluster, transform/nginx, transform/metadata_nullify]
           exporters: [otlp_http/newrelic]

Configuration parameters

The following table describes the key configuration parameters:

Parameter	Description
`<YOUR_STUB_STATUS_PORT>`	Replace with your NGINX stub status port (for example 80, 8080)
`<YOUR_STUB_STATUS_PATH>`	Replace with your NGINX stub status path (for example basic_status)
`<CLUSTER_NAME>`	Replace with your Kubernetes cluster name for identification in New Relic
`<YOUR_NEWRELIC_OTLP_ENDPOINT>`	Update with your region's OTLP endpoint. See OTLP endpoint documentation
`<YOUR_NEW_RELIC_LICENSE_KEY>`	Replace with your New Relic license key
`app` and `role` labels	Pod labels used to identify NGINX pods (update the rule to match your labels)
`basic_status`	NGINX stub status endpoint path (update if using a different path)
`collection_interval`	Interval in seconds to collect metrics. The default value is set to `30s`
`send_batch_size`	Number of metrics to batch before sending. The default value is set to `1024`
`timeout`	Timeout in seconds to wait before sending batched metrics. The default value is set to `30s`

Follow the OpenTelemetry Collector Helm chart installation guide to install the collector using your custom values.yaml file.

Example commands:

bash

$helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
$helm repo update
$helm upgrade my-opentelemetry-collector open-telemetry/opentelemetry-collector -f your-custom-values.yaml -n newrelic --create-namespace --install

Verify the pods are running:
bash
```
$kubectl get pods -n newrelic --watch
```
You should see the OpenTelemetry Collector pods in a Running state in the newrelic namespace.

Run an NRQL query in New Relic to verify data collection. Replace the cluster name with your actual cluster name:

FROM Metric
SELECT *
WHERE metricName LIKE 'nginx.%'
  AND instrumentation.provider = 'opentelemetry'
  AND k8s.cluster.name = 'your-cluster-name'
SINCE 10 minutes ago

View your data in New Relic

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.

Metrics and attributes reference

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 for detailed descriptions of all metrics, types, and resource attributes for Kubernetes deployments.

Next steps

Explore related monitoring:

Monitor NGINX Plus with OpenTelemetry - For commercial NGINX Plus deployments
Monitor self-hosted NGINX with OpenTelemetry - For traditional server deployments

Kubernetes-specific resources:

OpenTelemetry Collector on Kubernetes - Advanced collector configurations

Monitor NGINX on Kubernetes with OpenTelemetry

Set up NGINX monitoring

Before you begin

Configure the NRDOT collector

Manifest install

NGINX-only monitoring

Important

Configuration parameters

K8s + NGINX monitoring

Configuration parameters

Helm install

Important

Configuration parameters

Before you begin

Configure the OpenTelemetry Collector

Step 1: Create custom values.yaml configuration

Configuration parameters

Step 2: Install with Helm

Step 3: Verify deployment and data collection

View your data in New Relic

Metrics and attributes reference

Next steps

Monitor NGINX on Kubernetes with OpenTelemetry

Set up NGINX monitoring .css-21sua1{background:none;border:none;width:0;padding:0;}

Before you begin

Configure the NRDOT collector

Helm install

Before you begin

Configure the OpenTelemetry Collector

Step 1: Create custom values.yaml configuration

Step 2: Install with Helm

Step 3: Verify deployment and data collection

View your data in New Relic

Metrics and attributes reference

Next steps

Set up NGINX monitoring