Nginx OpenTelemetry Instrumentation

This guide provides step-by-step instructions for setting up OpenTelemetry (OTel) instrumentation in your Nginx web server to enable distributed tracing. The official ngx_otel_module dynamic module allows Nginx to participate in distributed traces by creating spans for proxied requests and propagating W3C trace context headers. Once your telemetry data is captured, you can configure an exporter to send it to Atatus via the OTel Collector for advanced monitoring and insights. The process of setting up OpenTelemetry in Nginx involves three key steps: Installing the OTel Module: Add the ngx_otel_module dynamic module to your Nginx installation.
Configuring the Exporter: Set up Nginx to export traces to the OTel Collector, which forwards them to Atatus.
Validating the Setup: Verify that the configuration is working and that your data is being correctly sent to Atatus.

Requirements

NGINX 1.25.3 or newer
OpenTelemetry Collector

Install NGINX with the OTel Module

Choose the installation method that matches your deployment environment.

Host / VM (Alpine Linux)

Add the nginx.org repository and install the module:

# Add nginx.org signing key
wget -qO /etc/apk/keys/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub

# Add nginx.org mainline repository
ALPINE_VERSION=$(cat /etc/alpine-release | cut -d. -f1,2)
echo "https://nginx.org/packages/mainline/alpine/v${ALPINE_VERSION}/main" >> /etc/apk/repositories

# Install the OTel module
apk update && apk add nginx-module-otel

Host / VM (Debian / Ubuntu)

Add the nginx.org repository and install the module:

# Install prerequisites
apt install -y curl gnupg2 ca-certificates lsb-release

# Add nginx.org signing key
curl -fsSL https://nginx.org/keys/nginx_signing.key \
  | gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

# Add nginx.org mainline repository
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
  http://nginx.org/packages/mainline/$(lsb_release -is | tr '[:upper:]' '[:lower:]') \
  $(lsb_release -cs) nginx" > /etc/apt/sources.list.d/nginx.list

# Install the OTel module
apt update && apt install -y nginx-module-otel

Docker

Create a Dockerfile that adds the OTel module to the official Nginx Alpine image:

FROM nginx:1.27-alpine

# Add nginx.org repo and install OTel module
RUN echo 'https://nginx.org/packages/mainline/alpine/v3.21/main' >> /etc/apk/repositories \
    && wget -qO /etc/apk/keys/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub \
    && apk add --no-cache nginx-module-otel

RUN rm /etc/nginx/conf.d/default.conf
COPY nginx.conf /etc/nginx/nginx.conf

EXPOSE 80

Build the image:

docker build -t nginx-otel .

Kubernetes

Use the same Docker image from the Docker section above and deploy it as a Kubernetes Deployment. The OTel Collector can run as a sidecar container in the same pod or as a separate service in the cluster.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-otel
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-otel
  template:
    metadata:
      labels:
        app: nginx-otel
    spec:
      containers:
        - name: nginx
          image: nginx-otel:latest
          ports:
            - containerPort: 80
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:latest
          args: ["--config", "/etc/otel/config.yaml"]
          ports:
            - containerPort: 4317
          volumeMounts:
            - name: otel-config
              mountPath: /etc/otel
      volumes:
        - name: otel-config
          configMap:
            name: otel-collector-config

In this sidecar setup, the Nginx container sends traces to localhost:4317 (the OTel Collector running in the same pod).

Prerequisites: Set Up the OTel Collector

The Nginx OTel module exports traces via OTLP/gRPC and does not support custom authentication headers, so an OTel Collector is required to add the Atatus API key and forward traces to Atatus. Before configuring Nginx, set up the OTel Collector by following the OTel Collector Configuration guide. Once the Collector is running and forwarding traces to Atatus, proceed with the steps below.

Send Telemetry Traces to Atatus

Step 1: Configure Nginx

Add the following to your nginx.conf, replacing <OTEL_COLLECTOR_HOST> with the address of your OTel Collector:

load_module modules/ngx_otel_module.so;

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    # --- OpenTelemetry Configuration ---
    otel_exporter {
        endpoint <OTEL_COLLECTOR_HOST>:4317;
    }

    # highlight-start
    otel_service_name my-nginx;
    otel_trace on;
    otel_trace_context propagate;
    # highlight-end

    server {
        listen 80;

        location / {
            proxy_pass http://your-upstream-service;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

OTel Collector endpoint by deployment environment:

Environment	`<OTEL_COLLECTOR_HOST>`	Notes
Host / VM	`localhost`	Collector running on the same machine
Docker Compose	`<collector-service-name>` (e.g., `otel-collector`)	Docker resolves container names via internal DNS within the same network
Kubernetes (sidecar)	`localhost`	Collector container in the same pod shares the network namespace
Kubernetes (separate service)	`<service-name>.<namespace>.svc.cluster.local`	K8s DNS for a collector deployed as its own Service

Replace my-nginx with a descriptive service name for your Nginx instance. Key directives:

Directive	Description
`otel_exporter { endpoint ... }`	OTLP/gRPC endpoint of the OTel Collector
`otel_service_name`	Service name that appears in your traces
`otel_trace on`	Enables trace generation for requests
`otel_trace_context propagate`	Propagates W3C `traceparent` and `tracestate` headers for distributed tracing

You can disable tracing for specific locations (e.g., health checks) to reduce noise:

location /health {
    otel_trace off;
    return 200 '{"status":"healthy"}';
    add_header Content-Type application/json;
}

Step 2: Verify

Send a request through Nginx and check that traces appear in Atatus:

curl http://localhost/your-endpoint

Traces should appear in your Atatus dashboard under the service name you configured in otel_service_name.

Additional Configuration

Custom Span Attributes

Add custom attributes to your spans for better filtering:

http {
    otel_span_attr deployment.environment $host;
    otel_span_attr http.route $uri;

    server {
        location /api/ {
            otel_span_name "api_request";
            otel_span_attr api.version "v1";
            proxy_pass http://backend;
        }
    }
}

Sampling

Control the trace sampling rate using a variable:

# Sample 25% of requests
split_clients $request_id $otel_sample {
    25% on;
    *   off;
}

http {
    otel_trace $otel_sample;
}

Exporter Tuning

Adjust the export batch settings for high-traffic environments:

otel_exporter {
    endpoint <OTEL_COLLECTOR_HOST>:4317;
    interval 5s;
    batch_size 512;
    batch_count 4;
}

​Requirements

​Install NGINX with the OTel Module

​Host / VM (Alpine Linux)

​Host / VM (Debian / Ubuntu)

​Docker

​Kubernetes

​Prerequisites: Set Up the OTel Collector

​Send Telemetry Traces to Atatus

​Step 1: Configure Nginx

​Step 2: Verify

​Additional Configuration

​Custom Span Attributes

​Sampling

​Exporter Tuning