Tracing distribué NGINX avec OpenTelemetry

Chargez le module, et activez le tracing dans votre nginx.conf. Ajoutez la directive load_module au niveau supérieur (contexte principal), et les directives OpenTelemetry dans le contexte http :

# Main context — load the dynamic module
load_module modules/ngx_otel_module.so;

http {
    # Export spans to the OpenTelemetry Collector over OTLP/gRPC
    otel_exporter {
        endpoint localhost:4317;
    }

    # A name that identifies this NGINX instance in traces
    otel_service_name nginx-server;

    # Emit a span per request and propagate W3C trace context to upstreams
    otel_trace on;
    otel_trace_context propagate;

    server {
        listen 80;

        location / {
            proxy_pass http://backend_app;
        }
    }
}

Cette configuration :

• Charge le module OpenTelemetry (load_module).
• Exporte les spans via OTLP/gRPC vers le collecteur écoutant sur localhost:4317 (otel_exporter).
• Crée une span pour chaque requête (otel_trace on). Pour tracer un sous-ensemble du trafic dans des environnements à haut débit, définissez otel_trace sur une variable (par exemple, pilotée par split_clients) au lieu de on.
• Propage le contexte de trace (otel_trace_context propagate) : cela extrait à la fois l'en-tête traceparent entrant (liant les spans NGINX au service appelant), et injecte le contexte mis à jour dans les requests envoyées aux services en amont (permettant aux services en aval de continuer la trace).

Les directives otel_trace on, et otel_trace_context peuvent également être définies par bloc server, ou location si vous souhaitez tracer uniquement des hôtes virtuels, ou des routes spécifiques.

Pour la référence complète des directives, consultez la documentation dengx_otel_module .

Configurez le Collecteur Otel pour recevoir les trace de ngx_otel_module, et les métriques du point de terminaison d'état stub NGINX, enrichir les deux avec l'identité NGINX, et les transférer à New Relic.

receivers:
  # Receives spans from ngx_otel_module (NGINX → localhost:4317)
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"
  # Collects NGINX metrics from the stub status endpoint
  nginx:
    endpoint: <YOUR_STUB_STATUS_ENDPOINT>  # e.g. http://127.0.0.1/status
    collection_interval: 30s

processors:
  resourcedetection:
    detectors: [system]
    system:
      resource_attributes:
        host.id:
          enabled: true

  # Adds the NGINX identity so spans and metrics resolve to the SAME NGINXSERVER entity
  resource/nginx:
    attributes:
      - key: nginx.server.endpoint
        value: "<YOUR_STUB_STATUS_ENDPOINT>"  # must match the nginx receiver endpoint
        action: upsert
      - key: nginx.deployment.name
        value: "<YOUR_DEPLOYMENT_NAME>"        # a stable name for this NGINX deployment
        action: upsert

  # Sets nginx.display.name for the metrics pipeline
  transform/nginx_metrics:
    metric_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))

  # Same display-name stamp for the traces pipeline — ngx_otel_module spans carry no
  # NGINX identity by default; resource/nginx adds the endpoint + deployment name, and
  # this adds nginx.display.name, so the spans resolve to the NGINXSERVER entity.
  transform/nginx_traces:
    trace_statements:
      - context: resource
        statements:
          - set(attributes["nginx.display.name"], Concat(["server", attributes["nginx.deployment.name"]], ":"))

  batch:

exporters:
  otlp_http:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT}
    headers:
      api-key: ${env:NEW_RELIC_LICENSE_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, resource/nginx, transform/nginx_traces, batch]
      exporters: [otlp_http]
    metrics/nginx:
      receivers: [nginx]
      processors: [resourcedetection, resource/nginx, transform/nginx_metrics, batch]
      exporters: [otlp_http]

Cette configuration de collecteur inclut deux pipelines :

• Pipeline de trace: reçoit les données de trace OTLP de ngx_otel_module, et de vos applications instrumentées via gRPC (port 4317), ou HTTP (port 4318). Il s’agit du même pipeline de trace standard que vous utiliseriez pour tout service envoyant des données OTLP à New Relic.
• Pipeline de métriques: utilise le nginxreceiver pour collecter les métriques de performance (connexions, requests) à partir du point de terminaison d’état stub de NGINX. Ces métriques créent l’entité NGINX dans New Relic avec des métriques dorées.

Les deux pipelines partagent ces Processeurs :

• resourcedetection: ajoute host.id, un attribut de ressource standard utilisé pour identifier les hôtes dans tout l’écosystème OpenTelemetry.
• resource/nginx: ajoute nginx.server.endpoint, et nginx.deployment.name. Ces deux attributs forment l’identité de l’entité NGINX. Leur application aux deux pipelines permet aux spans, et aux métriques NGINX de se résoudre vers la même entité NGINXSERVER au lieu d’une entité de service dupliquée.
• transform/nginx_*: ajoute nginx.display.name pour un nom d’entité convivial.

Définissez les variables d’environnement requises et démarrez (ou redémarrez) le collecteur :

$
export NEW_RELIC_LICENSE_KEY="<YOUR_LICENSE_KEY>"
$
export OTEL_EXPORTER_OTLP_ENDPOINT="<YOUR_NEWRELIC_OTLP_ENDPOINT>"
$

$
sudo systemctl restart nrdot-collector

Remplacez <YOUR_LICENSE_KEY> par votre clé de licence. Pour le point de terminaison OTLP, consultez la configuration du point de terminaison OTLP New Relic.

Testez la configuration et rechargez NGINX pour charger le module OpenTelemetry :

$
sudo nginx -t
$
sudo systemctl reload nginx

Une fois que NGINX et le collecteur sont en cours d’exécution, générez du trafic via vos applications instrumentées. Après quelques minutes, vérifiez que les données arrivent dans New Relic :

-- Verify NGINX trace spans
FROM Span SELECT count(*)
WHERE nginx.deployment.name = '<YOUR_DEPLOYMENT_NAME>'
SINCE 10 minutes ago

-- Verify NGINX metrics
FROM Metric SELECT count(*)
WHERE metricName LIKE 'nginx.%'
SINCE 10 minutes ago

Une fois que les données de trace circulent, New Relic crée automatiquement des relations CALLS entre vos services et l’entité NGINX. Les relations peuvent mettre jusqu’à 10 minutes à apparaître.

Pour afficher les relations :

1. Allez à one.newrelic.com > All capabilities > All entities.

2. Recherchez votre entité NGINX ou l’un de vos services instrumentés.

3. Sélectionnez une entité pour ouvrir sa page de résumé.

4. Cliquez sur Service map pour voir le graphique des relations d’entité.

   Vous devriez voir vos services clients connectés à NGINX, et NGINX connecté à vos services backend :

   [Client app] → CALLS → [NGINX] → CALLS → [Backend app]

   Copier

   Vous pouvez également interroger les relations avec NRQL :

   FROM Relationship SELECT *
   WHERE source.entityName = '<YOUR_NGINX_DISPLAY_NAME>'
     OR target.entityName = '<YOUR_NGINX_DISPLAY_NAME>'
   SINCE 1 day ago

   Copier

• Vérifiez que NGINX s'est rechargé sans erreur : sudo nginx -t et sudo journalctl -u nginx -n 50 --no-pager
• Confirmez que ngx_otel_module est chargé. Une erreur unknown directive "otel_exporter" signifie que le module n’est pas chargé. Vérifiez le chemin load_module et que nginx-module-otel est installé pour votre version de NGINX.
• Vérifiez que le Collecteur Otel est en cours d’exécution et écoute sur le port dans otel_exporter: sudo ss -tlnp | grep 4317
• Vérifiez les logs du collecteur pour les erreurs : sudo journalctl -u nrdot-collector -n 50 --no-pager
• Confirmez que le point de terminaison otel_exporter correspond à l’adresse d’écoute gRPC du collecteur.

• Prévoyez jusqu’à 10 minutes pour que les relations apparaissent après l’arrivée des premiers spans.

• Vérifiez que vos applications instrumentées envoient des traces via le collecteur. Les spans NGINX et les spans de l’application doivent tous deux atteindre New Relic pour que les relations se forment.

• Vérifiez que vos applications clientes propagent les en-têtes W3C traceparent. Sans la propagation du contexte de trace, les spans NGINX ne sont pas connectés au service appelant.

• Confirmez que les processeurs resourcedetection et resource/nginx sont tous deux inclus dans le pipeline de trace du collecteur. Les attributs nginx.server.endpoint et nginx.deployment.name sont requis pour que les spans NGINX soient résolus en l’entité NGINXSERVER.

• Confirmez que otel_trace_context propagate est défini (et non extract ou inject seul). propagate est requis pour le flux de contexte de bout en bout à travers NGINX.

• Requête pour vérifier que les spans NGINX et ceux de l’application partagent les ID de trace :

  FROM Span SELECT uniques(service.name)
  WHERE trace.id IN (
    SELECT uniques(trace.id) FROM Span
    WHERE nginx.deployment.name = '<YOUR_DEPLOYMENT_NAME>'
    SINCE 10 minutes ago LIMIT 5
  )
  SINCE 10 minutes ago

  Copier

  Vous devriez voir votre service NGINX à côté des noms de service de votre application.

• Assurez-vous que le processeur resource/nginx s’exécute dans le pipeline de traces (et pas seulement dans le pipeline de métriques). Sans cela, les spans NGINX manquent de nginx.deployment.name / nginx.server.endpoint et sont synthétisés comme un service générique plutôt que d’être résolus en l’entité NGINXSERVER.
• Vérifiez que la valeur nginx.server.endpoint est identique dans le Récepteur nginx et le Processeur resource/nginx, et que nginx.deployment.name correspond à la valeur utilisée par vos métriques NGINX. L’identité de l’entité est la combinaison de ces deux valeurs. Une non-correspondance produit une entité différente.
• Exécutez également le pipeline de métriques. Les métriques dorées de l’entité NGINXSERVER proviennent de nginxreceiver; sans cela, NGINX apparaît toujours via les traces, mais sans métriques.

• Chaque application instrumentée doit envoyer ses traces via le même Collecteur Otel (ou directement à New Relic) afin que les données de span pour tous les services atteignent le même compte.
• Pour les applications utilisant des agents New Relic APM, vérifiez que le tracing distribué est activé, et que l’agent est connecté.
• Pour les applications SDK OTel, vérifiez que l’exportateur OTLP est configuré pour envoyer au collecteur.
• Prévoyez un délai supplémentaire. Les relations pour les services avec un volume de trafic plus faible peuvent mettre plus de temps à apparaître.