Datadog Python APM Tracer (ddtrace)

Warnings

• breaking 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.
  Fix: v4 requires Python 3.9+. v3 requires Python 3.8+. v2 requires Python 3.7+.
• breaking Pin 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.
• breaking Span.set_tag_str() removed in v4.0. Raises AttributeError.
  Fix: Use span.set_tag('key', 'value') for all tag types.
• breaking ddtrace.settings package removed in v4.0. Code importing from ddtrace.settings raises ImportError.
  Fix: Use environment variables (DD_TRACE_*, DD_SERVICE, etc.) for configuration.
• breaking patch_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.
• breaking DD_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.
• gotcha Datadog 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.
• gotcha Unified 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.

Install

• pip install ddtrace Python

Imports

• ddtrace-run (preferred — auto-instrumentation)

  # Preferred: use ddtrace-run CLI wrapper
  # This patches libraries at startup before your code imports them
  
  # Set env vars:
  # DD_SERVICE=my-service
  # DD_ENV=production
  # DD_VERSION=1.0.0
  # DD_AGENT_HOST=localhost  (default)
  # DD_TRACE_AGENT_PORT=8126  (default)
  
  # Run your app:
  # ddtrace-run python app.py
  # ddtrace-run gunicorn app:application
  # ddtrace-run uvicorn app:app
  
  # Verify config:
  # ddtrace-run --info

  patch_all() and patch() must be called BEFORE the library being patched is imported. ddtrace-run handles this automatically. In code, call patch() at the very top of the entry point before any other imports.
• Manual tracing (custom spans)

  from ddtrace import tracer
  
  # Custom span
  with tracer.trace('my.operation', service='my-service', resource='checkout') as span:
      span.set_tag('user.id', '123')
      span.set_tag('order.id', 'ord-456')
      # do work
  
  # Decorator
  from ddtrace import tracer
  
  @tracer.wrap(service='my-service', resource='process_payment')
  def process_payment(order_id):
      pass
  
  # Error tracking
  try:
      risky_operation()
  except Exception as e:
      span.error = 1
      span.set_tag('error.msg', str(e))
      raise

  Pin class removed in v4. set_tag_str() removed in v4 — use set_tag() for all tag types. ddtrace.settings package removed in v4 — use environment variables instead.

Quickstart

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