Intégration d' OpenTelemetry à Instana pour NGINX

Propagation du contexte de trace

Le module natif NGINX OpenTelemetry utilise la norme W3C Trace Context pour le traçage distribué. Le module transmet le contexte de trace à l'aide des en-têtes standard d' HTTP s suivants :

• traceparent - Contient l'identifiant de la trace, l'identifiant du segment parent et les indicateurs de trace
• tracestate - Contient des informations de traçabilité propres au fournisseur

Le module ne prend pas en charge les en-têtes spécifiques à l' Instana pour la propagation des traces :

• X-Instana-T (Identifiant de trace)
• X-Instana-S (ID de la plage)
• X-Instana-L (Niveau d'échantillonnage ou décision)

Lorsque NGINX reçoit des requêtes comportant des en-têtes « W3C » dans le contexte de traçage, il poursuit automatiquement la traçabilité. Lorsque NGINX envoie des requêtes en amont, il transmet le contexte de traçage en utilisant les mêmes en-têtes standard de l' W3C.

Envoi de données vers le point de terminaison de l'agent OTLP

L'agent « Instana » fournit des points de terminaison « OTLP » capables de recevoir des données « OpenTelemetry » directement depuis votre serveur « NGINX ».

Pour envoyer des données au point de terminaison OTLP de l'agent d' Instana, configurez votre serveur NGINX comme suit :

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

Envoi de données vers le point de terminaison backend OTLP

Dans les environnements où une communication directe avec l'agent d' Instana s n'est pas possible, vous pouvez configurer votre serveur NGINX pour qu'il envoie les données d' OpenTelemetry directement au backend Instana.

Pour plus d'informations, consultez la section « Envoi de données d' OpenTelemetry vers Instana ».

Pour envoyer des données au point de terminaison OTLP du backend Instana, configurez votre serveur NGINX comme suit :

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

Remplacez {instana-backend-otlp-acceptor-endpoint} par votre point de terminaison backend Instana et {agent-key} par votre clé d'agent Instana.

Conditions préalables au déploiement d' Kubernetes

Assurez-vous que la configuration prérequise suivante est respectée :

• Kubernetes cluster (par exemple, Minikube, EKS, GKE ou AKS )
• Helm 3.x installé
• kubectl configuré pour accéder à votre cluster
• Instana point de terminaison d' OTLP du backend et clé d' API

Installation d'Ingress-Nginx avec OpenTelemetry

1. Ajoutez le dépôt Helm d'Ingress-Nginx :

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

2. Créez un fichier de paramètres « Helm » (par exemple, ingress-nginx-values.yaml) contenant la configuration suivante : 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}"

   Remplacez les valeurs suivantes dans la configuration :

   • {instana-backend-otlp-endpoint} - L'URL de votre point de terminaison backend OTLP d' Instana (par exemple, otlp-red-saas.instana.io )
   • {agent-key} - Votre clé d'agent d' Instana
   • {your-cluster-name} - Le nom de votre cluster Kubernetes
   • {your-service-name} - Le nom de votre service
   • {version} - La version de l'image ingress-nginx prenant en charge l' OpenTelemetry
   • Paramètres d'image - Configurez-les en fonction de votre registre et de vos besoins en matière d'images

3. Installez le contrôleur ingress-nginx en utilisant les valeurs personnalisées suivantes :

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

4. Vérifiez l'installation :

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

Options de configuration

Le fichier de paramètres « Helm » comprend plusieurs sections de configuration importantes :

• http-snippet : contient la configuration principale de l'exportateur OpenTelemetry, y compris le point de terminaison Instana et les paramètres d'authentification
• main-snippet : Charge le module OpenTelemetry NGINX
• otel-span-attr : Définit les attributs de span personnalisés qui sont ajoutés à chaque trace, y compris les métadonnées spécifiques à l' Kubernetes
• otel-trace : Active le traçage d' OpenTelemetry
• otel-trace-context : Configure la propagation du contexte de traçage vers les services en aval

Attributs « span » personnalisés

La configuration comprend des attributs propres à Kubernetes qui fournissent des informations contextuelles utiles dans Instana :

Ces attributs permettent d'associer les traces à des ressources spécifiques d' Kubernetes s dans l'interface utilisateur d' Instana.