Envoy 계측 (Instrumenting Envoy)

원문 보기 위키 갱신 2026.10.05

Datadog APM은 Envoy v1.9.0 이상에 포함돼 있어요.

출처: 문서

본문

Datadog APM 활성화

참고: 아래 예시 구성은 Envoy v1.19용이에요.

Envoy에서 Datadog APM을 활성화하려면 다음 설정이 필요해요:

Datadog Agent에 트레이스를 제출하는 클러스터
트레이싱을 활성화하는 http_connection_manager 구성

Datadog Agent에 트레이스를 제출하는 클러스터를 추가해요:

 clusters:
 ... 기존 클러스터 구성 ...
 - name: datadog_agent
   connect_timeout: 1s
   type: strict_dns
   lb_policy: round_robin
   load_assignment:
     cluster_name: datadog_agent
     endpoints:
     - lb_endpoints:
       - endpoint:
           address:
             socket_address:
               address: localhost
               port_value: 8126

Envoy가 컨테이너나 오케스트레이션 환경에서 실행된다면 address 값을 변경해요.

트레이싱을 활성화하려면 http_connection_manager 섹션에 다음 추가 구성을 포함해요:

    - name: envoy.filters.network.http_connection_manager
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
        generate_request_id: true
        request_id_extension:
          typed_config:
            "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
            use_request_id_for_trace_sampling: false
        tracing:
          provider:
            name: envoy.tracers.datadog
            typed_config:
              "@type": type.googleapis.com/envoy.config.trace.v3.DatadogConfig
              collector_cluster: datadog_agent
              service_name: envoy-v1.19

collector_cluster 값은 Datadog Agent 클러스터에 제공한 이름과 일치해야 해요. service_name은 사용자의 Envoy 사용 방식에 맞는 의미 있는 값으로 변경할 수 있어요.

이 구성을 사용하면 Envoy에 대한 HTTP 요청이 Datadog 트레이스를 시작하고 전파하며 APM UI에 나타나요.

Envoy v1.19 구성 예시

다음 예시 구성은 Datadog APM을 사용해 트레이싱을 활성화하는 데 필요한 항목의 배치를 보여줘요.

static_resources:
  listeners:
  - address:
      socket_address:
        address: 0.0.0.0
        port_value: 80
    traffic_direction: OUTBOUND
    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          generate_request_id: true
          request_id_extension:
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
              use_request_id_for_trace_sampling: false
          tracing:
            provider:
              name: envoy.tracers.datadog
              typed_config:
                "@type": type.googleapis.com/envoy.config.trace.v3.DatadogConfig
                collector_cluster: datadog_agent   # 명명된 클러스터와 일치
                service_name: envoy-v1.19          # 사용자 정의 서비스 이름
          codec_type: auto
          stat_prefix: ingress_http
          route_config:
            name: local_route
            virtual_hosts:
            - name: backend
              domains:
              - "*"
              routes:
              - match:
                  prefix: "/"
                route:
                  cluster: service1
          # 헬스체크 요청의 트레이스는 샘플링하면 안 됨.
          http_filters:
          - name: envoy.filters.http.health_check
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck
              pass_through_mode: false
              headers:
                - exact_match: /healthcheck
                  name: :path
          - name: envoy.filters.http.router
            typed_config: {}
          use_remote_address: true
  clusters:
  - name: service1
    connect_timeout: 0.250s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: service1
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: service1
                port_value: 80
  # 트레이스 전송을 위해 datadog Agent의 주소로 이 클러스터를 구성해요.
  - name: datadog_agent
    connect_timeout: 1s
    type: strict_dns
    lb_policy: round_robin
    load_assignment:
      cluster_name: datadog_agent
      endpoints:
      - lb_endpoints:
        - endpoint:
            address:
              socket_address:
                address: localhost
                port_value: 8126

admin:
  access_log_path: "/dev/null"
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 8001

메트릭 제외

Envoy의 dog_statsd 구성을 사용해 메트릭을 보고한다면 다음 추가 구성으로 datadog_agent 클러스터의 활동을 제외할 수 있어요.

stats_config:
  stats_matcher:
    exclusion_list:
      patterns:
      - prefix: "cluster.datadog_agent."

Envoy 샘플링

Datadog으로 전송되는 Envoy 트레이스의 양을 제어하려면 DD_TRACE_SAMPLING_RULES 파라미터를 0.0(0%)에서 1.0(100%) 사이의 값으로 설정해 샘플링 비율을 지정해요. 값이 지정되지 않으면 Envoy에서 시작된 트레이스의 100%가 전송돼요.

Datadog Agent 계산 샘플링 비율(Agent당 초당 10개 트레이스)을 사용하고 100%로 설정된 기본 샘플링 규칙을 무시하려면 DD_TRACE_SAMPLING_RULES 파라미터를 빈 배열로 설정해요:

DD_TRACE_SAMPLING_RULES=[]

또한 서비스별로 0.0(0%)에서 1.0(100%) 사이의 명시적 샘플링 비율을 정의할 수 있어요. 예를 들어 서비스 envoy-proxy의 샘플 비율을 10%로 설정하려면:

DD_TRACE_SAMPLING_RULES=[{"service": "envoy-proxy","sample_rate": 0.1}]

DD_TRACE_SAMPLING_RULES로 샘플링 비율을 구성하려면 Envoy 실행 방식에 따라 다음 방법 중 하나를 사용해요:

셸 스크립트로: 스크립트에서 envoy를 실행하기 직전에 환경 변수를 설정해요:
```
#!/bin/sh
export DD_TRACE_SAMPLING_RULES=[]
envoy -c envoy-config.yaml
```

Docker Compose 구성에서: 서비스 정의의 environment 섹션에 환경 변수를 설정해요:

services:
  envoy:
    image: envoyproxy/envoy:v1.19-latest
    entrypoint: []
    command:
        - envoy
        - -c
        - /etc/envoy/envoy.yaml
    volumes:
        - './envoy.yaml:/etc/envoy/envoy.yaml:ro'
    environment:
        - DD_TRACE_SAMPLING_RULES=[]

Kubernetes 파드 안의 컨테이너로: 파드 스펙의 해당 containers 항목의 env 섹션에 환경 변수를 지정해요:

apiVersion: v1
kind: Pod
metadata:
  name: envoy
spec:
  containers:
  - name: envoy
    image: envoyproxy/envoy:v1.20-latest
    env:
    - name: DD_TRACE_SAMPLING_RULES
      value: "[]"

환경 변수

참고: DD_AGENT_HOST, DD_TRACE_AGENT_PORT, DD_TRACE_AGENT_URL 변수는 Envoy에 적용되지 않아요. Datadog Agent의 주소는 cluster 설정으로 구성되기 때문이에요.

사용 가능한 환경 변수는 Envoy에 내장된 C++ 트레이서의 버전에 따라 달라져요. C++ 트레이서의 버전은 "DATADOG TRACER CONFIGURATION"으로 시작하는 줄에 표시되어 로그에서 찾을 수 있어요.