OpenTelemetry를 사용한 HAProxy 분산 추적

haproxy.cfg의 프런트엔드 섹션에 filter opentelemetry 지시문을 추가합니다. 이는 HAProxy가 수신되는 requests에 OTel 필터를 적용하도록 지시합니다:

frontend main
    bind *:8080
    default_backend app_servers
    filter opentelemetry id otel config /etc/haproxy/otel.cfg

frontend stats
    bind *:8404
    stats enable
    stats uri /stats

config 파라미터는 스팬, 컨텍스트 전파 및 익스포터 설정을 정의하는 별도의 OTel 필터 설정 파일을 가리킵니다.

stats 프런트엔드는 HAProxy 통계 엔드포인트를 활성화하며, OTel Collector의 haproxyreceiver은(는) 이를 사용하여 성능 메트릭을 수집합니다. 필요한 경우 바인딩 주소와 포트를 조정하십시오.

OTel 필터 설정 파일을 생성하십시오(예: /etc/haproxy/otel.cfg):

[otel]
    otel-instrumentation otel-inst
        config /etc/haproxy/otel.yml default
        no option disabled
        rate-limit 100.0

        scopes client_session_start
        scopes frontend_http_request
        scopes backend_http_request
        scopes client_session_end
        scopes server_session_start
        scopes http_response
        scopes server_session_end

    otel-scope client_session_start
        extract "-ctx" use-headers
        span "HAProxy session" parent "-ctx" root
        otel-event on-client-session-start

    otel-scope frontend_http_request
        span "Frontend HTTP request" parent "HAProxy session" kind server
            attribute "http.method" method
            attribute "http.url" url
            attribute "http.target" path
        otel-event on-frontend-http-request

    otel-scope backend_http_request
        span "Backend HTTP request" parent "Frontend HTTP request" kind client
        finish "Frontend HTTP request"
        span "HAProxy session"
            inject "-ctx" use-headers
        otel-event on-backend-http-request

    otel-scope client_session_end
        finish "Backend HTTP request"
        otel-event on-client-session-end

    otel-scope server_session_start
        span "Server session" parent "HAProxy session"
        otel-event on-server-session-start

    otel-scope http_response
        span "HTTP response" parent "Server session"
            attribute "http.status_code" status
        finish "Server session"
        otel-event on-http-response

    otel-scope server_session_end
        finish *
        otel-event on-server-session-end

이 설정은 다음을 수행합니다:

• 수신되는 W3C traceparent 헤더(extract "-ctx" use-headers)를 추출하여 HAProxy 스팬을 호출하는 서비스의 트레이스에 연결합니다.
• 전체 요청 수명 주기에 대한 스팬을 생성합니다: 세션 시작, 프런트엔드 요청 처리, 백앤드 요청 전달, 응답 처리 및 세션 종료.
• 백앤드(inject "-ctx" use-headers)로 전송된 requests에 업데이트된 트레이스 컨텍스트를 주입하여 다운스트림 서비스가 트레이스를 계속할 수 있도록 합니다.
• requests(rate-limit 100.0)의 100%를 트레이스 합니다. 처리량이 많은 환경에서는 이 값을 조정하여 트레이스 볼륨을 줄이십시오.

전체 OTel 필터 설정 참조는 HAProxy OTel 트레이스 문서를 참조하십시오.

필터 익스포터 설정 파일을 생성하십시오(예: /etc/haproxy/otel.yml). 이는 HAProxy OTel 필터에 트레이스 데이터를 보낼 위치를 알려줍니다:

exporters:
  exporter_traces:
    type:     otlp_grpc
    endpoint: "http://localhost:4317/v1/traces"

processors:
  processor_batch:
    type: batch

providers:
  provider_traces:
    resources:
      - service.name: "YOUR_HAPROXY_SERVICE_NAME"

signals:
  traces:
    default:
      scope_name: "HAProxy OTel filter"
      exporters:  exporter_traces
      processors: processor_batch
      providers:  provider_traces

YOUR_HAPROXY_SERVICE_NAME을(를) 이 HAProxy 인스턴스를 식별하는 이름으로 바꾸십시오(예: haproxy-prod-lb).

service.name 은(는) 분산 추적에 참여하는 모든 서비스를 식별하는 표준 OpenTelemetry 리소스 속성 입니다 ― HAProxy뿐만이 아닙니다. 모든 OTel 계측된 애플리케이션은 (OTEL_SERVICE_NAME을(를) 통해) 이를 설정하며, 모든 뉴렐릭 APM 에이전트에는 동등한 항목(app_name)이 있습니다. 이것이 없어도 트레이스는 여전히 올바르게 흐르고 연결되지만, 스팬이 UI에서 unknown_service (으)로 표시되어 식별하기 어렵습니다. 보다 자세한 내용은 OpenTelemetry 리소스 모범 사례를 참조하십시오.

이는 HAProxy 인스턴스당 일회성 설정입니다. 새로운 백앤드 또는 프런트엔드 애플리케이션을 추가할 때 이 파일을 변경할 필요가 없습니다 — 트레이스 컨텍스트 전파를 통해 관계가 자동으로 형성됩니다.

익스포터는 gRPC를 통해 OTel Collector가 수신 대기 중인 localhost:4317(으)로 트레이스를 보냅니다. 수집기가 다른 호스트에서 실행되는 경우 endpoint을(를) 조정하십시오.

HAProxy OTel 필터에서 트레이스를 수신하고 HAProxy 통계 엔드포인트에서 메트릭을 수신하여 뉴렐릭으로 전달하도록 OTel Collector를 설정하십시오.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
      http:
        endpoint: "0.0.0.0:4318"
  haproxy:
    endpoint: "http://127.0.0.1:8404/stats"
    collection_interval: 30s

processors:
  resourcedetection:
    detectors: [system]
    system:
      resource_attributes:
        host.name:
          enabled: true
        host.id:
          enabled: true
  resource/haproxy:
    attributes:
      - key: haproxy.addr
        value: "http://127.0.0.1:8404/stats"
        action: upsert
  batch:

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

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, resource/haproxy, batch]
      exporters: [otlphttp]
    metrics:
      receivers: [haproxy]
      processors: [resourcedetection, resource/haproxy, batch]
      exporters: [otlphttp]

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

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

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

• resourcedetection: OpenTelemetry 에코시스템 전체에서 호스트를 식별하는 데 사용되는 표준 리소스 속성인 host.name 및 host.id를 추가합니다.
• resource/haproxy: haproxy.addr 속성을 추가합니다. 이 속성은 이 HAProxy 인스턴스를 식별하고 뉴렐릭의 동일한 HAProxy 엔티티 아래에 메트릭과 트레이스 데이터를 함께 연결합니다.

http://127.0.0.1:8404/stats 값은 HAProxy 공식 문서에서 사용되는 일반적인 HAProxy 통계 주소이며 1단계의 haproxy.cfg과 일치합니다. 이는 HAProxy 인스턴스당 일회성 정적 값입니다. 백앤드 및 프런트엔드 애플리케이션을 추가하거나 제거할 때 수집기 설정을 변경할 필요가 없습니다 — 트레이스 컨텍스트 전파를 통해 관계가 자동으로 형성됩니다. 통계 엔드포인트가 다른 주소, 포트 또는 URI를 사용하는 경우에만 haproxy 수신기 endpoint 및 resource/haproxy 값을 조정하십시오 — 두 값은 항상 일치해야 합니다.

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

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

$
sudo systemctl restart otelcol-contrib

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

OTel 필터 설정을 로드하려면 HAProxy를 다시 시작하십시오:

$
sudo systemctl restart haproxy

다음 시작 오류를 확인하십시오:

• 필터 지원 누락: unknown keyword 'filter' 또는 unknown keyword 'opentelemetry'이 표시되면 HAProxy 바이너리에 OTel 필터가 포함되지 않은 것입니다. HAProxy OTel 설치 가이드를 참조하십시오.
• 설정 파일을 찾을 수 없음: unable to load OTel configuration이 표시되면 filter opentelemetry 지시어의 config 경로가 올바르고 파일이 존재하는지 확인하십시오. 경로는 HAProxy 작업 디렉터리에 대한 상대 경로입니다.
• 공유 라이브러리 오류: OTel 필터에는 OpenTelemetry C++ SDK 공유 라이브러리가 필요합니다. 설치되어 있고 검색 가능한지 확인하십시오(예: LD_LIBRARY_PATH 또는 ldconfig을(를) 통해).

다음 확인 사항을 순서대로 진행하십시오.

• HAProxy가 오류 없이 시작되었는지 확인하십시오: sudo journalctl -u haproxy -n 50 --no-pager
• OTel 필터가 로드되었는지 확인하십시오. HAProxy 로그에서 filter, opentelemetry 또는 otel를 언급하는 오류를 찾으십시오.
• OTel Collector가 실행 중이고 otel.yml에 지정된 포트에서 수신 대기 중인지 확인하십시오. sudo ss -tlnp | grep 4317
• 수집기 로그에서 오류 확인: sudo journalctl -u otelcol-contrib -n 50 --no-pager
• otel.yml 익스포터 엔드포인트가 수집기의 gRPC 리스너 주소와 일치하는지 확인하십시오.

다음 가능한 원인을 확인하십시오:

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

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

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

• resourcedetection 및 resource/haproxy 프로세서가 모두 수집기 트레이스 파이프라인에 포함되어 있는지 확인하십시오. HAProxy 엔티티 식별에는 host.id 및 haproxy.addr 속성이 필요합니다.

• 메트릭 파이프라인이 haproxy 수신기와 함께 실행 중인지 확인하십시오. 메트릭 파이프라인은 HAProxy 엔티티를 생성합니다 ― 이 파이프라인이 없으면 HAProxy는 전용 HAProxy 엔티티가 아닌 일반 서비스로 표시됩니다.

• HAProxy 및 애플리케이션 스팬이 모두 트레이스 ID를 공유하는지 확인하는 쿼리:

  FROM Span SELECT uniques(service.name)
  WHERE trace.id IN (
    SELECT uniques(trace.id) FROM Span
    WHERE service.name = 'YOUR_HAPROXY_SERVICE_NAME'
    SINCE 10 minutes ago LIMIT 5
  )
  SINCE 10 minutes ago

  카피

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

다음과 같은 가능한 원인을 고려해 보십시오:

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