Configuration#

ddtrace can be configured using environment variables. Many Integrations can also be configured using environment variables, see specific integration documentation for more details.

The following environment variables for the tracer are supported:

DD_ENV#

Set an application’s environment e.g. prod, pre-prod, staging. Added in v0.36.0. See Unified Service Tagging for more information.

Type: String

Default: (no value)

DD_SERVICE#

Set the service name to be used for this application. A default is provided for these integrations: Bottle, Flask, Grpc, Pyramid, Pylons, Tornado, Celery, Django and Falcon. Added in v0.36.0. See Unified Service Tagging for more information.

Type: String

Default: (autodetected)

DD_SERVICE_MAPPING#

Define service name mappings to allow renaming services in traces, e.g. postgres:postgresql,defaultdb:postgresql.

Type: String

Default: (no value)

DD_TAGS#

Set global tags to be attached to every span. Value must be either comma or space separated. e.g. key1:value1,key2:value2 or key1:value key2:value2.

Type: String

Default: (no value)

Changed in version v0.38.0: Comma separated support added

Changed in version v0.48.0: Space separated support added

DD_VERSION#

Set an application’s version in traces and logs e.g. 1.2.3, 6c44da20, 2020.02.13. Generally set along with DD_SERVICE.

See Unified Service Tagging for more information.

Type: String

Default: (no value)

New in version v0.36.0.

DD_SITE#

Specify which site to use for uploading profiles. Set to datadoghq.eu to use EU site.

Type: String

Default: datadoghq.com

DD_TRACE_ENABLED#

Enable sending of spans to the Agent. Note that instrumentation will still be installed and spans will be generated.

Type: Boolean

Default: True

Changed in version v0.41.0: Formerly named DATADOG_TRACE_ENABLED

DD_TRACE_OTEL_ENABLED#

When used with ddtrace-run this configuration enables OpenTelemetry support. To enable OpenTelemetry without ddtrace-run refer to the following docs.

Type: Boolean

Default: (no value)

New in version v1.12.0.

DD_INSTRUMENTATION_TELEMETRY_ENABLED#

Enables sending telemetry events to the agent.

Type: Boolean

Default: True

DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED#

This configuration enables the generation of 128 bit trace ids.

Type: Boolean

Default: (no value)

New in version v1.12.0.

DD_TRACE_DEBUG#

Enables debug logging in the tracer. Setting this flag will cause the library to create a root logging handler if one does not already exist.

Can be used with DD_TRACE_LOG_FILE to route logs to a file.

Type: Boolean

Default: (no value)

Changed in version v0.41.0: Formerly named DATADOG_TRACE_DEBUG

DD_TRACE_LOG_FILE_LEVEL#

Configures the RotatingFileHandler used by the ddtrace logger to write logs to a file based on the level specified. Defaults to DEBUG, but will accept the values found in the standard logging library, such as WARNING, ERROR, and INFO, if further customization is needed. Files are not written to unless DD_TRACE_LOG_FILE has been defined.

Type: String

Default: DEBUG

DD_TRACE_LOG_FILE#

Directs ddtrace logs to a specific file. Note: The default backup count is 1. For larger logs, use with DD_TRACE_LOG_FILE_SIZE_BYTES. To fine tune the logging level, use with DD_TRACE_LOG_FILE_LEVEL.

Type: String

Default: (no value)

DD_TRACE_LOG_FILE_SIZE_BYTES#

Max size for a file when used with DD_TRACE_LOG_FILE. When a log has exceeded this size, there will be one backup log file created. In total, the files will store 2 * DD_TRACE_LOG_FILE_SIZE_BYTES worth of logs.

Type: Int

Default: 15728640

DD_TRACE_<INTEGRATION>_ENABLED

Enables <INTEGRATION> to be patched. For example, DD_TRACE_DJANGO_ENABLED=false will disable the Django integration from being installed.

Type: Boolean

Default: True

New in version v0.41.0.

DD_PATCH_MODULES#

Override the modules patched for this execution of the program. Must be a list in the module1:boolean,module2:boolean format. For example, boto:true,redis:false.

Type: String

Default: (no value)

Changed in version v0.55.0: Formerly named DATADOG_PATCH_MODULES

DD_LOGS_INJECTION#

Enables Logs Injection.

Type: Boolean

Default: (no value)

DD_CALL_BASIC_CONFIG#

Controls whether logging.basicConfig is called in ddtrace-run or when debug mode is enabled.

Type: Boolean

Default: (no value)

DD_AGENT_HOST#

The host name to use to connect the Datadog agent for traces. The host name can be IPv4, IPv6, or a domain name. If DD_TRACE_AGENT_URL is specified, the value of DD_AGENT_HOST is ignored.

Example for IPv4: DD_AGENT_HOST=192.168.10.1

Example for IPv6: DD_AGENT_HOST=2001:db8:3333:4444:CCCC:DDDD:EEEE:FFFF

Example for domain name: DD_AGENT_HOST=host

Type: String

Default: localhost

New in version v0.17.0.

New in version v1.7.0.

DD_TRACE_AGENT_URL#

The URL to use to connect the Datadog agent for traces. The url can start with http:// to connect using HTTP or with unix:// to use a Unix Domain Socket.

Example for http url: DD_TRACE_AGENT_URL=http://localhost:8126

Example for UDS: DD_TRACE_AGENT_URL=unix:///var/run/datadog/apm.socket

Type: URL

Default: unix:///var/run/datadog/apm.socket if available otherwise http://localhost:8126

DD_DOGSTATSD_URL#

The URL to use to connect the Datadog agent for Dogstatsd metrics. The url can start with udp:// to connect using UDP or with unix:// to use a Unix Domain Socket.

Example for UDP url: DD_TRACE_AGENT_URL=udp://localhost:8125

Example for UDS: DD_TRACE_AGENT_URL=unix:///var/run/datadog/dsd.socket

Type: URL

Default: unix:///var/run/datadog/dsd.socket if available otherwise udp://localhost:8125

DD_TRACE_AGENT_TIMEOUT_SECONDS#

The timeout in float to use to connect to the Datadog agent.

Type: Float

Default: 2.0

DD_TRACE_WRITER_BUFFER_SIZE_BYTES#

The max size in bytes of traces to buffer between flushes to the agent.

Type: Int

Default: 8388608

DD_TRACE_WRITER_MAX_PAYLOAD_SIZE_BYTES#

The max size in bytes of each payload item sent to the trace agent. If the max payload size is greater than buffer size, then max size of each payload item will be the buffer size.

Type: Int

Default: 8388608

DD_TRACE_WRITER_INTERVAL_SECONDS#

The time between each flush of traces to the trace agent.

Type: Float

Default: 1.0

DD_TRACE_STARTUP_LOGS#

Enable or disable start up diagnostic logging.

Type: Boolean

Default: (no value)

DD_TRACE_SAMPLE_RATE#

A float, f, 0.0 <= f <= 1.0. f*100% of traces will be sampled.

Type: Float

Default: 1.0

DD_TRACE_RATE_LIMIT#

Maximum number of traces per second to sample. Set a rate limit to avoid the ingestion volume overages in the case of traffic spikes.

Type: int

Default: 100

New in version v0.33.0.

DD_TRACE_SAMPLING_RULES#

A JSON array of objects. Each object must have a “sample_rate”, and the “name” and “service” fields are optional. The “sample_rate” value must be between 0.0 and 1.0 (inclusive).

Example: DD_TRACE_SAMPLING_RULES='[{"sample_rate":0.5,"service":"my-service"}]'

Note that the JSON object must be included in single quotes (’) to avoid problems with escaping of the double quote (”) character.

Type: JSON array

Default: (no value)

DD_SPAN_SAMPLING_RULES#

A JSON array of objects. Each object must have a “name” and/or “service” field, while the “max_per_second” and “sample_rate” fields are optional. The “sample_rate” value must be between 0.0 and 1.0 (inclusive), and will default to 1.0 (100% sampled). The “max_per_second” value must be >= 0 and will default to no limit. The “service” and “name” fields can be glob patterns: “*” matches any substring, including the empty string, “?” matches exactly one of any character, and any other character matches exactly one of itself.

Example: DD_SPAN_SAMPLING_RULES='[{"sample_rate":0.5,"service":"my-serv*","name":"flask.re?uest"}]'

Type: string

Default: (no value)

New in version v1.4.0.

DD_SPAN_SAMPLING_RULES_FILE#

A path to a JSON file containing span sampling rules organized as JSON array of objects. For the rules each object must have a “name” and/or “service” field, and the “sample_rate” field is optional. The “sample_rate” value must be between 0.0 and 1.0 (inclusive), and will default to 1.0 (100% sampled). The “max_per_second” value must be >= 0 and will default to no limit. The “service” and “name” fields are glob patterns, where “glob” means: “*” matches any substring, including the empty string, “?” matches exactly one of any character, and any other character matches exactly one of itself.

Example: DD_SPAN_SAMPLING_RULES_FILE="data/span_sampling_rules.json"' Example File Contents: [{"sample_rate":0.5,"service":"*-service","name":"my-name-????", "max_per_second":"20"}, {"service":"xy?","name":"a*c"}]

Type: string

Default: (no value)

New in version v1.4.0.

DD_TRACE_HEADER_TAGS#

A map of case-insensitive header keys to tag names. Automatically applies matching header values as tags on root spans.

For example, User-Agent:http.useragent,content-type:http.content_type.

Type: String

Default: (no value)

DD_TRACE_API_VERSION#

The trace API version to use when sending traces to the Datadog agent.

Currently, the supported versions are: v0.3, v0.4 and v0.5.

Type: String

Default: v0.5 if priority sampling is enabled, else v0.3

New in version v0.56.0.

Changed in version v1.7.0: default changed to v0.5.

DD_TRACE_OBFUSCATION_QUERY_STRING_PATTERN#

A regexp to redact sensitive query strings. Obfuscation disabled if set to empty string

Type: String

Default: (?i)(?:p(?:ass)?w(?:or)?d|pass(?:_?phrase)?|secret|(?:api_?|private_?|public_?|access_?|secret_?)key(?:_?id)?|token|consumer_?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?)(?:(?:\s|%20)*(?:=|%3D)[^&]+|(?:"|%22)(?:\s|%20)*(?::|%3A)(?:\s|%20)*(?:"|%22)(?:%2[^2]|%[^2]|[^"%])+(?:"|%22))|bearer(?:\s|%20)+[a-z0-9\._\-]|token(?::|%3A)[a-z0-9]{13}|gh[opsu]_[0-9a-zA-Z]{36}|ey[I-L](?:[\w=-]|%3D)+\.ey[I-L](?:[\w=-]|%3D)+(?:\.(?:[\w.+\/=-]|%3D|%2F|%2B)+)?|[\-]{5}BEGIN(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY[\-]{5}[^\-]+[\-]{5}END(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY|ssh-rsa(?:\s|%20)*(?:[a-z0-9\/\.+]|%2F|%5C|%2B){100,}.

DD_TRACE_PROPAGATION_STYLE#

Comma separated list of propagation styles used for extracting trace context from inbound request headers and injecting trace context into outbound request headers.

Overridden by DD_TRACE_PROPAGATION_STYLE_EXTRACT for extraction.

Overridden by DD_TRACE_PROPAGATION_STYLE_INJECT for injection.

The supported values are datadog, b3multi, and b3 single header, and none.

When checking inbound request headers we will take the first valid trace context in the order provided. When none is the only propagator listed, propagation is disabled.

All provided styles are injected into the headers of outbound requests.

Example: DD_TRACE_PROPAGATION_STYLE_EXTRACT="datadog,b3multi" to check for both x-datadog-* and x-b3-* headers when parsing incoming request headers for a trace context.

Type: String

Default: datadog

Changed in version v1.7.0: The b3multi propagation style was added and b3 was deprecated in favor it.

DD_TRACE_PROPAGATION_STYLE_EXTRACT#

Comma separated list of propagation styles used for extracting trace context from inbound request headers.

Overrides DD_TRACE_PROPAGATION_STYLE for extraction propagation style.

The supported values are datadog, b3multi, and b3 single header, and none.

When checking inbound request headers we will take the first valid trace context in the order provided. When none is the only propagator listed, extraction is disabled.

Example: DD_TRACE_PROPAGATION_STYLE="datadog,b3" to check for both x-datadog-* and x-b3-* headers when parsing incoming request headers for a trace context. In addition, to inject both x-datadog-* and x-b3-* headers into outbound requests.

Type: String

Default: datadog

Changed in version v1.7.0: The b3multi propagation style was added and b3 was deprecated in favor it.

DD_TRACE_PROPAGATION_STYLE_INJECT#

Comma separated list of propagation styles used for injecting trace context into outbound request headers.

Overrides DD_TRACE_PROPAGATION_STYLE for injection propagation style.

The supported values are datadog, b3multi, and b3 single header, and none.

All provided styles are injected into the headers of outbound requests. When none is the only propagator listed, injection is disabled.

Example: DD_TRACE_PROPAGATION_STYLE_INJECT="datadog,b3multi" to inject both x-datadog-* and x-b3-* headers into outbound requests.

Type: String

Default: datadog

Changed in version v1.7.0: The b3multi propagation style was added and b3 was deprecated in favor it.

DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH#

The maximum length of x-datadog-tags header allowed in the Datadog propagation style. Must be a value between 0 to 512. If 0, propagation of x-datadog-tags is disabled.

Type: Integer

Default: 512

DD_TRACE_PARTIAL_FLUSH_ENABLED#

Prevents large payloads being sent to APM.

Type: Boolean

Default: True

DD_PROFILING_ENABLED#

Enable Datadog profiling when using ddtrace-run.

Type: Boolean

Default: (no value)

DD_PROFILING_API_TIMEOUT#

The timeout in seconds before dropping events if the HTTP API does not reply.

Type: Float

Default: 10

DD_PROFILING_MAX_TIME_USAGE_PCT#

The percentage of maximum time the stack profiler can use when computing statistics. Must be greater than 0 and lesser or equal to 100.

Type: Float

Default: 1

DD_PROFILING_MAX_FRAMES#

The maximum number of frames to capture in stack execution tracing.

Type: Integer

Default: 64

DD_PROFILING_ENABLE_CODE_PROVENANCE#

Whether to enable code provenance.

Type: Boolean

Default: (no value)

DD_PROFILING_MEMORY_ENABLED#

Whether to enable the memory profiler.

Type: Boolean

Default: True

DD_PROFILING_HEAP_ENABLED#

Whether to enable the heap memory profiler.

Type: Boolean

Default: True

DD_PROFILING_CAPTURE_PCT#

The percentage of events that should be captured (e.g. memory allocation). Greater values reduce the program execution speed. Must be greater than 0 lesser or equal to 100.

Type: Float

Default: 1

DD_PROFILING_UPLOAD_INTERVAL#

The interval in seconds to wait before flushing out recorded events.

Type: Float

Default: 60

DD_PROFILING_IGNORE_PROFILER#

Deprecated: whether to ignore the profiler in the generated data.

Type: Boolean

Default: (no value)

DD_PROFILING_TAGS#

The tags to apply to uploaded profile. Must be a list in the key1:value,key2:value2 format.

Type: String

Default: (no value)

DD_PROFILING_ENDPOINT_COLLECTION_ENABLED#

Whether to enable the endpoint data collection in profiles.

Type: Boolean

Default: True

DD_APPSEC_ENABLED#

Whether to enable AppSec monitoring.

Type: Boolean

Default: (no value)

DD_APPSEC_RULES#

Path to a json file containing AppSec rules.

Type: String

Default: (no value)

DD_COMPILE_DEBUG#

Compile Cython extensions in RelWithDebInfo mode (with debug info, but no debug code or asserts)

Type: Boolean

Default: (no value)

DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP#

Sensitive parameter key regexp for obfuscation.

Type: String

Default: (?i)(?:p(?:ass)?w(?:or)?d|pass(?:_?phrase)?|secret|(?:api_?|private_?|public_?)key)|token|consumer_?(?:id|key|secret)|sign(?:ed|ature)|bearer|authorization

DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP#

Sensitive parameter value regexp for obfuscation.

Type: String

Default: (?i)(?:p(?:ass)?w(?:or)?d|pass(?:_?phrase)?|secret|(?:api_?|private_?|public_?|access_?|secret_?)key(?:_?id)?|token|consumer_?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?)(?:\s*=[^;]|"\s*:\s*"[^"]+")|bearer\s+[a-z0-9\._\-]+|token:[a-z0-9]{13}|gh[opsu]_[0-9a-zA-Z]{36}|ey[I-L][\w=-]+\.ey[I-L][\w=-]+(?:\.[\w.+\/=-]+)?|[\-]{5}BEGIN[a-z\s]+PRIVATE\sKEY[\-]{5}[^\-]+[\-]{5}END[a-z\s]+PRIVATE\sKEY|ssh-rsa\s*[a-z0-9\/\.+]{100,}

DD_HTTP_CLIENT_TAG_QUERY_STRING#

Send query strings in http.url tag in http client integrations.

Type: Boolean

Default: True

DD_HTTP_SERVER_TAG_QUERY_STRING#

Send query strings in http.url tag in http server integrations.

Type: Boolean

Default: True

DD_IAST_ENABLED#

Whether to enable IAST.

Type: Boolean

Default: (no value)

DD_IAST_MAX_CONCURRENT_REQUESTS#

Number of requests analyzed at the same time.

Type: Integer

Default: 2

DD_IAST_VULNERABILITIES_PER_REQUEST#

Number of vulnerabilities reported in each request.

Type: Integer

Default: 2

DD_IAST_WEAK_HASH_ALGORITHMS#

Weak hashing algorithms that should be reported, comma separated.

Type: String

Default: MD5,SHA1

DD_IAST_WEAK_CIPHER_ALGORITHMS#

Weak cipher algorithms that should be reported, comma separated.

Type: String

Default: DES,Blowfish,RC2,RC4,IDEA

DD_UNLOAD_MODULES_FROM_SITECUSTOMIZE#

Controls whether module cloning logic is executed by ddtrace-run. Module cloning involves saving copies of dependency modules for internal use by ddtrace that will be unaffected by future imports of and changes to those modules by application code. Valid values for this variable are 1, 0, and auto. 1 tells ddtrace to run its module cloning logic unconditionally, 0 tells it not to run that logic, and auto tells it to run module cloning logic only if gevent is accessible from the application’s runtime.

Type: String

Default: auto

New in version v1.9.0.

DD_CIVISIBILITY_AGENTLESS_ENABLED#

Configures the CIVisibility service to use a test-reporting CIVisibilityWriter. This writer sends payloads for traces on which it’s used to the intake endpoint for Datadog CI Visibility. If there is a reachable Datadog agent that supports proxying these requests, the writer will send its payloads to that agent instead.

Type: Boolean

Default: (no value)

New in version v1.12.0.

DD_CIVISIBILITY_AGENTLESS_URL#

Configures the CIVisibility service to send event payloads to the specified host. If unspecified, the host “https://citestcycle-intake.<DD_SITE>” is used, where <DD_SITE> is replaced by that environment variable’s value, or “datadoghq.com” if unspecified.

Type: String

Default: (no value)

New in version v1.13.0.

Dynamic Instrumentation#

DD_DYNAMIC_INSTRUMENTATION_DIAGNOSTICS_INTERVAL#

Interval in seconds for periodically emitting probe diagnostic messages.

Type: Integer

Default: 3600

DD_DYNAMIC_INSTRUMENTATION_ENABLED#

Enable Dynamic Instrumentation.

Type: Boolean

Default: False

DD_DYNAMIC_INSTRUMENTATION_MAX_PAYLOAD_SIZE#

Maximum size in bytes of a single configuration payload that can be handled per request.

Type: Integer

Default: 1048576

DD_DYNAMIC_INSTRUMENTATION_METRICS_ENABLED#

Enable Dynamic Instrumentation diagnostic metrics.

Type: Boolean

Default: True

DD_DYNAMIC_INSTRUMENTATION_UPLOAD_FLUSH_INTERVAL#

Interval in seconds for flushing the dynamic logs upload queue.

Type: Float

Default: 1.0

DD_DYNAMIC_INSTRUMENTATION_UPLOAD_TIMEOUT#

Timeout in seconds for uploading Dynamic Instrumentation payloads.

Type: Integer

Default: 30