Integrating OpenTelemetry with Instana for NGINX

Trace context propagation

The native NGINX OpenTelemetry module uses the W3C Trace Context standard for distributed tracing. The module propagates trace context by using the following standard HTTP headers:

• traceparent - Contains the trace ID, parent span ID, and trace flags
• tracestate - Carries vendor-specific trace information

The module does not support Instana-specific headers for trace propagation:

• X-Instana-T (Trace ID)
• X-Instana-S (Span ID)
• X-Instana-L (Sampling level or decision)

When NGINX receives requests with W3C Trace Context headers, it automatically continues the trace. When NGINX makes upstream requests, it propagates the trace context by using the same W3C standard headers.

Sending data to agent OTLP endpoint

The Instana agent provides OTLP endpoints that can receive OpenTelemetry data directly from your NGINX server.

To send data to the Instana agent OTLP endpoint, configure your NGINX server as follows:

http {
    otel_exporter {
        endpoint localhost:4317;
    }

    otel_service_name your_service_name;
    otel_trace on;

    server {
        listen 80;
        location / {
            otel_trace_context propagate;
            proxy_pass http://backend;
        }
    }
}

Sending data to the backend OTLP endpoint

For environments where direct communication with the Instana agent is not possible, you can configure your NGINX server to send OpenTelemetry data directly to the Instana backend.

For more information, see Sending OpenTelemetry data to Instana.

To send data to the Instana backend OTLP endpoint, configure your NGINX server as follows:

http {
    otel_exporter {
        endpoint https://{instana-backend-otlp-acceptor-endpoint}:4317;
        headers x-instana-key={agent-key};
    }

    otel_service_name your_service_name;
    otel_trace on;

    server {
        listen 80;
        location / {
            otel_trace_context propagate;
            proxy_pass http://backend;
        }
    }
}

Replace {instana-backend-otlp-acceptor-endpoint} with your Instana backend endpoint and {agent-key} with your Instana agent key.

Prerequisites for Kubernetes deployment

Ensure that you have the following prerequisites:

• Kubernetes cluster (for example, Minikube, EKS, GKE, or AKS)
• Helm 3.x installed
• kubectl configured to access your cluster
• Instana backend OTLP endpoint and API key

Installing ingress-nginx with OpenTelemetry

1. Add the ingress-nginx Helm repository:

   helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
   helm repo update

2. Create a Helm values file (for example, ingress-nginx-values.yaml) with OpenTelemetry configuration:

   controller:
     config:
       http-snippet: |
         otel_exporter {
           endpoint https://{instana-backend-otlp-endpoint}:4317;
           header x-instana-key "{agent-key}";
         }
         otel_service_name "{your-service-name}";
         otel_resource_attr "service.namespace" "ingress-nginx";
         otel_resource_attr "k8s.cluster.name" "{your-cluster-name}";
       main-snippet: |
         load_module /etc/nginx/modules/ngx_otel_module.so;
       otel-span-attr: |
         http.request_id $request_id
         k8s.namespace $namespace
         k8s.ingress.name $ingress_name
         k8s.service.name $service_name
       otel-trace: "on"
       otel-trace-context: propagate
     image:
       digest: ""
       image: ingress-nginx-otel
       pullPolicy: Never
       registry: docker.io/library
       tag: "{version}"

   Replace the following values in the configuration:

   • {instana-backend-otlp-endpoint} - Your Instana backend OTLP endpoint (for example, otlp-red-saas.instana.io)
   • {agent-key} - Your Instana agent key
   • {your-cluster-name} - Your Kubernetes cluster name
   • {your-service-name} - Your service name
   • {version} - The ingress-nginx image version with OpenTelemetry support
   • Image settings - Configure according to your registry and image requirements

3. Install the ingress-nginx controller with the custom values:

   helm install ingress-nginx ingress-nginx/ingress-nginx \
     --namespace ingress-nginx \
     --create-namespace \
     --values ingress-nginx-values.yaml

4. Verify the installation:

   kubectl get pods -n ingress-nginx
   kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

Configuration options

The Helm values file includes several important configuration sections:

• http-snippet: Contains the main OpenTelemetry exporter configuration, including the Instana endpoint and authentication
• main-snippet: Loads the OpenTelemetry NGINX module
• otel-span-attr: Defines custom span attributes that are added to each trace, including Kubernetes-specific metadata
• otel-trace: Enables OpenTelemetry tracing
• otel-trace-context: Configures trace context propagation to downstream services

Custom span attributes

The configuration includes Kubernetes-specific attributes that provide valuable context in Instana:

These attributes help correlate traces with specific Kubernetes resources in the Instana UI.