Configuring the Python Tracing Library

After you set up the tracing library with your code and configure the Agent to collect APM data, optionally configure the tracing library as desired, including setting up Unified Service Tagging.

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

DD_TRACE_DEBUG: Default: false
Enable debug logging in the tracer.
DD_PATCH_MODULES: Override the modules patched for this application execution. Follow the format: DD_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.

DD_ENV

Set the application’s environment, for example: prod, pre-prod, staging. Learn more about how to setup your environment. Available in version 0.38+.

DD_SERVICE

The 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 (for example, see these Django docs). Available in version 0.38+.

DD_TRACE_PROPAGATION_STYLE_INJECT

Default: Datadog
Propagation styles to use when injecting tracing headers. For example, use DD_TRACE_PROPAGATION_STYLE_INJECT=Datadog,B3 to inject both Datadog and B3 format headers.

DD_TRACE_PROPAGATION_STYLE_EXTRACT

Default: Value of DD_TRACE_PROPAGATION_STYLE_INJECT (Datadog)
Propagation styles to use when extracting tracing headers. When multiple values are given, it uses the first header match found. The order of matching is static and unrelated to the order of values given. For example: DD_TRACE_PROPAGATION_STYLE_EXTRACT=B3,Datadog produces the same behavior as DD_TRACE_PROPAGATION_STYLE_EXTRACT=Datadog,B3.

DD_SERVICE_MAPPING

Define service name mappings to allow renaming services in traces, for example: postgres:postgresql,defaultdb:postgresql. Available in version 0.47+.

DD_VERSION

Set the application’s version, for example: 1.2.3, 6c44da20, 2020.02.13. Available in version 0.38+.

DD_TRACE_SAMPLE_RATE

Enable trace volume control

DD_TRACE_SAMPLING_RULES

Default: []
A JSON array of objects. Each object must have a "sample_rate". The "name" and "service" fields are optional. The "sample_rate" value must be between 0.0 and 1.0 (inclusive). Rules are applied in configured order to determine the trace’s sample rate.

DD_TRACE_RATE_LIMIT

Maximum number of spans to sample per-second, per-Python process. Defaults to 100 when DD_TRACE_SAMPLE_RATE is set. Otherwise, delegates rate limiting to the Datadog Agent.

DD_SPAN_SAMPLING_RULES

Default: []
A JSON array of objects. Rules are applied in configured order to determine the span’s sample rate. The sample_rate value must be between 0.0 and 1.0 (inclusive). For more information, see Ingestion Mechanisms.
Example:

Set the span sample rate to 50% for the service my-service and operation name http.request, up to 50 traces per second: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'

DD_TAGS

A list of default tags to be added to every span and profile, for example: layer:api,team:intake. Available in version 0.38+.

DD_TRACE_HEADER_TAGS

Default: null
Comma-separated list of header names that are reported on the root span as tags. For example, DD_TRACE_HEADER_TAGS="User-Agent:http.user_agent,Referer:http.referer,Content-Type:http.content_type,Etag:http.etag".

DD_TRACE_ENABLED

Default: true
Enable web framework and library instrumentation. When false, the application code doesn’t generate any traces.

DD_AGENT_HOST

Default: localhost
Override the address of the trace Agent host that the default tracer attempts to submit traces to.

DD_AGENT_PORT

Default: 8126
Overrides the port that the default tracer submit traces to. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then DD_AGENT_PORT or DD_TRACE_AGENT_URL must match it.

DD_TRACE_AGENT_URL

The URL of the Trace Agent that the tracer submits to. If set, this takes priority over hostname and port. Supports Unix Domain Sockets (UDS) in combination with the apm_config.receiver_socket configuration in your datadog.yaml file or the DD_APM_RECEIVER_SOCKET environment variable set on the Datadog Agent. For example, DD_TRACE_AGENT_URL=http://localhost:8126 for HTTP URL and DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket for UDS. If the Agent configuration sets receiver_port or DD_APM_RECEIVER_PORT to something other than the default 8126, then DD_AGENT_PORT or DD_TRACE_AGENT_URL must match it.

DD_DOGSTATSD_URL

The URL used to connect to the Datadog Agent for DogStatsD metrics. If set, this takes priority over hostname and port. Supports Unix Domain Sockets (UDS) in combination with the dogstatsd_socket configuration in your datadog.yaml file or the DD_DOGSTATSD_SOCKET environment variable set on the Datadog Agent. For example, DD_DOGSTATSD_URL=udp://localhost:8126 for UDP URL and DD_DOGSTATSD_URL=unix:///var/run/datadog/dsd.socket for UDS. If the Agent configuration sets dogstatsd_port or DD_DOGSTATSD_PORT to something other than the default 8125, then this tracing library DD_DOGSTATSD_URL or DD_DOGSTATSD_PORT must match it.

DD_DOGSTATSD_HOST

Default: localhost
Override the address of the trace Agent host that the default tracer attempts to submit DogStatsD metrics to. Use DD_AGENT_HOST to override DD_DOGSTATSD_HOST.

DD_DOGSTATSD_PORT

Default: 8125
Override the port that the default tracer submits DogStatsD metrics to. If the Agent configuration sets dogstatsd_port or DD_DOGSTATSD_PORT to something other than the default 8125, then this tracing library DD_DOGSTATSD_PORT or DD_DOGSTATSD_URL must match it.

DD_LOGS_INJECTION

Default: false
Enable connecting logs and trace injection.

Configuring the Python Tracing Library

Further Reading