ddtrace

library4.6.4pypypi✓ verified 50d ago

Datadog APM Python tracing library. Current version: 4.6.4 (Mar 2026). Three breaking major versions since 2023: v2 (dropped Python 2.7/3.5/3.6, removed DD_CALL_BASIC_CONFIG), v3 (dropped Python 3.7, removed deprecated config names), v4 (dropped Python 3.8, removed Pin class, removed Span.set_tag_str, removed ddtrace.settings package). Preferred usage is ddtrace-run CLI wrapper — NOT importing patch_all() in code. Requires Datadog Agent running separately. Auto-instrumentation patches libraries at import time.

observability

pip install ddtrace

github ↗package ↗homepage ↗docs ↗changelog ↗

Install & Compatibility

Where this runs

tested against v4.8.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.000s · 59.9MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 6.9s · import 0.000s · 57MB

58MB installed

● package 58MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

patch_all

✓ from ddtrace import patch_all

✗ from .. import patch_all

tracer

✓ from ddtrace import tracer

✗ from .. import tracer

config

✓ from ddtrace import config

✗ from .. import config

ddtrace — auto-instrumentation via ddtrace-run and custom spans.

# pip install ddtrace # Requires Datadog Agent running at localhost:8126 # Option 1: ddtrace-run (recommended) # DD_SERVICE=my-app DD_ENV=prod ddtrace-run python app.py # Option 2: manual patch at top of entry point (before all other imports) from ddtrace import patch patch(all=True) # must be before any library imports # OR selectively: # patch(requests=True, sqlalchemy=True, redis=True) import flask # patched because patch() was called first from ddtrace import tracer app = flask.Flask(__name__) @app.route('/checkout') def checkout(): with tracer.trace('checkout.process', resource='checkout') as span: span.set_tag('user.id', flask.request.args.get('user_id')) # Unified Service Tagging via env vars: # DD_SERVICE, DD_ENV, DD_VERSION return 'ok' # Check agent connectivity: # ddtrace-run --info

ddtrace-run --version

Debug

Known issues

breakingv4.0.0 dropped Python 3.8. v3.0.0 dropped Python 3.7. v2.0.0 dropped Python 2.7/3.5/3.6. Check Python version before upgrading major versions.

fix

v4 requires Python 3.9+. v3 requires Python 3.8+. v2 requires Python 3.7+.

affects: all

breakingPin class removed in v4.0. Code using Pin.get_from(), Pin.override(), ddtrace.Pin raises ImportError.

fix

Remove Pin usage. Configure integrations via environment variables or ddtrace.config instead.

affects: >= 4.0

breakingSpan.set_tag_str() removed in v4.0. Raises AttributeError.

fix

Use span.set_tag('key', 'value') for all tag types.

affects: >= 4.0

breakingddtrace.settings package removed in v4.0. Code importing from ddtrace.settings raises ImportError.

fix

Use environment variables (DD_TRACE_*, DD_SERVICE, etc.) for configuration.

affects: >= 4.0

breakingpatch_all() and patch() must be called BEFORE the library being instrumented is imported. Calling after import silently produces no instrumentation.

fix

Use ddtrace-run CLI wrapper which handles import order automatically.

affects: all

breakingDD_CALL_BASIC_CONFIG removed in v2.0. Raises error if set.

fix

Remove DD_CALL_BASIC_CONFIG from environment. ddtrace now logs to stdout by default.

affects: >= 2.0

gotchaDatadog Agent must be running at localhost:8126 (default). Without it, traces are silently dropped — no error raised.

fix

Run Datadog Agent before starting app. Verify with: ddtrace-run --info. Override with DD_AGENT_HOST and DD_TRACE_AGENT_PORT.

affects: all

gotchaUnified Service Tagging requires DD_SERVICE, DD_ENV, DD_VERSION env vars. Without them, services appear as unnamed in Datadog UI.

fix

Set DD_SERVICE=my-service DD_ENV=production DD_VERSION=1.0.0 before running.

affects: all

breakingCalling `ddtrace.patch(all=True)` is incorrect and will raise `ddtrace._monkey.ModuleNotFoundException`. The `patch` function expects specific integration names as keyword arguments (e.g., `patch(flask=True)`).

fix

Use `ddtrace.patch_all()` to instrument all available integrations, or specify individual integrations using `ddtrace.patch(integration_name=True, ...)`.

affects: all

breakingCalling ddtrace.patch(all=True) is incorrect and will raise a ModuleNotFoundException. 'all' is not a valid module name for selective patching.

fix

Use ddtrace.patch_all() to instrument all available integrations, or ddtrace.patch('integration_name') for specific ones.

affects: all

Upgrade

Version history

4.10.3latest on PyPI

Audit

Dependencies

Datadog AgentrequiredRequired separately. ddtrace sends traces to a local Agent process. Install from datadoghq.com/agent.

Agent activity

36 hits · last 30 days

node

mj12bot

seranking-bot

Amazon

ahrefsbot

bingbot

amazonbot

bytedance

Resources

githubhttps://github.com/DataDog/dd-trace-py ↗

packagehttps://pypi.org/project/ddtrace/ ↗

homepagehttps://www.datadoghq.com/ ↗

docshttps://ddtrace.readthedocs.io/en/stable/ ↗

changeloghttps://github.com/DataDog/dd-trace-py/releases ↗