트레이스 설정

트레이스 설정 (Traces Configuration)

이 페이지는 Airflow가 OpenTelemetry로 트레이스를 전송하도록 설정하는 방법을 안내해요. 먼저 apache-airflow[otel] 패키지를 설치하고 [traces] 섹션에서 설정을 켠 뒤, 표준 OpenTelemetry 환경 변수로 SDK를 구성해요. DAG 작성자는 airflow.sdk.observability의 trace 객체로 Task 안에 커스텀 스팬(span)을 추가할 수 있어요.

출처: 문서

본문

Airflow는 OpenTelemetry에서 트레이스를 전송하도록 설정할 수 있어요.

설치 - OpenTelemetry

OpenTelemetry를 사용하려면 먼저 필요한 패키지를 설치해야 해요:

pip install 'apache-airflow[otel]'

airflow.cfg 같은 설정 파일에 다음 줄을 추가해요:

[traces]
otel_on = True
otel_host = localhost
otel_port = 8889
otel_application = airflow
otel_ssl_active = False
otel_task_log_event = True

Note

다음 설정 키는 deprecated되었으며 향후 제거될 예정이에요
[traces]
otel_host = localhost
otel_port = 8889
otel_debugging_on = False
otel_service = Airflow
otel_ssl_active = False

OpenTelemetry SDK는 OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL 같은 표준 OpenTelemetry 환경 변수를 사용해 구성해야 해요.

자세한 내용은 OpenTelemetry exporter 프로토콜 스펙과 SDK 환경 변수 문서를 참고해요.

Task에 커스텀 스팬 추가하기

DAG 작성자는 airflow.sdk.observability의 trace 객체를 사용해 Task에 커스텀 스팬을 계측(instrument)할 수 있어요. 이것은 표준 OpenTelemetry opentelemetry.trace 모듈 위의 얇은 shim이라서, 모든 표준 OpenTelemetry 트레이싱 API를 사용할 수 있어요.

from airflow.sdk import task
from airflow.sdk.observability import trace

tracer = trace.get_tracer(__name__)

@task
def my_task():
    with tracer.start_as_current_span("my_span") as span:
        span.set_attribute("key", "value")
        # ... task logic ...

이렇게 만든 커스텀 스팬은 트레이싱이 활성화되어 있을 때 Airflow가 관리하는 Task 스팬의 자식으로 자동 중첩돼요. 트레이싱이 비활성화되어 있으면 OpenTelemetry API가 제공하는 no-op 트레이서가 사용되므로 Task는 아무 오버헤드 없이 실행돼요.

HTTPS 활성화

OpenTelemetry 콜렉터와 HTTPS 연결을 설정하려면 OpenTelemetry 콜렉터의 config.yml 파일 안에 SSL 인증서와 키를 구성해야 해요.

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
        tls:
          cert_file: "/path/to/cert/cert.crt"
          key_file: "/path/to/key/key.pem"

트레이스 설정