Rastreo distribuido de NGINX con OpenTelemetry

Cargue el módulo y habilite el rastreo en su nginx.conf. Agregue la directiva load_module en el nivel superior (contexto principal) y las directivas de OpenTelemetry dentro del contexto 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;
        }
    }
}

Esta configuración:

• Carga el módulo de OpenTelemetry (load_module).
• Exporta spans a través de OTLP/gRPC al recolector que escucha en localhost:4317 (otel_exporter).
• Crea un span para cada solicitud (otel_trace on). Para trazar un subconjunto de tráfico en entornos de alto rendimiento, configure otel_trace en una variable (por ejemplo, controlada por split_clients) en lugar de on.
• Propaga el contexto de traza (otel_trace_context propagate): esto extrae el encabezado traceparent entrante (vinculando los spans de NGINX al servicio de llamada) e inyecta el contexto actualizado en las requests enviadas a los upstreams (permitiendo que los servicios downstream continúen la traza).

Las directivas otel_trace on y otel_trace_context también se pueden configurar por bloque server o location si desea trazar solo hosts virtuales o rutas específicas.

Para obtener la referencia completa de las directivas, consulte la documentación dengx_otel_module .

Configure el OTel Collector para recibir trazas de ngx_otel_module y métricas del extremo de estado stub de NGINX, enriquecer ambas con la identidad de NGINX y enviarlas a 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]

Esta configuración del recolector incluye dos pipelines:

• Pipeline de trazas: recibe datos de traza de OTLP de ngx_otel_module y sus aplicaciones instrumentadas a través de gRPC (puerto 4317) o HTTP (puerto 4318). Este es el mismo pipeline de trazas estándar que usaría para cualquier servicio que envíe datos de OTLP a New Relic.
• Pipeline de métricas: usa el nginxreceiver para recopilar métricas de rendimiento (conexiones, requests) del extremo de estado stub de NGINX. Estas métricas crean la entidad de NGINX en New Relic con métricas doradas.

Ambas canalizaciones comparten estos procesadores:

• resourcedetection: agrega host.id, un atributo de recurso estándar que se usa para identificar hosts en todo el ecosistema de OpenTelemetry.
• resource/nginx: agrega nginx.server.endpoint y nginx.deployment.name. Estos dos atributos forman la identidad de la entidad de NGINX. Al aplicarlos a ambos pipelines, los spans y las métricas de NGINX se resuelven en la misma entidad NGINXSERVER en lugar de en una entidad de servicio duplicada.
• transform/nginx_*: agrega nginx.display.name para obtener un nombre de entidad amigable.

Establezca las variables de entorno requeridas e inicie (o reinicie) el recolector:

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

$
sudo systemctl restart nrdot-collector

Reemplace <YOUR_LICENSE_KEY> con su clave de licencia. Para el extremo OTLP, consulte la configuración del extremo OTLP de New Relic.

Pruebe la configuración y recargue NGINX para cargar el módulo de OpenTelemetry:

$
sudo nginx -t
$
sudo systemctl reload nginx

Una vez que NGINX y el recolector estén en ejecución, genere algo de tráfico a través de sus aplicaciones instrumentadas. Después de unos minutos, verifique que los datos estén llegando a 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

Una vez que los datos de traza fluyen, New Relic crea automáticamente relaciones CALLS entre sus servicios y la entidad de NGINX. Las relaciones pueden tardar hasta 10 minutos en aparecer.

Para ver las relaciones:

1. Vaya a one.newrelic.com > All capabilities > All entities.

2. Busque la entidad de NGINX o uno de los servicios instrumentados.

3. Seleccione una entidad para abrir su página de resumen.

4. Haga clic en Service map para ver el gráfico de relaciones de la entidad.

   Debería ver sus servicios de cliente conectados a NGINX y NGINX conectado a sus servicios de backend:

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

   Copia

   También puede consultar las relaciones con NRQL:

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

   Copia

• Verifique que NGINX se haya recargado sin errores: sudo nginx -t y sudo journalctl -u nginx -n 50 --no-pager
• Confirme que ngx_otel_module esté cargado. Un error unknown directive "otel_exporter" significa que el módulo no está cargado. Verifique la ruta load_module y que nginx-module-otel esté instalado para su versión de NGINX.
• Verifique que el OTel Collector se esté ejecutando y escuchando en el puerto en otel_exporter: sudo ss -tlnp | grep 4317
• Verifique los logs del recolector en busca de errores: sudo journalctl -u nrdot-collector -n 50 --no-pager
• Confirme que el extremo otel_exporter coincida con la dirección del listener de gRPC del recolector.

• Espere hasta 10 minutos para que aparezcan las relaciones después de que lleguen los primeros spans.

• Verifique que sus aplicaciones instrumentadas estén enviando trazas a través del recolector. Tanto los spans de NGINX como los spans de la aplicación deben llegar a New Relic para que se formen las relaciones.

• Compruebe que las aplicaciones cliente propaguen los encabezados traceparent del W3C. Sin la propagación del contexto de traza, los spans de NGINX no están conectados al servicio de llamada.

• Confirme que los procesadores resourcedetection y resource/nginx estén incluidos en el pipeline de trazas del recolector. Los atributos nginx.server.endpoint y nginx.deployment.name son necesarios para que los spans de NGINX se resuelvan en la entidad NGINXSERVER.

• Confirme que otel_trace_context propagate esté configurado (no solo extract o inject). propagate es necesario para el flujo de contexto de extremo a extremo a través de NGINX.

• Consulta para verificar que tanto los spans de NGINX como los de la aplicación compartan los ID de traza:

  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

  Copia

  Debería ver su servicio NGINX junto a los nombres de los servicios de su aplicación.

• Asegúrese de que el procesador resource/nginx se ejecute en el pipeline de trazas (no solo en el pipeline de métricas). Sin él, los spans de NGINX carecen de nginx.deployment.name / nginx.server.endpoint y se sintetizan como un servicio genérico en lugar de resolverse en la entidad NGINXSERVER.
• Verifique que el valor nginx.server.endpoint sea idéntico en el receptor nginx y el procesador resource/nginx, y que nginx.deployment.name coincida con el valor utilizado por sus métricas de NGINX. La identidad de la entidad es la composición de estos dos valores. Una discrepancia produce una entidad diferente.
• Ejecute también el pipeline de métricas. Las métricas doradas de la entidad NGINXSERVER provienen del nginxreceiver; sin esto, NGINX sigue apareciendo a través de trazas, pero sin métricas.

• Cada aplicación instrumentada debe enviar trazas a través del mismo OTel Collector (o directamente a New Relic) para que los datos de los spans de todos los servicios lleguen a la misma cuenta.
• Para las aplicaciones que utilizan agentes APM de New Relic, verifique que el rastreo distribuido esté habilitado y que el agente esté conectado.
• Para las aplicaciones del SDK de OTel, verifique que el exportador OTLP esté configurado para enviar al recolector.
• Espere un tiempo adicional. Las relaciones de los servicios con menor volumen de tráfico pueden tardar más en aparecer.