Tracing Python Applications
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

Tracing Python Applications

Compatibility requirements

Python versions 2.7+ and 3.5+ are supported. For a full list of supported libraries, visit the Compatibility Requirements page.

Installation and getting started

Follow the Quickstart instructions within the Datadog app for the best experience, including:

  • Step-by-step instructions scoped to your deployment configuration (hosts, Docker, Kubernetes, or Amazon ECS).
  • Dynamically set service, env, and version tags.
  • Enable the Continuous Profiler, ingesting 100% of traces, and Trace ID injection into logs during setup.

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 then:

ddtrace-run python

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


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

Environment VariableDefaultDescription
DATADOG_TRACE_DEBUGfalseEnable debug logging in the tracer.
DATADOG_PATCH_MODULESOverride the modules patched for this application execution. It should follow the format: DATADOG_PATCH_MODULES=module:patch,module:patch....

It is recommended to use DD_ENV, DD_SERVICE, and DD_VERSION to set env, service, and version for your services. Refer to the Unified Service Tagging documentation for recommendations on how to configure these environment variables.

Environment VariableDefaultDescription
DD_ENVSet the application’s environment, for example: prod, pre-prod, staging. Learn more about how to setup your environment. Available in version 0.38+.
DD_SERVICEThe service name to be used for this application. The value is passed through when setting up middleware for web framework integrations like Pylons, Flask, or Django. For tracing without a web integration, it is recommended that you set the service name in code. Available in version 0.38+.
DD_VERSIONSet the application’s version, for example: 1.2.3, 6c44da20, 2020.02.13. Available in version 0.38+.
DD_TAGSA list of default tags to be added to every span, profile, and runtime metric, for example: layer:api,team:intake. Available in version 0.38+.
DATADOG_TRACE_ENABLEDtrueEnable web framework and library instrumentation. When false, the application code doesn’t generate any traces.
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 trace injection.

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.

But you can also set the hostname and port in code:

import os
from ddtrace import tracer


Further Reading