Version 3.0.0 of dd-trace-py drops support for Python 3.7 and removes previously deprecated APIs. This guide provides steps to help you upgrade your application.

With the release of v3.0.0, the 2.x release line is in maintenance mode. Only critical bug fixes should be backported. For more details, see the versioning support policy.

Step 1: Detect deprecations

To ensure a smooth transition, first upgrade to the latest v2 release (2.21.0) and use the following tools to find any deprecated code that will break in v3.

In tests

Run pytest with warnings enabled as errors to identify areas in your test suite that need updates:

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

In applications

Set thePYTHONWARNINGS environment variable to surface deprecation warnings when you run your application.

PYTHONWARNINGS=all python app.py

Step 2: Address breaking changes

After identifying potential issues, review the following breaking changes. Update your code to be compatible with v3 before proceeding with the upgrade.

Environment variable changes

The following environment variables have been removed or replaced. Update your configuration with the new variables where applicable.

You can use the following command to find all occurrences of these deprecated variables in your codebase:

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=.*\[\]"

API and interface changes

The following methods, attributes, and behaviors have been removed or changed.

General

• Python 3.7 Support: Support for Python 3.7 is removed.

Tracing

• Multiple Tracer Instances: Support for multiple Tracer instances is removed. You must use the global ddtrace.tracer instance.
• Tracer.configure(): Deprecated parameters have been removed. Use environment variables to configure Agent connection details (hostname, port), sampling, and other settings.
• Span.sampled: This attribute is removed. Use span.context.sampling_priority > 0 to check if a span is sampled.
• ddtrace.opentracer: The _dd_tracer attribute is removed. Use the global ddtrace.tracer instead.
• LLMObs.annotate(): The parameters argument is removed. Use metadata instead.
• choose_matcher(): Callables and regex patterns are no longer allowed as arguments to ddtrace.tracer.sampler.rules[].choose_matcher. You must pass a string.

LLM Observability

• OpenAI and Langchain: Support for OpenAI v0.x and Langchain v0.0.x is dropped.

CI Visibility

• The new pytest plugin is the default.
• Module, suite, and test names are parsed from item.nodeid.
• Test names for class-based tests include the class name (for example, TestClass::test_method).
• Test skipping is performed at the suite level.

Step 3: Upgrade the library

After you have updated your code to address the breaking changes, you can upgrade to the latest v3 release.

pip install --upgrade ddtrace

Python 3.13 compatibility

Full support for Python 3.13 is in active development. While the core tracing library is compatible, some integrations may not be fully tested or supported in the latest version.

For the most current compatibility details for a specific integration, see the library’s latest release notes.