Compatibility requirements

For a full list of Datadog’s Python version and framework support (including legacy and maintenance versions), read the Compatibility Requirements page.

Getting started

Before you begin, make sure you’ve already installed and configured the Agent.

Instrument your application

After you install and configure your Datadog Agent, the next step is to add the tracing library directly in the application to instrument it. Read more about compatibility information.

To begin tracing applications written in Python, install the Datadog Tracing library, ddtrace, using pip:

pip install ddtrace

Note: This command requires pip version 18.0.0 or greater. For Ubuntu, Debian, or another package manager, update your pip version with the following command:

pip install --upgrade pip

Then to instrument your Python application use the included ddtrace-run command. To use it, prefix your Python entry-point command with ddtrace-run.

For example, if your application is started with python app.py then:

ddtrace-run python app.py

Once you’ve finished setup and are running the tracer with your application, you can run ddtrace-run --info to check that configurations are working as expected. Note that the output from this command does not reflect configuration changes made during runtime in code.

Configuration

If needed, configure the tracing library to send application performance telemetry data as you require, including setting up Unified Service Tagging. Read Library Configuration for details.

The connection for traces can also be configured in code:

from ddtrace import tracer

# Network sockets
tracer.configure(
    https=False,
    hostname="custom-hostname",
    port="1234",
)

# Unix domain socket configuration
tracer.configure(
    uds_path="/var/run/datadog/apm.socket",
)

The connection for stats can also be configured in code:

from ddtrace import tracer

# Network socket
tracer.configure(
  dogstatsd_url="udp://localhost:8125",
)

# Unix domain socket configuration
tracer.configure(
  dogstatsd_url="unix:///var/run/datadog/dsd.socket",
)

Upgrading to dd-trace-py v3

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 now in maintenance mode. Only critical bug fixes will 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 now 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 now the default.
• Module, suite, and test names are now parsed from item.nodeid.
• Test names for class-based tests now include the class name (for example, TestClass::test_method).
• Test skipping is now performed at the suite level.

Step 3: Upgrade the library

Once 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. The following list details compatibility status as of dd-trace-py v3.0. For the most current information, see the dd-trace-py repository.

Note: dd-trace-py does not work on Windows with Python 3.13.

The following features may be compatible, but have not been verified with Python 3.13:

• Products: AppSec IAST, Code Coverage, Data Streams Monitoring, CI Visibility, Continuous Profiling.
• Features: Automatic Service Naming.
• Integrations: anthropic, consul, freezegun, gevent, google_generativeai, gunicorn, langchain, mysqlclient, opentracing, psycopg, psycopg2, pymysql, pytest, pytest-bdd, pytest-benchmark, sanic, selenium, sqlite3, starlette, tornado, vertexai.
• AppSec Threat Detection: Not tested against Django, Flask, or FastAPI.

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.

Further reading

Additional helpful documentation, links, and articles:

Source codeSOURCE CODE API DocsEXTERNAL SITE Explore your services, resources, and tracesDOCUMENTATION Advanced UsageDOCUMENTATION