Distributed tracing do NGINX com OpenTelemetry

Carregue o módulo e ative o tracing no seu nginx.conf. Adicione a diretiva load_module no nível superior (contexto principal) e as diretivas do OpenTelemetry dentro do 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 configuração:

• Carrega o módulo do OpenTelemetry (load_module).
• Exporta spans por OTLP/gRPC para o coletor escutando em localhost:4317 (otel_exporter).
• Cria um span para cada request (otel_trace on). Para fazer o trace de um subconjunto de tráfego em ambientes de altas taxas de transferência, defina otel_trace como uma variável (por exemplo, controlada por split_clients) em vez de on.
• Propaga o contexto do trace (otel_trace_context propagate): isso tanto extrai o cabeçalho traceparent de entrada (vinculando os spans do NGINX ao serviço chamador) quanto injeta o contexto atualizado nos requests enviados aos upstreams (permitindo que os serviços downstream continuem o trace).

As diretivas otel_trace on e otel_trace_context também podem ser definidas por bloco server ou location caso deseje fazer o trace apenas de hosts virtuais ou rotas específicas.

Para a referência completa da diretiva, consulte a documentação dongx_otel_module .

Configure o OTel Collector para receber traces de ngx_otel_module e métricas do endpoint de status stub do NGINX, enriquecer ambos com a identidade do NGINX e encaminhá-los para o 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 configuração do coletor inclui dois pipelines:

• Pipeline de traces: recebe dados de trace OTLP de ngx_otel_module e de seus aplicativos instrumentados via gRPC (porta 4317) ou HTTP (porta 4318). Este é o mesmo pipeline de trace padrão que você usaria para qualquer serviço que envia dados OTLP para o New Relic.
• Pipeline de métricas: usa o nginxreceiver para coletar métricas de desempenho (conexões, requests) do endpoint de status stub do NGINX. Essas métricas criam a entidade do NGINX no New Relic com métricas clássicas.

Ambos os pipelines compartilham estes processadores:

• resourcedetection: adiciona host.id, um atributo de recurso padrão usado para identificar hosts em todo o ecossistema do OpenTelemetry.
• resource/nginx: adiciona nginx.server.endpoint e nginx.deployment.name. Esses dois atributos formam a identidade da entidade do NGINX. Aplicá-los a ambos os pipelines faz com que os spans e as métricas do NGINX sejam resolvidos para a mesma entidade NGINXSERVER em vez de uma entidade de serviço duplicada.
• transform/nginx_*: adiciona nginx.display.name para um nome de entidade amigável.

Defina as variáveis de ambiente necessárias e inicie (ou reinicie) o coletor:

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

$
sudo systemctl restart nrdot-collector

Substitua <YOUR_LICENSE_KEY> pelo seu chave de licença. Para o endpoint OTLP, consulte a configuração do endpoint OTLP da New Relic.

Teste a configuração e recarregue o NGINX para carregar o módulo do OpenTelemetry:

$
sudo nginx -t
$
sudo systemctl reload nginx

Assim que o NGINX e o coletor estiverem em execução, gere algum tráfego por meio de seus aplicativos instrumentados. Após alguns minutos, verifique se os dados estão chegando no 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

Depois que os dados de trace estiverem fluindo, o New Relic cria automaticamente relacionamentos CALLS entre seus serviços e a entidade do NGINX. Pode levar até 10 minutos para os relacionamentos aparecerem.

Para visualizar os relacionamentos:

1. Vá para one.newrelic.com > All capabilities > All entities.

2. Pesquise sua entidade do NGINX ou um de seus serviços instrumentados.

3. Selecione uma entidade para abrir sua página de resumo.

4. Clique em Service map para ver o gráfico de relacionamento de entidades.

   Você deve ver seus serviços cliente conectados ao NGINX, e o NGINX conectado aos seus serviços de backend:

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

   Copiar

   Você também pode consultar relacionamentos com NRQL:

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

   Copiar

• Verifique se o NGINX foi recarregado sem erros: sudo nginx -t e sudo journalctl -u nginx -n 50 --no-pager
• Confirme se ngx_otel_module está carregado. Um erro unknown directive "otel_exporter" significa que o módulo não está carregado. Verifique o caminho load_module e se nginx-module-otel está instalado para a sua versão do NGINX.
• Verifique se o OTel Collector está em execução e escutando na porta em otel_exporter: sudo ss -tlnp | grep 4317
• Verifique os logs do coletor em busca de erros: sudo journalctl -u nrdot-collector -n 50 --no-pager
• Confirme se o endpoint otel_exporter corresponde ao endereço de escuta gRPC do coletor.

• Aguarde até 10 minutos para que os relacionamentos apareçam após a chegada dos primeiros spans.

• Verifique se seus aplicativos instrumentados estão enviando traces pelo coletor. Tanto os spans do NGINX quanto os spans do aplicativo devem chegar ao New Relic para que os relacionamentos se formem.

• Verifique se seus aplicativos clientes propagam os cabeçalhos W3C traceparent. Sem a propagação de contexto do trace, os spans do NGINX não são conectados ao serviço chamador.

• Confirme se os processadores resourcedetection e resource/nginx estão incluídos no pipeline de traces do coletor. Os atributos nginx.server.endpoint e nginx.deployment.name são necessários para que os spans do NGINX sejam resolvidos para a entidade NGINXSERVER.

• Confirme se otel_trace_context propagate está definido (não apenas extract ou inject). propagate é necessário para o fluxo de contexto de ponta a ponta através do NGINX.

• Consulta para verificar se os spans do NGINX e do aplicativo compartilham IDs 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

  Copiar

  Você deve ver o seu serviço NGINX ao lado dos nomes dos serviços do seu aplicativo.

• Garanta que o processador resource/nginx seja executado no pipeline de trace (não apenas no pipeline de métricas). Sem ele, os spans do NGINX não têm nginx.deployment.name / nginx.server.endpoint e são sintetizados como um serviço genérico em vez de serem resolvidos para a entidade NGINXSERVER.
• Verifique se o valor nginx.server.endpoint é idêntico no receiver nginx e no processador resource/nginx, e se nginx.deployment.name corresponde ao valor usado pelas suas métricas do NGINX. A identidade da entidade é a composição desses dois valores. Uma incompatibilidade produz uma entidade diferente.
• Execute o pipeline de métricas também. As métricas clássicas da entidade NGINXSERVER vêm do nginxreceiver; sem ele, o NGINX ainda aparece via trace, mas sem métricas.

• Cada aplicativo instrumentado deve enviar trace pelo mesmo OTel Collector (ou diretamente para a New Relic) para que os dados de span de todos os serviços cheguem à mesma conta.
• Para aplicativos que usam agentes do New Relic APM, verifique se o distributed tracing está ativado e se o agente está conectado.
• Para aplicativos do OTel SDK, verifique se o exportador OTLP está configurado para enviar para o coletor.
• Aguarde um tempo adicional. Os relacionamentos para serviços com menor volume de tráfego podem demorar mais para aparecer.