dd-trace-py v4로 마이그레이션 (Migrate to dd-trace-py v4)

Python 트레이서를 v3에서 v4로 업그레이드해요.

출처: 문서

본문

개요 (Overview)

dd-trace-py 버전 4.0.0은 이전 Python 버전 지원을 중단하고 폐기된 API를 제거하며 Django 같은 프레임워크에 대한 새 기본 동작을 만들어요.

3.x 릴리스 라인은 이제 유지보수 모드에 있어요. 중요한 버그 수정만 백포트돼요.

사전 요구 사항 (Prerequisites)

환경이 다음 요구 사항을 충족하는지 확인하세요:

• Python 버전: Python 3.9 이상(Python 3.8 지원은 제거됨).
• Datadog Agent: v7.63.0 이상.
• OS: 64비트 Linux(32비트 Linux 지원은 제거됨).

1단계: 폐기 항목 탐지 (Step 1: Detect deprecations)

원활한 전환을 위해 최신 v3 릴리스(3.19.0)로 업그레이드하고 다음 도구를 사용해 폐기된 코드를 탐지하세요.

테스트에서 (In tests)

경고를 오류로 활성화한 상태로 pytest를 실행해 테스트 스위트에서 필요한 업데이트를 식별하세요:

pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py

애플리케이션에서 (In applications)

애플리케이션을 실행할 때 폐기 경고를 표시하도록 PYTHONWARNINGS 환경 변수를 설정하세요:

PYTHONWARNINGS=error::ddtrace.DDTraceDeprecationWarning python app.py

2단계: 주요 변경 사항 처리 (Step 2: Address breaking changes)

다음 변경 사항을 검토하고 v4를 설치하기 전에 코드를 업데이트하세요.

구성 및 환경 변수 (Configuration and environment variables)

ddtrace.settings 패키지는 제거됐어요. 설정을 구성하려면 환경 변수를 사용하세요.

다음 환경 변수가 제거됐어요:

• DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL
• DD_EXCEPTION_DEBUGGING_ENABLED
• DD_PROFILING_STACK_V2_ENABLED
• DEFAULT_RUNTIME_METRICS_INTERVAL

코드베이스에서 항목을 찾으려면 git grep을 사용하세요:

git grep -P -e "DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL" \
-e "DD_EXCEPTION_DEBUGGING_ENABLED" \
-e "DD_PROFILING_STACK_V2_ENABLED" \
-e "DEFAULT_RUNTIME_METRICS_INTERVAL"

트레이싱 API 변경 (Tracing API changes)

Span 및 Tracer 객체의 다음 메서드는 제거되거나 유형 시그니처가 업데이트됐어요.

제거된 메서드 (Removed methods)

클래스	메서드	대체
Span	set_tag_str	Span.set_tag 사용.
Span	finished (setter)	Span.finish() 사용.
Span	finish_with_ancestors	없음.
Span	set_struct_tag	없음.
Span	get_struct_tag	없음.
Span	_pprint	없음.
Tracer	on_start_span	없음.
Tracer	deregister_on_start_span	없음.
ddtrace.trace	Pin	없음.

업데이트된 유형 시그니처 (Updated type signatures)

다음 메서드는 더 엄격한 유형을 적용해요:

• Span.set_tag: (key: str, value: Optional[str] = None) -> None
• Span.get_tag: (key: str) -> Optional[str]
• Span.set_tags: (tags: dict[str, str]) -> None
• Span.get_tags: () -> dict[str, str]
• Span.set_metric: (key: str, value: int | float) -> None
• Span.get_metric: (key: str) -> Optional[int | float]
• Span.set_metrics: (metrics: Dict[str, int | float]) -> None
• Span.get_metrics: () -> dict[str, int | float]

매개변수 변경 (Parameter changes)

• Span.record_exception: timestamp 및 escaped 매개변수가 제거됐어요.

프레임워크 및 통합 변경 (Framework and Integration changes)

Django

DD_DJANGO_TRACING_MINIMAL은 기본적으로 true예요.

• 영향: Django ORM, 캐시, 템플릿 계측이 기본적으로 비활성화돼요. 이는 성능 오버헤드를 줄이고(기본 라이브러리인 psycopg, redis, jinja2가 자체 통합에 의해 계측되므로) 중복 스팬을 제거해요.
• 데이터베이스 스팬: DD_DJANGO_INSTRUMENT_DATABASES=true(기본값 false)일 때 SDK는 별도 스팬을 만들지 않고 Django 전용 태그를 드라이버 스팬에 병합해요.
• 복원: 전체 Django 계측을 복원하려면 DD_DJANGO_TRACING_MINIMAL=false로 설정하세요.

OpenAI

스트리밍된 chat/completions는 토큰 수를 계산하는 데 tiktoken을 사용하지 않아요.

• 조치: 정확한 스트리밍 토큰 메트릭을 보장하려면 OpenAI 요청에 stream_options={"include_usage": True}를 설정하세요.

Agent 관찰 가능성 (Agent Observability)

• 수동 계측: 다음 메서드는 오류를 기록하는 대신 예외를 발생시켜요: LLMObs.annotate(), LLMObs.export_span(), LLMObs.submit_evaluation(), LLMObs.inject_distributed_headers(), LLMObs.activate_distributed_headers().
• 이름 변경: LLMObs.submit_evaluation_for()는 제거됐어요. LLMObs.submit_evaluation()을 사용하고 span_context 인자를 span으로 이름을 바꾸세요.

제거된 통합 (Removed integrations)

다음 라이브러리는 더 이상 지원되지 않아요:

• google_generativeai: google_genai 라이브러리와 통합을 사용하세요.
• Mongoengine: ddtrace.Pin 지원이 제거됐어요. pymongo 통합을 사용하세요.
• Aioredis
• Freezegun
• Opentracer

프로파일링 (Profiling)

• V1 스택 프로파일러가 제거됐어요. V2가 기본이에요.
• echion(Python 스택 샘플러)에는 실험적인 더 빠른 메모리 복사 함수가 포함돼요.

CI Visibility

• Pytest: pytest_benchmark 및 pytest_bdd에 대한 폐기된 진입점은 제거됐어요. 표준 pytest 통합이 이러한 플러그인을 지원해요.
• 전파 (Propagation): 폐기된 non_active_span 매개변수가 HttpPropagator.inject에서 제거됐어요.

3단계: 라이브러리 업그레이드 (Step 3: Upgrade the library)

주요 변경 사항을 처리한 후 새 버전을 설치하세요:

pip install --upgrade ddtrace

더 알아보기 (Learn more)

• 릴리스 노트
• Python 트레이싱 설정