Datadog Python APM Tracer (ddtrace)

Common errors

Warnings

Install compatibility verified last tested: 2026-05-12

Imports

• ddtrace-run (preferred — auto-instrumentation)
  wrong

  # Wrong: patch_all() called after imports — too late to instrument
  import flask
  import sqlalchemy
  from ddtrace import patch_all
  patch_all()  # flask and sqlalchemy already imported — not patched
  
  # Wrong: calling patch() inside app factory — same issue
  def create_app():
      from ddtrace import patch
      patch(flask=True)  # flask already imported above

  correct

  # 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)
  wrong

  # Wrong in v4: Pin class removed
  from ddtrace import Pin
  Pin.override(my_client, service='my-svc')  # ImportError in v4
  
  # Wrong in v4: set_tag_str removed
  span.set_tag_str('key', 'value')  # AttributeError in v4 — use set_tag()

  correct

  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 stale last tested: 2026-04-23

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