Tracing Python Applications
Security Monitoring is now available Security Monitoring is now available

Tracing Python Applications

For Python Django applications, note that tracing is disabled when your application is launched in DEBUG mode. Find more here.

Installation and Getting Started

If you already have a Datadog account you can find step-by-step instructions in our in-app guides for either host-based or container-based set ups.

Otherwise, to begin tracing applications written in Python, first install and configure the Datadog Agent, see the additional documentation for tracing Docker applications or Kubernetes applications.

Next, install the Datadog Tracing library, ddtrace, using pip:

pip install ddtrace

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

For more advanced usage, configuration, and fine-grain control, see Datadog’s API documentation.

Environment variables

When using ddtrace-run, the following environment variable options can be used:

Environment VariableDefaultDescription
DD_ENVSet the application’s environment e.g. prod, pre-prod, staging. Learn more about how to setup your environment.
DD_VERSIONSet the application’s version e.g. 1.2.3, 6c44da20, 2020.02.13.
DD_SERVICEThe service name to be used for this application. The value is passed through when setting up middleware for web framework integrations (e.g. Pylons, Flask, Django). For tracing without a web integration, it is recommended that you set the service name in code.
DATADOG_TRACE_ENABLEDtrueEnable web framework and library instrumentation. When false, the application code doesn’t generate any traces.
DATADOG_TRACE_DEBUGfalseEnable debug logging in the tracer. Note that this is not available with Django.
DATADOG_PATCH_MODULESOverride the modules patched for this application execution. It should follow this format: DATADOG_PATCH_MODULES=module:patch,module:patch....
DD_AGENT_HOSTlocalhostOverride the address of the trace Agent host that the default tracer attempts to submit traces to.
DATADOG_TRACE_AGENT_PORT8126Override the port that the default tracer submit traces to.
DD_TRACE_AGENT_URLThe URL of the Trace Agent that the tracer submits to. Takes priority over hostname and port, if set. Supports Unix Domain Sockets in combination with the apm_config.receiver_socket in your datadog.yaml file, or the DD_APM_RECEIVER_SOCKET environment variable.
DATADOG_PRIORITY_SAMPLINGtrueEnable Priority Sampling.
DD_LOGS_INJECTIONfalseEnable connecting logs and traces Injection.
DD_TRACE_ANALYTICS_ENABLEDfalseEnable App Analytics globally for web integrations.
DD_INTEGRATION_ANALYTICS_ENABLEDfalseEnable App Analytics for a specific integration. Example: DD_BOTO_ANALYTICS_ENABLED=true .

Change Agent Hostname

Configure your application level tracers to submit traces to a custom Agent hostname. The Python Tracing Module automatically looks for and initializes with the ENV variables DD_AGENT_HOST and DD_TRACE_AGENT_PORT

import os
from ddtrace import tracer

tracer.configure(
    hostname=os.environ['DD_AGENT_HOST'],
    port=os.environ['DD_TRACE_AGENT_PORT'],
)

Compatibility

Python versions 2.7 and 3.4 and onwards are supported.

Integrations

Web Framework Compatibility

The ddtrace library includes support for a number of web frameworks, including:

FrameworkSupported VersionPyPi Datadog Documentation
aiohttp>= 1.2http://pypi.datadoghq.com/trace/docs/web_integrations.html#aiohttp
Bottle>= 0.11http://pypi.datadoghq.com/trace/docs/web_integrations.html#bottle
Django>= 1.8http://pypi.datadoghq.com/trace/docs/web_integrations.html#django
djangorestframework>= 3.4http://pypi.datadoghq.com/trace/docs/web_integrations.html#django
Falcon>= 1.0http://pypi.datadoghq.com/trace/docs/web_integrations.html#falcon
Flask>= 0.10http://pypi.datadoghq.com/trace/docs/web_integrations.html#flask
Molten>= 0.7.0http://pypi.datadoghq.com/trace/docs/web_integrations.html#molten
Pylons>= 0.9.6http://pypi.datadoghq.com/trace/docs/web_integrations.html#pylons
Pyramid>= 1.7http://pypi.datadoghq.com/trace/docs/web_integrations.html#pyramid
Tornado>= 4.0http://pypi.datadoghq.com/trace/docs/web_integrations.html#tornado

Datastore Compatibility

The ddtrace library includes support for the following data stores:

DatastoreSupported VersionPyPi Datadog Documentation
Cassandra>= 3.5http://pypi.datadoghq.com/trace/docs/db_integrations.html#cassandra
Elasticsearch>= 1.6http://pypi.datadoghq.com/trace/docs/db_integrations.html#elasticsearch
Flask Cache>= 0.12http://pypi.datadoghq.com/trace/docs/db_integrations.html#flask-cache
Memcached pylibmc>= 1.4http://pypi.datadoghq.com/trace/docs/db_integrations.html#pylibmc
Memcached pymemcache>= 1.3http://pypi.datadoghq.com/trace/docs/db_integrations.html#pymemcache
MongoDB Mongoengine>= 0.11http://pypi.datadoghq.com/trace/docs/db_integrations.html#mongoengine
MongoDB Pymongo>= 3.0http://pypi.datadoghq.com/trace/docs/db_integrations.html#pymongo
MySQL MySQL-python>= 1.2.3http://pypi.datadoghq.com/trace/docs/db_integrations.html#module-ddtrace.contrib.mysqldb
MySQL mysqlclient>= 1.3http://pypi.datadoghq.com/trace/docs/db_integrations.html#module-ddtrace.contrib.mysqldb
MySQL mysql-connector>= 2.1http://pypi.datadoghq.com/trace/docs/db_integrations.html#mysql-connector
Postgres aiopg>= 0.12.0http://pypi.datadoghq.com/trace/docs/db_integrations.html#aiopg
Postgres psycopg>= 2.4http://pypi.datadoghq.com/trace/docs/db_integrations.html#module-ddtrace.contrib.psycopg
Redis>= 2.6http://pypi.datadoghq.com/trace/docs/db_integrations.html#redis
Redis redis-py-cluster>= 1.3.5http://pypi.datadoghq.com/trace/docs/db_integrations.html#module-ddtrace.contrib.rediscluster
SQLAlchemy>= 1.0http://pypi.datadoghq.com/trace/docs/db_integrations.html#sqlalchemy
SQLite3Fully Supportedhttp://pypi.datadoghq.com/trace/docs/db_integrations.html#sqlite
Vertica>= 0.6http://pypi.datadoghq.com/trace/docs/db_integrations.html#vertica

Library Compatibility

The ddtrace library includes support for the following libraries:

LibrarySupported VersionPyPi Datadog Documentation
asyncioFully Supportedhttp://pypi.datadoghq.com/trace/docs/async_integrations.html#asyncio
gevent>= 1.0http://pypi.datadoghq.com/trace/docs/async_integrations.html#gevent
aiobotocore>= 0.2.3http://pypi.datadoghq.com/trace/docs/other_integrations.html#aiobotocore
Boto2>= 2.29.0http://pypi.datadoghq.com/trace/docs/other_integrations.html#boto2
Botocore>= 1.4.51http://pypi.datadoghq.com/trace/docs/other_integrations.html#botocore
Celery>= 4.0.2http://pypi.datadoghq.com/trace/docs/other_integrations.html#celery
FuturesFully Supportedhttp://pypi.datadoghq.com/trace/docs/other_integrations.html#futures
Grpc>= 1.8.0http://pypi.datadoghq.com/trace/docs/other_integrations.html#grpc
httplibFully Supportedhttp://pypi.datadoghq.com/trace/docs/other_integrations.html#httplib
Jinja2>= 2.7http://pypi.datadoghq.com/trace/docs/other_integrations.html#jinja2
Kombu>= 4.0http://pypi.datadoghq.com/trace/docs/other_integrations.html#kombu
Mako>= 0.1.0http://pypi.datadoghq.com/trace/docs/other_integrations.html#mako
Requests>= 2.08http://pypi.datadoghq.com/trace/docs/other_integrations.html#requests

Further Reading