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

원문 보기 위키 갱신 2026.10.05

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

출처: 문서

본문

dd-trace-py 버전 3.0.0은 Python 3.7 지원을 중단하고 이전에 폐기(deprecated)된 API를 제거해요. 이 가이드는 애플리케이션을 업그레이드하는 데 도움을 주는 단계를 제공해요.

v3.0.0 릴리스와 함께 2.x 릴리스 라인은 유지보수 모드에 있어요. 중요한 버그 수정만 백포트되어야 해요. 자세한 내용은 버전 지원 정책을 참고하세요.

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

원활한 전환을 위해 먼저 최신 v2 릴리스(2.21.0)로 업그레이드하고 다음 도구를 사용해 v3에서 깨질 폐기된 코드를 찾으세요.

테스트에서 (In tests)

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

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

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

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

PYTHONWARNINGS=all python app.py

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

잠재적 문제를 식별한 후 다음 주요 변경 사항을 검토하세요. 업그레이드를 진행하기 전에 코드가 v3과 호환되도록 업데이트하세요.

환경 변수 변경 (Environment variable changes)

다음 환경 변수가 제거되거나 대체됐어요. 해당하는 경우 새 변수로 구성을 업데이트하세요.

다음 명령을 사용해 코드베이스에서 이 폐기된 변수의 모든 항목을 찾을 수 있어요:

git grep -P -e "DD_LLMOBS_APP_NAME" \
  -e "_DD_LLMOBS_EVALUATOR_SAMPLING_RULES" \
  -e "_DD_LLMOBS_EVALUATORS" \
  -e "DD_TRACE_PROPAGATION_STYLE=.*b3 single header" \
  -e "DD_TRACE_SAMPLE_RATE" \
  -e "DD_TRACE_API_VERSION=v0.3" \
  -e "DD_ANALYTICS_ENABLED" \
  -e "DD_TRACE_ANALYTICS_ENABLED" \
  -e "DD_HTTP_CLIENT_TAG_QUERY_STRING" \
  -e "DD_TRACE_SPAN_AGGREGATOR_RLOCK" \
  -e "DD_TRACE_METHODS=.*\[\]"

폐기 항목 (Deprecation)	필수 조치 (Action Required)
`DD_ANALYTICS_ENABLED`	제거됨. 동작 없음(no-op). 대안은 Ingestion Controls를 참고하세요.
`DD_HTTP_CLIENT_TAG_QUERY_STRING`	대신 `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING`을 사용하세요.
`DD_LLMOBS_APP_NAME`	대신 `DD_LLMOBS_ML_APP`을 사용하세요.
`_DD_LLMOBS_EVALUATOR_SAMPLING_RULES`	대신 `DD_LLMOBS_EVALUATOR_SAMPLING_RULES`을 사용하세요(앞의 밑줄 제외).
`_DD_LLMOBS_EVALUATORS`	대신 `DD_LLMOBS_EVALUATORS`를 사용하세요(앞의 밑줄 제외).
`DD_PYTEST_USE_NEW_PLUGIN_BETA`	제거됨. 새 pytest 플러그인이 기본이며 더 이상 베타가 아니에요.
`DD_TRACE_ANALYTICS_ENABLED`	제거됨. 동작 없음(no-op). 대안은 Ingestion Controls를 참고하세요.
`DD_TRACE_METHODS` (`[]` 표기법 사용)	`:` 표기법을 사용해야 해요. 예: `mod.submod:method2;mod.submod:Class.method1`. 자세한 내용은 DD_TRACE_METHODS 문서를 참고하세요.
`DD_TRACE_PROPAGATION_STYLE="b3 single header"`	동일한 동작을 위해 `DD_TRACE_PROPAGATION_STYLE=b3`을 사용하세요.
`DD_TRACE_SAMPLE_RATE`	대신 `DD_TRACE_SAMPLING_RULES`을 사용하세요. 자세한 내용은 User-Defined Rules을 참고하세요.
`DD_TRACE_SPAN_AGGREGATOR_RLOCK`	제거됨. 이 기능은 제거되었으며 변수는 동작 없음(no-op)이에요.

정보 이 변경 사항은 dd-trace-py 구성에만 적용되며 Datadog Agent에는 적용되지 않아요.

API 및 인터페이스 변경 (API and interface changes)

다음 메서드, 속성, 동작이 제거되거나 변경됐어요.

일반 (General)

Python 3.7 지원: Python 3.7 지원이 제거됐어요.

트레이싱 (Tracing)

여러 Tracer 인스턴스: 여러 Tracer 인스턴스 지원이 제거됐어요. 전역 ddtrace.tracer 인스턴스를 사용해야 해요.
Tracer.configure(): 폐기된 매개변수가 제거됐어요. Agent 연결 세부 정보(hostname, port), 샘플링 및 기타 설정을 구성하려면 환경 변수를 사용하세요.
Span.sampled: 이 속성이 제거됐어요. 스팬이 샘플링되었는지 확인하려면 span.context.sampling_priority > 0을 사용하세요.
ddtrace.opentracer: _dd_tracer 속성이 제거됐어요. 대신 전역 ddtrace.tracer를 사용하세요.
LLMObs.annotate(): parameters 인자가 제거됐어요. 대신 metadata를 사용하세요.
choose_matcher(): 콜러블과 정규식 패턴은 더 이상 ddtrace.tracer.sampler.rules[].choose_matcher의 인자로 허용되지 않아요. 문자열을 전달해야 해요.

Agent 관찰 가능성 (Agent Observability)

OpenAI 및 Langchain: OpenAI v0.x 및 Langchain v0.0.x 지원이 중단됐어요.

CI Visibility

새 pytest 플러그인이 기본이에요.
모듈, 스위트, 테스트 이름이 item.nodeid에서 파싱돼요.
클래스 기반 테스트의 테스트 이름에는 클래스 이름이 포함돼요(예: TestClass::test_method).
테스트 건너뛰기가 스위트 레벨에서 수행돼요.

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

주요 변경 사항을 처리하도록 코드를 업데이트한 후 최신 v3 릴리스로 업그레이드할 수 있어요.

pip install --upgrade ddtrace

Python 3.13 호환성 (Python 3.13 compatibility)

Python 3.13의 전체 지원은 활발히 개발 중이에요. 코어 SDK는 호환되지만 일부 통합은 최신 버전에서 완전히 테스트되거나 지원되지 않을 수 있어요.

특정 통합의 최신 호환성 세부 정보는 라이브러리의 최신 릴리스 노트를 참고하세요.

더 알아보기 (Learn more)

dd-trace-py 릴리스