{"id":194,"library":"ddtrace","title":"Datadog Python APM Tracer (ddtrace)","description":"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.","status":"active","version":"4.6.4","language":"python","source_language":"en","source_url":"https://github.com/DataDog/dd-trace-py","tags":["datadog","ddtrace","apm","tracing","observability","python","monitoring"],"install":[{"cmd":"pip install ddtrace","lang":"bash","label":"Python"}],"dependencies":[{"reason":"Required separately. ddtrace sends traces to a local Agent process. Install from datadoghq.com/agent.","package":"Datadog Agent","optional":false}],"imports":[{"wrong":"from .. import patch_all","symbol":"patch_all","correct":"from ddtrace import patch_all"},{"wrong":"from .. import tracer","symbol":"tracer","correct":"from ddtrace import tracer"},{"wrong":"from .. import config","symbol":"config","correct":"from ddtrace import config"}],"quickstart":{"code":"# pip install ddtrace\n# Requires Datadog Agent running at localhost:8126\n\n# Option 1: ddtrace-run (recommended)\n# DD_SERVICE=my-app DD_ENV=prod ddtrace-run python app.py\n\n# Option 2: manual patch at top of entry point (before all other imports)\nfrom ddtrace import patch\npatch(all=True)  # must be before any library imports\n\n# OR selectively:\n# patch(requests=True, sqlalchemy=True, redis=True)\n\nimport flask  # patched because patch() was called first\n\nfrom ddtrace import tracer\n\napp = flask.Flask(__name__)\n\n@app.route('/checkout')\ndef checkout():\n    with tracer.trace('checkout.process', resource='checkout') as span:\n        span.set_tag('user.id', flask.request.args.get('user_id'))\n        # Unified Service Tagging via env vars:\n        # DD_SERVICE, DD_ENV, DD_VERSION\n        return 'ok'\n\n# Check agent connectivity:\n# ddtrace-run --info","lang":"python","description":"ddtrace — auto-instrumentation via ddtrace-run and custom spans."},"warnings":[{"fix":"v4 requires Python 3.9+. v3 requires Python 3.8+. v2 requires Python 3.7+.","message":"v4.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.","severity":"breaking","affected_versions":"all"},{"fix":"Remove Pin usage. Configure integrations via environment variables or ddtrace.config instead.","message":"Pin class removed in v4.0. Code using Pin.get_from(), Pin.override(), ddtrace.Pin raises ImportError.","severity":"breaking","affected_versions":">= 4.0"},{"fix":"Use span.set_tag('key', 'value') for all tag types.","message":"Span.set_tag_str() removed in v4.0. Raises AttributeError.","severity":"breaking","affected_versions":">= 4.0"},{"fix":"Use environment variables (DD_TRACE_*, DD_SERVICE, etc.) for configuration.","message":"ddtrace.settings package removed in v4.0. Code importing from ddtrace.settings raises ImportError.","severity":"breaking","affected_versions":">= 4.0"},{"fix":"Use ddtrace-run CLI wrapper which handles import order automatically.","message":"patch_all() and patch() must be called BEFORE the library being instrumented is imported. Calling after import silently produces no instrumentation.","severity":"breaking","affected_versions":"all"},{"fix":"Remove DD_CALL_BASIC_CONFIG from environment. ddtrace now logs to stdout by default.","message":"DD_CALL_BASIC_CONFIG removed in v2.0. Raises error if set.","severity":"breaking","affected_versions":">= 2.0"},{"fix":"Run Datadog Agent before starting app. Verify with: ddtrace-run --info. Override with DD_AGENT_HOST and DD_TRACE_AGENT_PORT.","message":"Datadog Agent must be running at localhost:8126 (default). Without it, traces are silently dropped — no error raised.","severity":"gotcha","affected_versions":"all"},{"fix":"Set DD_SERVICE=my-service DD_ENV=production DD_VERSION=1.0.0 before running.","message":"Unified Service Tagging requires DD_SERVICE, DD_ENV, DD_VERSION env vars. Without them, services appear as unnamed in Datadog UI.","severity":"gotcha","affected_versions":"all"},{"fix":"Use `ddtrace.patch_all()` to instrument all available integrations, or specify individual integrations using `ddtrace.patch(integration_name=True, ...)`.","message":"Calling `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)`).","severity":"breaking","affected_versions":"all"},{"fix":"Use ddtrace.patch_all() to instrument all available integrations, or ddtrace.patch('integration_name') for specific ones.","message":"Calling ddtrace.patch(all=True) is incorrect and will raise a ModuleNotFoundException. 'all' is not a valid module name for selective patching.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"search_vec":"'/3.5/3.6':26 '2.7':25 '2023':21 '2026':15 '3.7':35 '3.8':43 '4.6.4':13 'agent':70 'apm':3,7,83 'auto':74 'auto-instrument':73 'basic':30 'break':17 'call':29 'class':46 'cli':60 'code':67 'config':31,38 'current':11 'datadog':1,6,69,81 'dd':28 'ddtrace':5,58,82 'ddtrace-run':57 'ddtrace.settings':52 'deprec':37 'drop':23,33,41 'import':63,79 'instrument':75 'librari':10,77 'major':18 'mar':14 'monitor':87 'name':39 'observ':85 'packag':53 'patch':64,76 'pin':45 'prefer':54 'python':2,8,24,34,42,86 'remov':27,36,44,47,51 'requir':68 'run':59,71 'separ':72 'sinc':20 'span.set':48 'str':50 'tag':49 'three':16 'time':80 'trace':9,84 'tracer':4 'usag':55 'v2':22 'v3':32 'v4':40 'version':12,19 'wrapper':61","created_at":"2026-03-25T16:33:38.235309+00:00","updated_at":"2026-04-16T05:56:28.471494+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":80,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"4.10.3","cli_name":"ddtrace-run","cli_version":"ddtrace-run 4.8.4","type":"library","homepage":"https://www.datadoghq.com/","github":"https://github.com/DataDog/dd-trace-py","docs":"https://ddtrace.readthedocs.io/en/stable/","changelog":"https://github.com/DataDog/dd-trace-py/releases","pypi":"https://pypi.org/project/ddtrace/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":"verified"}}