Tracing Python Applications

Compatibility requirements

The latest Python Tracer supports CPython versions 2.7 and 3.5-3.10.

For a full list of Datadog’s Python version and framework support (including legacy and maintenance versions), read 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.

Configure the Datadog Agent for APM

Install and configure the Datadog Agent to receive traces from your now instrumented application. By default the Datadog Agent is enabled in your datadog.yaml file under apm_config with enabled: true and listens for trace data by default at http://localhost:8126. For containerized environments, follow the links below to enable trace collection within the Datadog Agent.

  1. Set apm_non_local_traffic: true in the apm_config section of your main datadog.yaml configuration file.

  2. See the specific setup instructions to ensure that the Agent is configured to receive traces in a containerized environment:

Docker
Kubernetes
Amazon ECS
ECS Fargate

  1. After the application is instrumented, the trace client attempts to send traces to the Unix domain socket /var/run/datadog/apm.socket by default. If the socket does not exist, traces are sent to http://localhost:8126.

    If a different socket, host, or port is required, use the DD_TRACE_AGENT_URL environment variable. Some examples:

    DD_TRACE_AGENT_URL=http://custom-hostname:1234
    DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket
    

    The connection for traces can also be configured in code:

    from ddtrace import tracer
    
    # Network sockets
    tracer.configure(
        https=False,
        hostname="custom-hostname",
        port="1234",
    )
    
    # Unix domain socket configuration
    tracer.configure(
        uds_path="/var/run/datadog/apm.socket",
    )
    

    Similarly, the trace client attempts to send stats to the /var/run/datadog/dsd.socket Unix domain socket. If the socket does not exist then stats are sent to http://localhost:8125.

    If a different configuration is required, the DD_DOGSTATSD_URL environment variable can be used. Some examples:

    DD_DOGSTATSD_URL=udp://custom-hostname:1234
    DD_DOGSTATSD_URL=unix:///var/run/datadog/dsd.socket
    

    The connection for stats can also be configured in code:

    from ddtrace import tracer
    
    # Network socket
    tracer.configure(
      dogstatsd_url="udp://localhost:8125",
    )
    
    # Unix domain socket configuration
    tracer.configure(
      dogstatsd_url="unix:///var/run/datadog/dsd.socket",
    )
    

  1. Set DD_SITE in the Datadog Agent to to ensure the Agent sends data to the right Datadog location.

To set up Datadog APM in AWS Lambda, see the Tracing Serverless Functions documentation.

Tracing is available for a number of other environments, such as Heroku, Cloud Foundry, AWS Elastic Beanstalk, and Azure App Service.

For other environments, please refer to the Integrations documentation for that environment and contact support if you are encountering any setup issues.

Instrument Your Application

Once the agent is installed, to begin tracing applications written in Python, install the Datadog Tracing library, ddtrace, using pip:

pip install ddtrace

Note: This command requires pip version 18.0.0 or greater. For Ubuntu, Debian, or another package manager, update your pip version with the following command:

pip install --upgrade pip

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

Once you’ve finished setup and are running the tracer with your application, you can run ddtrace-run --info to check that configurations are working as expected. Note that the output from this command does not reflect configuration changes made during runtime in code.

Configuration

If needed, configure the tracing library to send application performance telemetry data as you require, including setting up Unified Service Tagging. Read Library Configuration for details.

Upgrading to v1

If you are upgrading to ddtrace v1, review the upgrade guide and the release notes in the library documentation for full details.

Further Reading