Integration von „ OpenTelemetry “ mit „ Instana “ für „ NGINX “

Tracekontextweitergabe

Das native Modul „ NGINX “ ( OpenTelemetry ) nutzt den Standard „ W3C Trace Context“ für die verteilte Ablaufverfolgung. Das Modul überträgt den Trace-Kontext mithilfe der folgenden Standard- HTTP -Header:

• traceparent - Enthält die Trace-ID, die übergeordnete Span-ID und die Trace-Flags
• tracestate - Enthält herstellerspezifische Trace-Informationen

Das Modul unterstützt keine „ Instana “-spezifischen Header für die Trace-Weitergabe:

• X-Instana-T (Trace-ID)
• X-Instana-S (Span ID)
• X-Instana-L (Abtaststufe oder Entscheidung)

Wenn „ NGINX “ Anfragen mit den Header-Einträgen „ W3C “ und „Trace Context“ erhält, setzt es die Ablaufverfolgung automatisch fort. Wenn „ NGINX “ Upstream-Anfragen sendet, gibt es den Trace-Kontext mithilfe derselben Standard-Header-Zeichenfolgen weiter: W3C.

Daten an den Endpunkt „ OTLP “ des Agenten senden

Der „ Instana “-Agent stellt „ OTLP “-Endpunkte bereit, die „ OpenTelemetry “-Daten direkt von Ihrem „ NGINX “-Server empfangen können.

Um Daten an den Endpunkt „ OTLP “ des Instana -Agenten zu senden, konfigurieren Sie Ihren NGINX -Server wie folgt:

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;
        }
    }
}

Daten an den Backend-Endpunkt „ OTLP “ senden

In Umgebungen, in denen keine direkte Kommunikation mit dem „ Instana “-Agenten möglich ist, können Sie Ihren „ NGINX “-Server so konfigurieren, dass „ OpenTelemetry “-Daten direkt an das „ Instana “-Backend gesendet werden.

Weitere Informationen finden Sie unter „ OpenTelemetry -Daten an Instana senden “.

Um Daten an den Endpunkt „ OTLP “ des Backends „ Instana “ zu senden, konfigurieren Sie Ihren „ NGINX “-Server wie folgt:

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;
        }
    }
}

Ersetzen Sie {instana-backend-otlp-acceptor-endpoint} durch Ihren Backend-Endpunkt Instana und {agent-key} durch Ihren Agentenschlüssel Instana.

Voraussetzungen für die Bereitstellung von „ Kubernetes “

Stellen Sie sicher, dass die folgenden Voraussetzungen verfügbar sind:

• Kubernetes Cluster (z. B. Minikube, EKS, GKE oder AKS )
• Helm 3.x installiert
• kubectl für den Zugriff auf Ihren Cluster konfiguriert
• Instana Backend- OTLP -Endpunkt und API -Schlüssel

Installation von ingress-nginx mit „ OpenTelemetry “

1. Fügen Sie das Repository „ingress-nginx“ Helm hinzu:

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

2. Erstellen Sie eine Werte-Datei namens „ Helm “ (zum Beispiel ingress-nginx-values.yaml ) mit der folgenden Konfiguration: OpenTelemetry

   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}"

   Ersetzen Sie die folgenden Werte in der Konfiguration:

   • {instana-backend-otlp-endpoint} - Der Endpunkt Ihres „ Instana “-Backends unter OTLP (zum Beispiel otlp-red-saas.instana.io )
   • {agent-key} - Ihr „ Instana “-Agentenschlüssel
   • {your-cluster-name} - Der Name Ihres „ Kubernetes “-Clusters
   • {your-service-name} - Name Ihres Dienstes
   • {version} - Die Version des „ingress-nginx“-Images mit Unterstützung für „ OpenTelemetry “
   • Image-Einstellungen – Konfigurieren Sie diese entsprechend Ihrer Registrierung und Ihren Image-Anforderungen

3. Installieren Sie den Ingress-Nginx-Controller mit den benutzerdefinierten Werten:

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

4. Prüfen Sie die Installation:

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

Konfigurationsoptionen

Die Wertedatei „ Helm “ enthält mehrere wichtige Konfigurationsabschnitte:

• http-snippet : Enthält die Hauptkonfiguration des „ OpenTelemetry “-Exporters, einschließlich des Endpunkts „ Instana “ und der Authentifizierung
• main-snippet : Lädt das Modul „ OpenTelemetry “ NGINX
• otel-span-attr : Definiert benutzerdefinierte Span-Attribute, die jedem Trace hinzugefügt werden, einschließlich Metadaten, die für „ Kubernetes “ spezifisch sind
• otel-trace : Aktiviert die Nachverfolgung von „ OpenTelemetry “
• otel-trace-context : Konfiguriert die Weitergabe des Trace-Kontexts an nachgelagerte Dienste

Benutzerdefinierte Span-Attribute

Die Konfiguration enthält spezifische Attribute für „ Kubernetes “, die in „ Instana “ wertvolle Kontextinformationen liefern:

Diese Attribute helfen dabei, Traces mit bestimmten Ressourcen von „ Kubernetes “ in der Benutzeroberfläche von „ Instana “ abzugleichen.