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:

Common Configurations

For common configuration variables (not language specific), see Configure the Datadog Tracing Library.

Unified Service Tagging

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, Tornado, Celery, Django and Falcon. Added in v0.36.0. See Unified Service Tagging for more information.

Type: String

Default: (autodetected)

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.

Traces

DD_<INTEGRATION>_DISTRIBUTED_TRACING

Enables distributed tracing for the specified <INTEGRATION>.

Type: String

Default: True

New in version v2.7.0.

DD_<INTEGRATION>_SERVICE

Set the service name, allowing default service name overrides for traces for the specific <INTEGRATION>.

Type: String

Default: <INTEGRATION>

New in version v2.11.0.

DD_ASGI_TRACE_WEBSOCKET

Enables tracing ASGI websockets. Please note that the websocket span duration will last until the connection is closed, which can result in long running spans.

Type: String

Default: (no value)

New in version v2.7.0.

DD_BOTOCORE_EMPTY_POLL_ENABLED

Enables creation of consumer span when AWS SQS and AWS Kinesis poll() operations return no records. When disabled, no consumer span is created if no records are returned.

Type: Boolean

Default: True

New in version v2.6.0.

DD_BOTOCORE_PROPAGATION_ENABLED

Enables trace context propagation connecting producer and consumer spans within a single trace for AWS SQS, SNS, and Kinesis messaging services.

Type: Boolean

Default: (no value)

New in version v2.6.0.

DD_TRACE_RAY_ARGS_KWARGS

Enables tracing of function arguments and keyword arguments in Ray remote functions and actor method.

Type: Boolean

Default: (no value)

New in version v3.16.0.

DD_TRACE_RAY_CORE_API

Enables tracing of Ray core API operations such as ray.get(), ray.wait(), and ray.put().

Type: Boolean

Default: (no value)

New in version v3.16.0.

DD_HTTP_SERVER_TAG_QUERY_STRING

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

Type: Boolean

Default: True

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_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_TRACE_128_BIT_TRACEID_GENERATION_ENABLED

This configuration enables the generation of 128 bit trace ids.

Type: Boolean

Default: True

New in version v1.12.0.

DD_TRACE_API_VERSION

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

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

Type: String

Default: v0.5

New in version v0.56.0.

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

Changed in version v1.19.1: default reverted to v0.4.

Changed in version v2.4.0: default changed to v0.5.

DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH

Sets the depth of expanding the JSON AWS payload after which we stop creating tags.

Type: Integer

Default: 10

New in version v2.17.0.

DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_TAGS

Sets the the maximum number of tags that will be added when expanding an AWS payload.

Type: Integer

Default: 758

New in version v2.17.0.

DD_TRACE_CLOUD_PAYLOAD_TAGGING_SERVICES

Sets the enabled AWS services to be expanded when AWS payload tagging is enabled.

Type: Set

Default: {‘s3’: None, ‘sns’: None, ‘sqs’: None, ‘kinesis’: None, ‘eventbridge’: None}

New in version v2.17.0.

DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING

Enables AWS request payload tagging when set to "all" or a valid comma-separated list of JSONPaths.

Type: String

Default: None

New in version v2.17.0.

DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING

Enables AWS response payload tagging when set to "all" or a valid comma-separated list of JSONPaths.

Type: String

Default: None

New in version v2.17.0.

DD_TRACE_HEADER_TAGS

A map of case-insensitive http headers to tag names. Automatically applies matching header values as tags on request and response spans. For example if DD_TRACE_HEADER_TAGS=User-Agent:http.useragent,content-type:http.content_type. The value of the header will be stored in tags with the name http.useragent and http.content_type.

If a tag name is not supplied the header name will be used. For example if DD_TRACE_HEADER_TAGS=User-Agent,content-type. The value of http header will be stored in tags with the names http.<response/request>.headers.user-agent and http.<response/request>.headers.content-type.

Type: String

Default: (no value)

DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING

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

Type: Boolean

Default: True

DD_TRACE_HTTP_SERVER_ERROR_STATUSES

Comma-separated list of HTTP status codes that should be considered errors when returned by an HTTP request. Multiple comma separated error ranges can be set (ex: 200,400-404,500-599). The status codes are used to set the error field on the span.

Type: String

Default: 500-599

DD_TRACE_METHODS

Specify methods to trace. For example: mod.submod:method1,method2;mod.submod:Class.method1. Note that this setting is only compatible with ddtrace-run, and that it doesn’t work for methods implemented by libraries for which there’s an integration in ddtrace/contrib.

Type: String

Default: (no value)

New in version v2.1.0.

DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP

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

Type: String

Default: '(?ix)(?:(?:"|%22)?)(?:(?:old[-_]?|new[-_]?)?p(?:ass)?w(?:or)?d(?:1|2)?|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(?:-{5})?(?:\\n|%0A)?|(?:ssh-(?:rsa|dss)|ecdsa-[a-z0-9]+-[a-z0-9]+)(?:\\s|%20|%09)+(?:[a-z0-9/.+]|%2F|%5C|%2B){100,}(?:=|%3D)*(?:(?:\\s|%20|%09)+[a-z0-9._-]+)?)'

Changed in version v1.19.0: DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP replaces DD_TRACE_OBFUSCATION_QUERY_STRING_PATTERN which is deprecated and will be deleted in 2.0.0

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_TRACE_PARTIAL_FLUSH_ENABLED

Prevents large payloads being sent to APM.

Type: Boolean

Default: True

DD_TRACE_PARTIAL_FLUSH_MIN_SPANS

Maximum number of spans sent per trace per payload when DD_TRACE_PARTIAL_FLUSH_ENABLED=True.

Type: Integer

Default: 300

DD_TRACE_PROPAGATION_EXTRACT_FIRST

Whether the propagator stops after extracting the first header.

Type: Boolean

Default: (no value)

New in version v2.3.0.

DD_TRACE_PROPAGATION_HTTP_BAGGAGE_ENABLED

Enables propagation of baggage items through http headers with prefix ot-baggage-.

Type: Boolean

Default: (no value)

New in version v2.4.0.

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, tracecontext, baggage, 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="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,tracecontext,baggage

Changed in version v1.7.0: Added support for tracecontext W3C headers. Changed the default value to DD_TRACE_PROPAGATION_STYLE="tracecontext,datadog".

Changed in version v2.6.0: Updated default value to datadog,tracecontext.

Changed in version v2.16.0: Updated default value to datadog,tracecontex,baggage.

DD_TRACE_SPAN_TRACEBACK_MAX_SIZE

The maximum length of a traceback included in a span.

Type: Integer

Default: 30

New in version v2.3.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_INTERVAL_SECONDS

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

Type: Float

Default: 1.0

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_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_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_TRACE_SAFE_INSTRUMENTATION_ENABLED

Whether to enable safe instrumentation.

When enabled, ddtrace will check if the version of an installed package is compatible with the respective ddtrace integration patching the package. If the version is not compatible, ddtrace will not patch the respective package.

This is useful to avoid application crashes from patching packages that are incompatible with the ddtrace supported integration version ranges.

Type: Boolean

Default: (no value)

New in version v3.11.0.

Trace Context propagation

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, b3, tracecontext, 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_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,tracecontext

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

DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

String for how to handle incoming request headers that are extracted for propagation of trace info.

The supported values are continue, restart, and ignore.

After extracting the headers for propagation, this configuration determines what is done with them.

The default value is continue which always propagates valid headers. ignore ignores all incoming headers and restart turns the first extracted valid propagation header into a span link and propagates baggage if present.

Example: DD_TRACE_PROPAGATION_STYLE_EXTRACT="ignore" to ignore all incoming headers and to start a root span without a parent.

Type: String

Default: continue

New in version v2.20.0.

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,``b3``, tracecontext, 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: tracecontext,datadog

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

Metrics

DD_RUNTIME_METRICS_ENABLED

When used with ddtrace-run this configuration enables sending runtime metrics to Datadog. These metrics track the memory management and concurrency of the python runtime. Refer to the following docs <https://docs.datadoghq.com/tracing/metrics/runtime_metrics/python/> _ for more information.

Type: Boolean

Default: (no value)

DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED

Adds support for tagging runtime metrics with the current runtime ID. This is useful for tracking runtime metrics across multiple processes. Refer to the following docs <https://docs.datadoghq.com/tracing/metrics/runtime_metrics/python/> _ for more information.

Type: Boolean

Default: (no value)

Changed in version v3.10.0: Renamed from DD_TRACE_EXPERIMENTAL_RUNTIME_ID_ENABLED

Changed in version v3.2.0: Adds initial support

DD_METRICS_OTEL_ENABLED

When used with ddtrace-run this configuration enables support for exporting OTLP metrics generated by the OpenTelemetry Metrics API. The application must also include its own OTLP metrics exporter.

Type: Boolean

Default: (no value)

New in version v3.11.0.

Application & API Security

DD_APPSEC_AUTOMATED_USER_EVENTS_TRACKING

Sets the mode for the automated user login events tracking feature which sets some traces on each user login event. The supported modes are safe which will only store the user id or primary key, extended which will also store the username, email and full name and disabled. Note that this feature requires DD_APPSEC_ENABLED to be set to true to work.

Type: String

Default: safe

Changed in version v1.17.0: Added support to the Django integration. No other integrations support this configuration.

DD_APPSEC_ENABLED

Whether to enable AppSec monitoring.

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_APPSEC_RULES

Path to a json file containing AppSec rules.

Type: String

Default: (no value)

DD_APPSEC_SCA_ENABLED

Whether to enable/disable SCA (Software Composition Analysis).

Type: Boolean

Default: None

DD_APPSEC_MAX_STACK_TRACES

Maximum number of stack traces reported for each trace.

Type: Integer

Default: 2

DD_APPSEC_MAX_STACK_TRACE_DEPTH

Maximum number of frames in a stack trace report. 0 means no limit.

Type: Integer

Default: 32

DD_APPSEC_MAX_STACK_TRACE_DEPTH_TOP_PERCENT

Percentage of reported stack trace frames to be taken from the top of the stack in case of a stack trace truncation. For example, if DD_APPSEC_MAX_STACK_TRACE_DEPTH is set to 25 and DD_APPSEC_MAX_STACK_TRACE_DEPTH_TOP_PERCENT is set to 60, if a stack trace has more than 25 frames, the top 15 (25*0.6=15)frames and the bottom 10 frames will be reported.

Type: Integer

Default: 75

DD_APPSEC_STACK_TRACE_ENABLED

Whether to enable stack traces in reports for ASM. Currently used for exploit prevention reports.

Type: Boolean

Default: True

DD_APPSEC_WAF_TIMEOUT

Each time the WAF is run to analyze a possible threat, this timeout duration is used to limit the WAF analysis. You can increase this value if you’re expecting large request payloads to be analyzed. Please note that the WAF can be queried multiple times in a single trace.

Type: Float

Default: 5.0 (unit:milliseconds)

DD_API_SECURITY_MAX_DOWNSTREAM_REQUEST_BODY_ANALYSIS

Maximum number of downstream requests per request whose (request and response) bodies will be analyzed by the WAF

Type: Integer

Default: 1

DD_API_SECURITY_DOWNSTREAM_BODY_ANALYSIS_SAMPLE_RATE

sampling rate for body analysis of downstream requests. Default value is 50%.

Type: Float

Default: 0.5 (between 0. and 1.)

Code Security

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_DEDUPLICATION_ENABLED

Avoid sending vulnerabilities in the span if they have already been reported in the last hour.

Type: Integer

Default: True

DD_IAST_REDACTION_ENABLED

Replace potentially sensitive information in the vulnerability report, like passwords with * for non tainted strings and abcde... for tainted ones. This will use the regular expressions of the two next settings to decide what to scrub.

Type: Boolean

Default: True

New in version v1.17.0.

DD_IAST_REDACTION_NAME_PATTERN

Regular expression containing key or name style strings matched against vulnerability origin and evidence texts. If it matches, the scrubbing of the report will be enabled.

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)?)

New in version v1.17.0.

DD_IAST_REDACTION_VALUE_PATTERN

Regular expression containing value style strings matched against vulnerability origin and evidence texts. If it matches, the scrubbing of the report will be enabled.

Type: String

Default: (?i)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,}

New in version v1.17.0.

DD_IAST_STACK_TRACE_ENABLED

Whether to enable stack traces in reports for Code Security/IAST.

Type: Boolean

Default: True

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_IAST_SECURITY_CONTROLS_CONFIGURATION

Allows you to specify custom sanitizers and validators that IAST should recognize when analyzing your application for security vulnerabilities. See the Security Controls documentation for more information about this feature.

Type: String

Default: (no value)

Test Visibility

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.

DD_CIVISIBILITY_ITR_ENABLED

Configures the CIVisibility service to query the Datadog API to decide whether to enable the Datadog Test Impact Analysis (formerly Intelligent Test Runner). Setting the variable to false will skip querying the API and disable code coverage collection and test skipping.

Type: Boolean

Default: True

New in version v1.13.0.

DD_CIVISIBILITY_LOG_LEVEL

Configures the CIVisibility service to replace the default Datadog logger’s stream handler with one that only displays messages related to the CIVisibility service, at a level of or higher than the given log level. The Datadog logger’s file handler is unaffected. Valid, case-insensitive, values are critical, error, warning, info, or debug. A value of none silently disables the logger. Note: enabling debug logging with the DD_TRACE_DEBUG environment variable overrides this behavior.

Type: String

Default: info

New in version v2.5.0.

DD_TEST_SESSION_NAME

Configures the CIVisibility service to use the given string as the value of the test_session.name tag in test events. If not specified, this string will be constructed from the CI job id (if available) and the test command used to start the test session.

Type: String

Default: (autodetected)

New in version v2.16.0.

DD_CIVISIBILITY_RUM_FLUSH_WAIT_MILLIS

Configures how long, in milliseconds, the Selenium integration will wait after invoking the RUM flush function during calls to the driver’s quit() or close() methods. This helps ensure that the call to the asynchronous function finishes before the driver is closed.

Type: Integer

Default: 500

New in version v2.18.0.

DD_CIVISIBILITY_USE_BETA_WRITER

Configures the CIVisibility service to use an alternative method for collecting and sending test spans. In this mode, the CIVisibility tracer is kept separate from the global ddtrace tracer, which helps avoid interference between test and non-test tracer configurations. This mode is currently experimental.

Type: Boolean

Default: (no value)

New in version v3.12.0.

DD_PYTEST_USE_NEW_PLUGIN

Configures the CIVisibility service to use a new version of the pytest plugin. This new version uses an independent span writer for Test Optimization (similar to the DD_CIVISIBILITY_USE_BETA_WRITER option), and also contains performance and memory usage improvements.

Type: Boolean

Default: True

New in version v4.3.0.

DD_CIVISIBILITY_ENABLED

Allows the CIVisibility service to run and send traces to the Test Visibility product.

Type: Boolean

Default: True

New in version v3.15.0.

Agent

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_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_DOGSTATSD_URL=udp://localhost:8125

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

Type: URL

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

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_SITE

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

Type: String

Default: datadoghq.com

DD_TAGS

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

If a tag value is not supplied the value will be an empty string.

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_TRACE_AGENT_TIMEOUT_SECONDS

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

Type: Float

Default: 2.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

Logs

DD_LOGS_INJECTION

Enables Logs Injection. Supported values are false, and true.

Type: Boolean

Default: True

Changed in version v0.51.0: Added support for correlating traces to log using the builtin logger. This feature was disabled by default.

Changed in version v3.10.0: The default value was changed to true. This means that the tracer will inject trace context into logs when ddtrace-run or import ddtrace.auto is used. To disable this behavior, set DD_LOGS_INJECTION=false.

DD_LOGS_OTEL_ENABLED

When used with ddtrace-run this configuration enables support for exporting OTLP logs generated by the OpenTelemetry Logging API. The application must also include its own OTLP logs exporter.

Type: Boolean

Default: (no value)

Changed in version v3.12.0: Adds support for submitting logs via an OTLP Exporter.

DD_TRACE_DEBUG

Enables debug logging in the tracer.

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

Takes precedence over DD_TRACE_LOG_LEVEL.

Type: Boolean

Default: (no value)

Changed in version v0.41.0: Formerly named DATADOG_TRACE_DEBUG

DD_TRACE_LOG_LEVEL

Sets the log level for the ddtrace logger, overriding inheritance from the root logger. Valid values are NOTSET, DEBUG, INFO, WARNING, ERROR, and CRITICAL (case-insensitive). Setting NOTSET will cause the ddtrace logger to inherit from the root logger. DD_TRACE_DEBUG=true takes precedence over DD_TRACE_LOG_LEVEL.

Type: String

Default: None

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_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_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_STARTUP_LOGS

Enable or disable start up diagnostic logging.

Type: Boolean

Default: (no value)

Sampling

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_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. This configuration is only applied when client based sampling is configured, otherwise agent based rate limits are used.

Type: int

Default: 100

New in version v0.33.0.

Changed in version v2.15.0: Only applied when DD_TRACE_SAMPLE_RATE, DD_TRACE_SAMPLING_RULES, or DD_SPAN_SAMPLING_RULE are set.

Changed in version v3.0.0: Only applied when DD_TRACE_SAMPLING_RULES or DD_SPAN_SAMPLING_RULE are set.

DD_TRACE_SAMPLING_RULES

A JSON array of objects. Each object must have a “sample_rate”, and the “name”, “service”, “resource”, and “tags” 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","resource":"my-url","tags":{"my-tag":"example"}}]'

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)

Changed in version v1.19.0: added support for “resource”

Changed in version v1.20.0: added support for “tags”

Changed in version v2.8.0: added lazy sampling support, so that spans are evaluated at the end of the trace, guaranteeing more metadata to evaluate against.

Other

DD_INSTRUMENTATION_TELEMETRY_ENABLED

Enables sending telemetry events to the agent.

Type: Boolean

Default: True

DD_TRACE_EXPERIMENTAL_FEATURES_ENABLED

Enables support for experimental ddtrace configurations. The supported configurations are: DD_RUNTIME_METRICS_ENABLED.

Type: string

Default: (no value)

Changed in version v3.2.0: Adds initial support and support for enabling experimental runtime metrics.

DD_SUBPROCESS_SENSITIVE_WILDCARDS

Add more possible matches to the internal list of subprocess execution argument scrubbing. Must be a comma-separated list and each item can take fnmatch style wildcards, for example: *ssn*,*personalid*,*idcard*,*creditcard*.

Type: String

Default: (no value)

DD_USER_MODEL_EMAIL_FIELD

Field to be used to read the user email when using a custom User model for the automatic login events. This field will take precedence over automatic inference.

Type: String

Default: (no value)

New in version v1.15.0.

DD_USER_MODEL_LOGIN_FIELD

Field to be used to read the user login when using a custom User model for the automatic login events. This field will take precedence over automatic inference. Please note that, if set, this field will be used to retrieve the user login even if DD_APPSEC_AUTOMATED_USER_EVENTS_TRACKING is set to safe and, in some cases, the selected field could hold potentially private information.

Type: String

Default: (no value)

New in version v1.15.0.

DD_USER_MODEL_NAME_FIELD

Field to be used to read the user name when using a custom User model for the automatic login events. This field will take precedence over automatic inference.

Type: String

Default: (no value)

New in version v1.15.0.

DD_TRACE_BAGGAGE_TAG_KEYS

A comma-separated list of baggage keys, sent via HTTP headers, to automatically tag as baggage.<key> on the local root span. Only baggage extracted from incoming headers is supported. Baggage set via Context.set_baggage_item(..., ...) is not included. Keys must have non-empty values. Set to * to tag all baggage keys (use with caution to avoid exposing sensitive data). Set to an empty string to disable the feature.

Type: String

Default: user.id,account.id,session.id

New in version v3.6.0.

Profiling

DD_PROFILING_AGENTLESS

Type: Boolean

Default: False

DD_PROFILING_API_TIMEOUT_MS

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

Type: Integer

Default: 10000

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.0

DD_PROFILING_ENABLE_ASSERTS

Whether to enable debug assertions in the profiler code.

Type: Boolean

Default: False

DD_PROFILING_ENABLE_CODE_PROVENANCE

Whether to enable code provenance.

Type: Boolean

Default: True

DD_PROFILING_ENABLED

Enable Datadog profiling when using ddtrace-run.

Type: Boolean

Default: False

DD_PROFILING_ENDPOINT_COLLECTION_ENABLED

Whether to enable the endpoint data collection in profiles.

Type: Boolean

Default: True

DD_PROFILING_IGNORE_PROFILER

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

Type: Boolean

Default: False

DD_PROFILING_MAX_FRAMES

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

Type: Integer

Default: 64

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.0

DD_PROFILING_OUTPUT_PPROF

Type: String

Default: None

DD_PROFILING_SAMPLE_POOL_CAPACITY

The number of Sample objects to keep in the pool for reuse. Increasing this can reduce the overhead from frequently allocating and deallocating Sample objects.

Type: Integer

Default: 4

DD_PROFILING_TAGS

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

Type: Mapping

Default: {}

DD_PROFILING_TIMELINE_ENABLED

Whether to add timestamp information to captured samples. Adds a small amount of overhead to the profiler, but enables the use of the Timeline view in the UI.

Type: Boolean

Default: True

DD_PROFILING_UPLOAD_INTERVAL

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

Type: Float

Default: 60.0

DD_PROFILING_STACK_ENABLED

Whether to enable the stack profiler.

Type: Boolean

Default: True

DD_PROFILING_STACK_UVLOOP

Whether to enable uvloop support for async profiling.

Type: Boolean

Default: True

DD_PROFILING_PYTORCH_ENABLED

Whether to enable the PyTorch profiler.

Type: Boolean

Default: False

DD_PROFILING_PYTORCH_EVENTS_LIMIT

How many events the PyTorch profiler records each collection.

Type: Integer

Default: 1000000

DD_PROFILING_MEMORY_ENABLED

Whether to enable the memory profiler.

Type: Boolean

Default: True

DD_PROFILING_MEMORY_EVENTS_BUFFER

Type: Integer

Default: 16

DD_PROFILING_LOCK_ENABLED

Whether to enable the lock profiler.

Type: Boolean

Default: True

DD_PROFILING_LOCK_NAME_INSPECT_DIR

Whether to inspect the dir() of local and global variables to find the name of the lock. With this enabled, the profiler finds the name of locks that are attributes of an object.

Type: Boolean

Default: True

DD_PROFILING_HEAP_ENABLED

Whether to enable the heap memory profiler.

Type: Boolean

Default: True

DD_PROFILING_HEAP_SAMPLE_SIZE

Average number of bytes allocated between memory profiler samples.

Type: Integer

Default: None

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_PROBE_FILE

Path to a file containing probe definitions.

Type: Path

Default: None

DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS

List of identifiers/object attributes/dict keys to redact from dynamic logs and snapshots.

Type: List

Default: set()

DD_DYNAMIC_INSTRUMENTATION_REDACTED_TYPES

List of object types to redact from dynamic logs and snapshots.

Type: List

Default: set()

DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS

List of identifiers to exclude from redaction.

Type: List

Default: set()

DD_DYNAMIC_INSTRUMENTATION_UPLOAD_INTERVAL_SECONDS

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

Exception Replay

DD_EXCEPTION_REPLAY_CAPTURE_MAX_FRAMES

The maximum number of frames to capture for each exception.

Type: int

Default: 8

DD_EXCEPTION_REPLAY_ENABLED

Enable automatic capturing of exception debugging information.

Type: Boolean

Default: False

Code Origin

DD_CODE_ORIGIN_FOR_SPANS_ENABLED

Enable code origin for spans.

Type: Boolean

Default: False

Live Debugging

DD_LIVE_DEBUGGING_ENABLED

Enable the live debugger.

Type: Boolean

Default: False

Error Tracking

DD_ERROR_TRACKING_HANDLED_ERRORS

Report automatically handled errors to Error Tracking. Handled errors are also attached to spans through span events.

Possible values are: user|third_party|all. Report handled exceptions of user code, third party packages or both.

Type: String

Default: (no value)

DD_ERROR_TRACKING_HANDLED_ERRORS_INCLUDE

Comma-separated list of Python modules for which we report handled errors.

Type: String

Default: (no value)