개요

플래그 평가 메트릭을 사용하면 서버 측 애플리케이션에서 Feature Flags의 각 변형이 얼마나 자주 반환되는지 측정할 수 있습니다. 이 메트릭을 사용하여 시간 경과에 따른 플래그 채택을 추적하고, 타겟팅 규칙이 예상대로 작동하는지 확인하며, Dashboards에서 플래그 평가 데이터를 그래프로 나타낼 수 있습니다.

전제 조건

플래그 평가 메트릭을 설정하기 전에 다음 사항을 확인하세요.

• 서버 측 Feature Flags가 이미 구성되어 있어야 합니다.
• Agent 기반 배포의 경우, Datadog Agent 7.32.0 이상이 실행 중이어야 하며 OTLP 메트릭을 수신할 수 있어야 합니다.
• Agent가 없는 서버리스 배포의 경우, 플랫폼에 지원되는 서버리스 텔레메트리 경로가 구성되어 있어야 합니다.
• Java, Node.js 및 Python 서버리스 환경의 경우 Feature Flags 텔레메트리 전송을 참조합니다.
• 레거시 활성화 경로를 사용하는 Agent 기반 구성의 경우, 애플리케이션에 DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true가 설정되어 있어야 합니다.
• 서버 측 트레이서가 플래그 평가 메트릭 지원을 위한 최소 버전을 충족해야 합니다.

Agentless 구성 전달과 이 메트릭은 독립적인 경로를 사용합니다. Agentless SDK는 지원되는 Agent 기반 또는 서버리스 텔레메트리 설정을 통해 필요한 OTLP 경로를 구성할 때 메트릭을 내보낼 수 있습니다.

1단계: OTLP 수신기 구성

플래그 평가 메트릭은 OpenTelemetry(OTLP)를 통해 내보내집니다. Agent 기반 배포의 경우, 기본적으로 꺼져 있는 Datadog Agent OTLP 수신기를 활성화해야 합니다. 설정 지침은 Datadog Agent에 의한 OTLP 수집을 참조하세요. Agent가 없는 서버리스 배포의 경우, Serverless Monitoring 설정에서 지원하는 OTLP 또는 사용자 지정 메트릭 경로를 사용하세요.

애플리케이션이 사용하는 프로토콜(포트 4317의 gRPC 또는 포트 4318의 HTTP)만 활성화하면 됩니다.

2단계: 애플리케이션 구성

Java를 제외한 지원되는 트레이서 및 전달 모드 조합의 경우, 표준 서버 측 Feature Flags 구성 외에 다음 환경 변수를 설정하세요. Java의 경우 DD_METRICS_OTEL_ENABLED는 아무런 효과가 없습니다. 대신 Java: OpenTelemetry SDK 종속성 추가 섹션을 참조하세요.

# Enable flag evaluation metrics
DD_METRICS_OTEL_ENABLED=true

Java: OpenTelemetry SDK 종속성 추가

Java 공급자는 OpenTelemetry SDK를 통해 feature_flag.evaluations를 기록하고 OTLP를 통해 내보내므로 opentelemetry-sdk-metrics 및 opentelemetry-exporter-otlp 종속성이 애플리케이션의 클래스 경로에 있어야 합니다. Java Feature Flags 종속성과 함께 추가하세요. OpenTelemetry BOM을 가져와 OpenTelemetry API와 SDK의 버전이 동일하게 유지되도록 하세요.

dependencies {
    implementation platform('io.opentelemetry:opentelemetry-bom:1.47.0')
    implementation 'io.opentelemetry:opentelemetry-sdk-metrics'
    implementation 'io.opentelemetry:opentelemetry-exporter-otlp'
}

dependencies {
    implementation(platform("io.opentelemetry:opentelemetry-bom:1.47.0"))
    implementation("io.opentelemetry:opentelemetry-sdk-metrics")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp")
}

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.47.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-metrics</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

Java 트레이서에서 공급자는 OpenTelemetry SDK가 클래스 경로에 있으면 OTLP 메트릭 익스포터를 자동으로 시작합니다. 종속성이 누락되면 메트릭이 내보내지지 않고 트레이서가 OpenTelemetry SDK is not on the classpath를 기록합니다.

Ruby: OpenTelemetry 메트릭 gem 추가

Ruby 애플리케이션의 경우, 애플리케이션 번들에 OpenTelemetry 메트릭 SDK 및 OTLP 메트릭 익스포터 gem을 추가하세요.

gem "opentelemetry-metrics-sdk", ">= 0.8"
gem "opentelemetry-exporter-otlp-metrics", ">= 0.4"

bundle install을 사용하여 gem을 설치합니다. 이 gem들은 OpenTelemetry 미터 공급자와 OTLP 메트릭 익스포터를 제공합니다. Ruby 트레이서는 DD_METRICS_OTEL_ENABLED=true가 설정되었을 때 이를 사용합니다. gem이 누락된 경우, Ruby 트레이서는 feature_flag.evaluations 메트릭을 내보내지 않고 Failed to load OpenTelemetry metrics gems를 기록합니다.

엔드포인트 구성

DD_TRACE_AGENT_URL 및 포트 8126의 표준 serverless-init 리스너는 OTLP 메트릭 엔드포인트를 구성하지 않습니다. 다음 섹션에 설명된 대로 OTLP 엔드포인트를 별도로 구성하세요. Agent가 없는 서버리스 배포의 경우, 이 메트릭을 구성하기 전에 플랫폼에 대한 Serverless Monitoring 설정을 따릅니다.

기본적으로 대부분의 트레이서는 포트 4318(HTTP)을 통해 DD_AGENT_HOST의 Agent로 OTLP 메트릭을 보냅니다. 애플리케이션에서 Agent에 도달하기 위해 이미 DD_AGENT_HOST를 설정한 경우, 엔드포인트 구성은 필요하지 않습니다.

다음 중 하나에 해당하는 경우 OTLP 엔드포인트를 명시적으로 설정하세요.

• Agent가 기본 OTLP 포트의 DD_AGENT_HOST에서 도달할 수 없는 경우(예: 원격 Agent 또는 기본값이 아닌 포트).
• Java 트레이서를 사용하는 경우. 해당 플래그 평가 메트릭 익스포터는 포트 4318에서 OTLP/HTTP만 지원합니다(gRPC는 지원되지 않음). Java 트레이서는 DD_AGENT_HOST에서 엔드포인트를 파생하지 않으며 기본값은 http://localhost:4318입니다. Agent가 localhost에 있지 않을 때 OTEL_EXPORTER_OTLP_ENDPOINT를 Agent의 HTTP 엔드포인트로 설정합니다.
• Python 트레이서를 사용하는 경우. Python 트레이서는 기본적으로 HTTP가 아닌 포트 4317의 gRPC를 사용합니다. Agent에서 gRPC OTLP 수신기를 활성화하거나 프로토콜을 재정의하여 HTTP를 대신 사용하세요.

OTEL_EXPORTER_OTLP_ENDPOINT=http://<AGENT_HOST>:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

엔드포인트를 설정하려면 표준 OpenTelemetry 변수를 사용하세요.

# Point OTLP data at the Datadog Agent (HTTP, port 4318)
OTEL_EXPORTER_OTLP_ENDPOINT=http://<AGENT_HOST>:4318

# Or use gRPC (port 4317). For most tracers, the default protocol is http/protobuf,
# so set the protocol explicitly when switching to gRPC:
# OTEL_EXPORTER_OTLP_ENDPOINT=http://<AGENT_HOST>:4317
# OTEL_EXPORTER_OTLP_PROTOCOL=grpc

<AGENT_HOST>를 Datadog Agent의 호스트 이름 또는 IP 주소로 바꿉니다.

Docker Compose 예시:

services:
  datadog-agent:
    environment:
      - DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT=0.0.0.0:4317
      - DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318
      - HOST_PROC=/proc  # If running Agent v7.61.0+ in Docker

  app-go:
    environment:
      - DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true
      - DD_METRICS_OTEL_ENABLED=true
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://datadog-agent:4318
    depends_on:
      datadog-agent:
        condition: service_healthy

3단계: 메트릭 흐름 확인

배포 후 메트릭이 Datadog에 도달하고 있는지 확인하세요.

1. Metrics Explorer로 이동하여 feature_flag.evaluations를 검색합니다.
2. 애플리케이션이 플래그를 평가한 후 몇 분 이내에 메트릭이 나타나지 않으면 다음을 확인합니다.
   • Agent OTLP 수신기가 활성화되어 있고 올바른 포트가 노출되어 있습니다.
   • OTEL_EXPORTER_OTLP_ENDPOINT가 별도의 컬렉터가 아닌 Agent를 가리킵니다.
   • 애플리케이션이 런타임에 서버 SDK로 플래그를 활발하게 평가하고 있습니다(코드 경로가 실행 중입니다).

4단계: 메트릭 보존 활성화

기본적으로 feature_flag.evaluations는 1시간 분량의 데이터만 보존합니다. 더 긴 기록을 보존하려면 다음을 수행하세요.

1. Metrics Summary로 이동하여 feature_flag.evaluations를 검색합니다.
2. 메트릭을 선택하고 과거 메트릭을 활성화합니다.

이 설정은 선택 사항이며 OTLP 메트릭에 대해 자동으로 활성화되지 않습니다.

Dashboards에서 플래그 평가 그래프화

다음 쿼리를 사용하여 Dashboards에서 플래그 키 및 변형별로 플래그 평가를 그래프로 표시하세요.

sum:feature_flag.evaluations{*} by {feature_flag.key,feature_flag.result.variant}

feature_flag.evaluations 메트릭은 다음 태그가 있는 카운터입니다.

추가 자료

추가적인 유용한 설명서, 링크 및 기사:

서버 측 Feature Flags설명서 Feature Flag 그래프설명서 메트릭설명서 Dashboards설명서