선언적 구성

선언적 구성은 환경 변수 대신 YAML 파일을 사용한다.

이 방식은 다음과 같은 경우에 유용하다.

  • 설정할 구성 옵션이 많다.
  • 환경 변수로 제공되지 않는 구성 옵션을 사용하고 싶다.

지원 언어

다음 오픈텔레메트리(OpenTelemetry) SDK는 선언적 구성을 지원한다.

자세한 내용은 준수 현황 표를 참고한다.

시작하기

  1. 다음 구성 파일을 otel-config.yaml로 저장한다.
  2. 환경 변수 OTEL_CONFIG_FILE=/path/to/otel-config.yaml을 설정한다.

권장 구성 파일은 다음과 같다.

# otel-getting-started.yaml은 OTLP를 통해 localhost로 내보내는 구성을 포함하여
# SDK를 구성하기 위한 좋은 출발점이다.
#
# 참고: 환경 변수 치환 문법(예: ${MY_ENV})을 제외하고, SDK는 구성 파일을 해석할 때
# 환경 변수를 무시한다. 여기에는 다음 문서에 정의된 모든 환경 변수도 포함된다.
# https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
#
# 필수 속성, 시맨틱, 기본 동작 등을 포함한 스키마 문서는 다음을 참고한다.
# https://opentelemetry.io/docs/specs/otel-config/types/

file_format: "1.2"

resource:
  # OTEL_RESOURCE_ATTRIBUTES 환경 변수에서 리소스 속성을 읽는다.
  # 이 방식은 오픈텔레메트리 오퍼레이터 및 다른 배포 방식과 잘 맞는다.
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development: # /development 속성은 일부 SDK에서 지원되지 않을 수 있다.
    detectors:
      - service: # "service.instance.id"와 OTEL_SERVICE_NAME 환경 변수의 "service.name"을 추가한다.
      - host:
      - process:
      - container:

propagator:
  composite:
    - tracecontext:
    - baggage:

# OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수에서 백엔드 엔드포인트를 읽는다.
# 이 방식은 오픈텔레메트리 오퍼레이터 및 다른 배포 방식과 잘 맞는다.

tracer_provider:
  sampler:
    parent_based:
      root:
        always_on:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/logs

환경 변수

  • 선언적 구성은 환경 변수 를 읽는 문법을 지원한다.
  • 모든 환경 변수는 구성 파일에 명시적으로 추가하지 않으면 무시된다.

예를 들어 다음과 같이 설정하면,

OTEL_RESOURCE_ATTRIBUTES=service.version=1.1,deployment.environment.name=staging

다음 구성은 service.version=1.1과 deployment.environment.name=staging을 가진 리소스를 생성한다.

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}

마이그레이션 구성

기존 구성이 환경 변수에 의존한다면, 마이그레이션 구성을 선언적 구성으로 마이그레이션하기 위한 출발점으로 사용할 수 있다.

사용 가능한 구성 옵션

전체 구성 옵션 목록은 구성 예시에서 확인할 수 있다.

시그널별 엔드포인트

트레이스, 메트릭, 로그의 엔드포인트가 서로 다르다면, otlp_http를 사용할 때 다음 구성을 사용한다.

OTLP HTTP 익스포터엔드포인트 값
트레이스${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-http://localhost:4318/v1/traces}
메트릭${OTEL_EXPORTER_OTLP_METRICS_ENDPOINT:-http://localhost:4318/v1/metrics}
로그${OTEL_EXPORTER_OTLP_LOGS_ENDPOINT:-http://localhost:4318/v1/logs}

gRPC 익스포터

otlp_http 대신 otlp_grpc를 사용하여 gRPC로 내보낼 수도 있다.

otlp_grpc:
  endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4317}

리소스 속성

리소스 속성은 환경 변수로 설정하는 것을 권장한다. 쿠버네티스용 오픈텔레메트리 오퍼레이터처럼 환경 변수를 설정하는 도구와 잘 연동되기 때문이다.

하지만 구성 파일에서 리소스 속성을 직접 설정할 수도 있다.

resource:
  attributes:
    - name: service.name
      value: shopping_cart
    - name: deployment.environment.name
      value: staging