Airflow

OpenTelemetry 트레이스 설정

트레이스를 쓰려면 ``pip install 'apache-airflow[otel]'``로 필요한 패키지를 설치한 뒤 ``airflow.cfg``에 ``[traces] otel_on = True``와 함께 ``otel_host``, ``otel_port``, ``otel_application``, ``otel_ssl_active``, ``otel_task_log_event``를 설정한다. 메트릭과 마찬가지로 개별 설정 키 대신 표준 OpenTelemetry 환경변수(``OTEL_EXPORTER_OTLP_ENDPOINT`` 등)로 SDK를 구성하는 방식이 권장되며, 옛 설정 키들은 지원 중단 예정이다.

태스크에 커스텀 스팬 추가하기

Dag 작성자는 ``airflow.sdk.observability``의 ``trace`` 객체를 이용해 태스크에 커스텀 스팬을 계측할 수 있다. 이 객체는 표준 OpenTelemetry ``opentelemetry.trace`` 모듈을 얇게 감싼 것이어서 표준 OpenTelemetry 트레이싱 API를 그대로 쓸 수 있다. ``trace.get_tracer(__name__)``으로 트레이서를 얻고, ``@task`` 함수 안에서 ``tracer.start_as_current_span("my_span")``으로 스팬을 만들면 된다.

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

Dag Run conf를 통한 실행 단위 트레이스 제어

Dag run의 ``conf``에 넣는 몇 가지 예약된 키로 그 개별 실행에 대해서만 트레이싱을 제어할 수 있다. 이 키들은 실행이 생성될 때(그리고 클리어될 때) 읽히므로, UI/API의 "Trigger with config" 다이얼로그, ``airflow dags trigger --conf`` CLI, 또는 ``TriggerDagRunOperator(conf=...)``로 실행을 트리거할 때 함께 지정해야 한다.

``airflow/trace_sampled``는 이 실행의 head-sampling 결정을 강제한다. ``true``면 설정된 샘플러와 무관하게 항상 트레이싱하고 ``false``면 절대 하지 않으며, 키를 생략하면 샘플러가 결정하게 둔다. 명시적인 불리언 값만 인정된다.

``airflow/task_span_detail_level``은 1보다 큰 값으로 설정하면 상세 스팬을 활성화한다. 이는 디버깅을 돕기 위한 기능으로 언제든 변경되거나 제거될 수 있다.

``airflow/dagrun_parent_trace_context``는 이 실행을 루트 트레이스가 아니라 **외부** 트레이스 안에 포함시킨다. 실행을 트리거한 상위 오케스트레이터, 이벤트 파이프라인, CI 잡, 또는 다른 Airflow 배포 등에서 캡처한 W3C ``traceparent`` 문자열(선택적으로 ``traceparent``와 ``tracestate``를 담은 매핑)을 넣는다. 이렇게 하면 실행 전체(``dag_run`` 스팬과 모든 태스크/워커 스팬)가 그 트레이스 안에 살게 되고, 부모 기반 샘플러는 외부 샘플링 결정을 물려받는다. 이 키가 없으면(기본값) 실행은 루트 트레이스가 된다. 값이 없거나 형식이 잘못되면 무시되어 실행은 루트로 남을 뿐, 실행 생성 자체가 실패하지는 않는다.