Nginx + OpenTelemetry

Associez le traçage distribué à votre infrastructure

Cet article est aussi disponible en anglais

Naviguer sans visibilité dans une architecture de microservices, c'est comme traverser l'océan sans boussole. Pour éviter de sombrer, une cartographie précise des transactions est indispensable. C'est là qu'intervient l'alliance stratégique de deux géants : OpenTelemetry (OTel) et NGINX. Ensemble, ils forment la colonne vertébrale d'un tracing distribué robuste, offrant aux équipes DevOps une clarté sans précédent pour monitorer et déboguer leurs applications.

Fondé sur la documentation officielle d'OpenTelemetry et du module NGINX, cet article explore comment orchestrer cette synergie. Nous passerons en revue ses avantages décisifs, ses limites et des exemples concrets pour consolider votre stratégie d'observabilité.

Etude du module Otel pour Nginx ?

OpenTelemetry est un outil open source qui collecte traces, métriques et logs pour rendre vos systèmes transparents. Il standardise l’observabilité avec des APIs, SDKs et un Collector qui s’intègre à plus de 40 backends. Le module NGINX OpenTelemetry (ngx_otel_module) permet à NGINX de générer des traces conformes au standard W3C (notamment via les en-têtes traceparent et tracestate) et de les envoyer via OTLP/gRPC. Pas de métriques directes, mais les attributs des traces (ex. : http.status_code) peuvent faire le job.

Pourquoi ce combo ?

Associer OTel à NGINX, c’est comme donner des lunettes à rayons X à votre proxy. Vous suivez les requêtes de bout en bout, même dans un labyrinthe de microservices.

Les atouts :

• Traces distribuées : Visualisez le parcours des requêtes à travers NGINX et les backends.
• Standard W3C : Interopérabilité avec d’autres outils OTel.
• Personnalisation : Ajoutez des données spécifiques (ex. : latence) pour un monitoring sur mesure.
• Écosystème flexible : Exportez vers Jaeger, Prometheus (via transformations), et plus encore.

Mais attention, il y a des pièges : compiler NGINX avec le module, configurer un Collector, ou gérer la surcharge des traces sans sampling.

Mise en œuvre : NGINX et OTel en action

Prenons un cas typique : NGINX relaie des requêtes vers un backend, et vous voulez savoir pourquoi certaines sont lentes.

Étape 1 : Installer le module OTel

Le module n’est pas inclus par défaut. Compilez NGINX avec :

./configure --with-compat --add-dynamic-module=/path/to/ngx_otel_module
make && make install

Ajoutez dans nginx.conf :

load_module modules/ngx_otel_module.so;

Étape 2 : Configurer le tracing

Voici une configuration pour tracer les requêtes /api et exporter vers un Collector OTel :

http {
    otel_exporter {
        endpoint localhost:4317; # Collector OTel
        batch_size 512;
        batch_count 4;
        interval 5s;
    }

    server {
        listen 80;
        server_name example.com;

        location /api {
            otel_trace on;
            otel_trace_context propagate; # Lier avec le backend
            otel_span_attr "latency=$request_time"; # Latence personnalisée
            proxy_pass http://backend:8080;
        }
    }
}

• otel_trace on; active le tracing.
• otel_trace_context propagate; relie les traces NGINX au backend via des en-têtes W3C.
• otel_span_attr capture la latence des requêtes.
• Les traces sont envoyées par lots pour éviter la surcharge.

Étape 3 : Déployer un Collector OTel

Le Collector traite et exporte les traces. Exemple de configuration :

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
processors:
  batch:
    timeout: 5s
exporters:
  otlp:
    endpoint: jaeger:4317
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

Les traces vont de NGINX au Collector, puis à Jaeger pour visualisation.

Étape 4 : Optimiser avec du sampling

Pour un site à fort trafic, limitez le tracing à 10 % des requêtes :

http {
    split_clients "${remote_addr}AAA" $otel_trace_on {
        10% on;
        * off;
    }

    server {
        location /api {
            otel_trace $otel_trace_on;
            otel_trace_context propagate;
            proxy_pass http://backend:8080;
        }
    }
}

Cela réduit la charge tout en collectant des données pertinentes.

Exemple : Traquer une latence

Votre endpoint /api est lent. Avec Jaeger, vous analysez les traces :

• Span NGINX : http.status_code=200, latency=0.300s.
• Span Backend : Latence de 0.250s.

Vous ajoutez otel_span_attr "upstream_time=$upstream_response_time"; et découvrez que NGINX ajoute 0.050s. Peut-être un problème de configuration ou de réseau ? Vous ajustez et surveillez l’amélioration.

Pourquoi ajouter cet attribut ?

• En ajoutant upstream_time=$upstream_response_time comme attribut dans un span OpenTelemetry, vous enrichissez les traces avec des informations spécifiques sur la performance du serveur backend.
• Cela permet de surveiller la latence des serveurs upstream dans des outils de traçabilité comme Jaeger, Zipkin ou Grafana Tempo, et de corréler ces données avec d'autres métriques ou logs pour diagnostiquer des problèmes.

Quand l’utiliser ?

Ce combo brille dans :

• Les architectures microservices avec NGINX comme passerelle. Petit clin d'oeil aux utilisateurs de nginx et ceux qui utilisent un Ingress Nginx.
• Les cas nécessitant un débogage précis des performances.
• Les équipes voulant un pipeline d’observabilité unifié.

Conclusion

NGINX et OpenTelemetry forment un duo redoutable améliorant la visibilité à des endroits stratégiques pour votre infrastructure. Avec quelques lignes de configuration et un collector, vous accédez à des informations qui habituellement nécessites de la ressource et pas mal de compétences devops avancées. Cela pourrait vous aider à passez du flou à la clareté quand il s'agît de vos requêtes. Testez avec les exemples ci-dessus et armez votre service NGINX !