OpenTelemetry를 사용한 NGINX 분산 추적

모듈을 로드하고 nginx.conf에서 추적을 활성화하십시오. 최상위 수준(기본 컨텍스트)에 load_module 지시문을 추가하고 http 컨텍스트 내에 OpenTelemetry 지시문을 추가하십시오:

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

이 설정:

• OpenTelemetry 모듈(load_module)을 로드합니다.
• OTLP/gRPC를 통해 localhost:4317 (otel_exporter)에서 수신 대기 중인 수집기로 스팬을 내보냅니다.
• 모든 요청(otel_trace on)에 대해 스팬을 생성합니다. 처리량이 많은 환경에서 트래픽의 하위 집합을 트레이스하려면 on 대신 otel_trace을(를) 변수(예: split_clients에 의해 구동됨)로 설정하십시오.
• 전파 트레이스 컨텍스트(otel_trace_context propagate): 이는 수신되는 traceparent 헤더를 추출 (NGINX 스팬을 호출 서비스에 연결)하고 업데이트된 컨텍스트를 업스트림으로 전송된 requests에 주입 (다운스트림 서비스가 트레이스를 계속할 수 있도록 함)합니다.

특정 가상 호스트나 라우트만 트레이스하려는 경우 otel_trace on 및 otel_trace_context 지시문을 server 또는 location 블록별로 설정할 수도 있습니다.

전체 지시문 참조는 ngx_otel_module 문서를 참조하십시오.

ngx_otel_module에서 트레이스를 수신하고 NGINX 스텁 상태 엔드포인트에서 메트릭을 수신하도록 OTel Collector를 설정하고, 두 가지 모두 NGINX ID로 보강하여 뉴렐릭으로 전달하십시오.

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]

이 수집기 설정에는 두 개의 파이프라인이 포함됩니다:

• 트레이스 파이프라인: gRPC(포트 4317) 또는 HTTP(포트 4318)를 통해 ngx_otel_module 및 계측된 애플리케이션에서 OTLP 트레이스 데이터를 수신합니다. 이는 OTLP 데이터를 뉴렐릭으로 전송하는 모든 서비스에 사용하는 것과 동일한 표준 트레이스 파이프라인입니다.
• 메트릭 파이프라인: nginxreceiver을(를) 사용하여 NGINX 스텁 상태 엔드포인트에서 성능 메트릭(연결, requests)을 수집합니다. 이러한 메트릭은 골든 메트릭과 함께 뉴렐릭에 NGINX 엔티티를 생성합니다.

두 파이프라인 모두 다음 프로세서를 공유합니다:

• resourcedetection: OpenTelemetry 에코시스템 전반에서 호스트를 식별하는 데 사용되는 표준 리소스 속성인 host.id을(를) 추가합니다.
• resource/nginx: nginx.server.endpoint 및 nginx.deployment.name를 추가합니다. 이 두 속성은 NGINX 엔티티의 식별자를 형성합니다. 이를 두 파이프라인 모두에 적용하면 NGINX 스팬과 메트릭이 중복 서비스 엔티티 대신 동일한 NGINXSERVER 엔티티로 확인됩니다.
• transform/nginx_*: 친숙한 엔티티 이름을 위해 nginx.display.name을(를) 추가합니다.

필요한 환경 변수를 설정하고 수집기를 시작(또는 다시 시작)하십시오:

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

$
sudo systemctl restart nrdot-collector

<YOUR_LICENSE_KEY>을(를) 라이선스 키(으)로 교체합니다. OTLP 엔드포인트의 경우 뉴렐릭 OTLP 엔드포인트 설정을 참조하십시오.

설정을 테스트하고 NGINX를 다시 로드하여 OpenTelemetry 모듈을 로드하십시오:

$
sudo nginx -t
$
sudo systemctl reload nginx

NGINX와 수집기가 실행되면 계측된 애플리케이션을 통해 트래픽을 생성하십시오. 몇 분 후 뉴렐릭에 데이터가 도착하는지 확인하십시오:

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

트레이스 데이터가 흐르기 시작하면 뉴렐릭은 서비스와 NGINX 엔티티 간에 CALLS 관계를 자동으로 생성합니다. 관계가 나타나려면 최대 10분이 걸릴 수 있습니다.

관계를 보려면 다음을 수행하십시오:

1. one.newrelic.com > All capabilities > All entities 으)로 이동합니다.

2. NGINX 엔티티 또는 계측된 서비스 중 하나를 검색하십시오.

3. 엔티티를 선택하여 요약 페이지를 여십시오.

4. 엔티티 관계 그래프를 보려면 Service map을(를) 클릭하십시오.

   클라이언트 서비스가 NGINX에 연결되고 NGINX가 백앤드 서비스에 연결된 것을 볼 수 있습니다:

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

   카피

   또한 NRQL로 관계를 쿼리할 수 있습니다:

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

   카피

• NGINX가 오류 없이 다시 로드되었는지 확인하십시오: sudo nginx -t 및 sudo journalctl -u nginx -n 50 --no-pager
• ngx_otel_module이(가) 로드되었는지 확인하십시오. unknown directive "otel_exporter" 오류는 모듈이 로드되지 않았음을 의미합니다. load_module 경로를 확인하고 NGINX 버전에 맞는 nginx-module-otel이(가) 설치되어 있는지 확인하십시오.
• OTel Collector가 실행 중이고 otel_exporter의 포트에서 수신 대기 중인지 확인하십시오: sudo ss -tlnp | grep 4317
• 수집기 로그에서 오류 확인: sudo journalctl -u nrdot-collector -n 50 --no-pager
• otel_exporter 엔드포인트가 수집기의 gRPC 리스너 주소와 일치하는지 확인하십시오.

• 첫 번째 스팬이 도착한 후 관계가 나타나려면 최대 10분이 걸립니다.

• 계측된 애플리케이션이 수집기를 통해 트레이스를 전송하고 있는지 확인하십시오. 관계가 형성되려면 NGINX 스팬과 애플리케이션 스팬이 모두 뉴렐릭에 도달해야 합니다.

• 클라이언트 애플리케이션이 W3C traceparent 헤더를 전파하는지 확인하십시오. 트레이스 컨텍스트 전파가 없으면 NGINX 스팬이 호출 서비스에 연결되지 않습니다.

• resourcedetection 및 resource/nginx 프로세서가 모두 수집기 트레이스 파이프라인에 포함되어 있는지 확인하십시오. NGINX 스팬이 NGINXSERVER 엔티티로 확인되려면 nginx.server.endpoint 및 nginx.deployment.name 속성이 필요합니다.

• otel_trace_context propagate이(가) 설정되어 있는지 확인하십시오(extract 또는 inject만 설정된 것이 아님). NGINX를 통한 엔드투엔드 컨텍스트 흐름에는 propagate이(가) 필요합니다.

• NGINX와 애플리케이션 스팬이 모두 트레이스 ID를 공유하는지 확인하기 위한 쿼리:

  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

  카피

  애플리케이션 서비스 이름과 함께 NGINX 서비스가 표시되어야 합니다.

• resource/nginx 프로세서가 트레이스 파이프라인(메트릭 파이프라인뿐만 아니라)에서 실행되는지 확인하십시오. 이것이 없으면 NGINX 스팬에 nginx.deployment.name / nginx.server.endpoint이(가) 부족하여 NGINXSERVER 엔티티로 확인되지 않고 일반 서비스로 합성됩니다.
• nginx 수신기와 resource/nginx 프로세서에서 nginx.server.endpoint 값이 동일한지 확인하고, nginx.deployment.name이(가) NGINX 메트릭에서 사용되는 값과 일치하는지 확인하십시오. 엔티티 식별자는 이 두 값의 조합입니다. 일치하지 않으면 다른 엔티티가 생성됩니다.
• 메트릭 파이프라인도 실행하십시오. NGINXSERVER 엔티티의 골든 메트릭은 nginxreceiver에서 가져오며, 이 항목이 없으면 NGINX는 여전히 트레이스를 통해 나타나지만 메트릭은 없습니다.

• 모든 서비스의 스팬 데이터가 동일한 계정에 도달하도록 각 계측된 애플리케이션은 동일한 OTel Collector를 통해(또는 뉴렐릭으로 직접) 트레이스를 전송해야 합니다.
• 뉴렐릭 APM 에이전트를 사용하는 애플리케이션의 경우 분산 추적이 활성화되어 있고 에이전트가 연결되어 있는지 확인하십시오.
• OTel SDK 애플리케이션의 경우 OTLP 익스포터가 수집기로 전송하도록 설정되어 있는지 확인하십시오.
• 추가 시간을 두십시오. 트래픽 양이 적은 서비스의 관계는 나타나는 데 시간이 더 오래 걸릴 수 있습니다.