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_BEDROCK_RESOLVE_INFERENCE_PROFILE#

Enables resolving the underlying foundation model of an AWS Bedrock application inference profile. When a Bedrock request uses an application-inference-profile ARN as its modelId, the model name is otherwise an opaque identifier and LLM Observability cannot compute cost. When enabled, the integration makes an extra bedrock:GetInferenceProfile call (once per profile, cached) to report the underlying model. The caller’s credentials must be allowed to call bedrock:GetInferenceProfile.

Type: Boolean

Default: (no value)

New in version v4.13.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_CTX_ENABLED#

Enables publication of OpenTelemetry thread context records for external readers such as the OpenTelemetry eBPF Profiler. These records describe the active traces running within the sampled process.

Type: Boolean

Default: (no value)

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_AS_SPAN_LINKS#

Comma-separated list of integration names for which upstream context is attached to the child span as span links instead of being used to parent the span.

Example: DD_TRACE_PROPAGATION_AS_SPAN_LINKS="google_cloud_pubsub,kafka".

Type: String

Default: (empty)

New in version v4.15.0.

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.

DD_LLMOBS_PAYLOAD_SIZE_BYTES#

The max size in bytes of an LLMObs payload submitted to Datadog. When the buffer reaches this limit it is flushed immediately before the next event is enqueued. Defaults to 5 MiB.

This controls the size of LLMObs payloads sent directly to Datadog when agentless mode is enabled (DD_LLMOBS_AGENTLESS_ENABLED=true). In agent mode, this value should not exceed the EVP proxy max payload size configured in the Datadog Agent.

Type: Int

Default: 5242880

DD_LLMOBS_EVENT_SIZE_BYTES#

The max size in bytes of a single LLMObs event submitted to Datadog. Events that exceed this limit have their input/output fields truncated before submission. Defaults to 5 MB.

This controls the size of individual LLMObs events sent directly to Datadog when agentless mode is enabled (DD_LLMOBS_AGENTLESS_ENABLED=true). In agent mode, this value should not exceed the EVP proxy max event size configured in the Datadog Agent.

Type: Int

Default: 5000000

DD_LLMOBS_SAMPLE_RATE#

The proportion of LLM Observability spans (between 0.0 and 1.0) that Datadog retains after intake. 100% of LLM Observability spans are always submitted; this rate controls how many are retained in full. For example, 0.1 keeps roughly 10% of your LLM Observability spans with their complete input/output data.

This only affects LLM Observability span retention. It does not affect APM span retention, and it does not affect metrics: token usage, cost, and other LLM Observability metrics are always computed from 100% of traffic regardless of the configured rate.

Type: Float

Default: 1.0

New in version v4.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_AGENTIC_ONBOARDING#

A legitimate Datadog variable set automatically by Datadog’s agentic onboarding solution when it configures App & API Protection. Its value is reported verbatim via instrumentation telemetry, so that Datadog can record that the service was onboarded through the agentic flow.

Type: String

Default: (no value)

New in version v4.13.0.

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

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

AI Guard#

DD_AI_GUARD_ANALYZE_STREAM_RESPONSES_ENABLED#

When set to True and AI Guard is enabled, streamed responses from Anthropic and OpenAI (Chat Completions, including the with_raw_response helper, and Responses) are fully buffered before any chunk is returned to the caller. The complete response is evaluated; if the evaluation results in a block (DENY or ABORT), no chunks are delivered and AIGuardAbortError is raised. When set to False (default), only request inputs are evaluated and streamed chunks are forwarded live.

Trade-offs: enabling this flag increases time-to-first-token (all chunks must be received before the first one is delivered) and increases peak memory usage proportional to the response size.

Type: Boolean

Default: (no value)

DD_AI_GUARD_BLOCK#

Controls whether AI Guard blocking is enabled. When set to True (default), the blocking behavior configured in the Datadog AI Guard UI (in-app) will be honored. Set to False to force monitor-only mode locally: evaluations are still performed but AIGuardAbortError is never raised, regardless of the in-app blocking setting.

Type: Boolean

Default: True

DD_AI_GUARD_REDACTION_ENABLED#

Global switch for AI Guard sensitive data redaction. When set to True (default) and the AI Guard service asks for redaction, the tracer replaces the affected message content with the redacted values returned by the AI Guard, and reports the redacted messages instead of the originals. Set to False to disable the transformation without a tracer rollback: evaluations still run and sensitive data findings are still reported, but no message is modified.

Type: Boolean

Default: True

DD_AI_GUARD_OPENAI_ENABLED#

Per-provider kill switch for AI Guard auto-instrumentation of the OpenAI SDK. When set to True (default) and AI Guard is enabled, OpenAI calls are evaluated. Set to False to disable AI Guard instrumentation for OpenAI only, without affecting other providers or requiring a tracer version rollback.

Type: Boolean

Default: True

DD_AI_GUARD_ANTHROPIC_ENABLED#

Per-provider kill switch for AI Guard auto-instrumentation of the Anthropic SDK. Behaves like DD_AI_GUARD_OPENAI_ENABLED but scoped to Anthropic: set to False to disable AI Guard instrumentation for Anthropic only, without affecting other providers or requiring a rollback.

Type: Boolean

Default: True

DD_AI_GUARD_LANGCHAIN_ENABLED#

Per-framework kill switch for AI Guard auto-instrumentation of LangChain. Set to False to disable AI Guard instrumentation for LangChain only, without affecting other integrations or requiring a tracer version rollback.

Note: this disables only the LangChain framework-level integration; other integrations remain active. If your LangChain models run on an instrumented provider SDK, its integration will still evaluate those calls — so you must disable that provider’s switch too. For example, with ChatOpenAI also set DD_AI_GUARD_OPENAI_ENABLED=false, and with ChatAnthropic also set DD_AI_GUARD_ANTHROPIC_ENABLED=false. To stop AI Guard for a LangChain app regardless of provider, set DD_AI_GUARD_ENABLED=false.

Type: Boolean

Default: True

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

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_CODE_COVERAGE_FLAGS#

Adds flags to uploaded code coverage reports for grouping and filtering. Separate flags with commas, for example DD_CODE_COVERAGE_FLAGS="type:unit-tests,jvm-21". Surrounding whitespace and empty entries are ignored; order and duplicate flags are preserved. Up to 32 flags are supported. If more are provided, the flags are omitted without canceling the report upload.

Type: String (comma-separated list)

Default: (no value)

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_DYNAMIC_ATR_ENABLED#

Enables dynamic, duration-based Auto Test Retries budgets. When enabled, the number of retries allowed for a test is determined by the duration of its initial attempt, using the same duration buckets as Early Flake Detection, instead of the flat per-test retry limit. Requires Auto Test Retries to be enabled by the backend.

Type: Boolean

Default: (no value)

New in version v4.15.0.

DD_CIVISIBILITY_DYNAMIC_ATR_BUCKETS#

Comma-separated list of five positive integers in [1, 20] overriding the five duration-based Auto Test Retries budgets (for the 5s, 10s, 30s, 5m, and >5m buckets respectively). When unset or empty, the Early Flake Detection retry settings from the backend are used. Only takes effect when DD_CIVISIBILITY_DYNAMIC_ATR_ENABLED is enabled.

Type: String

Default: (no value)

New in version v4.15.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.

Setting this option to false selects the legacy pytest plugin (ddtrace/contrib/internal/pytest), which is deprecated and will be removed in ddtrace 5.0.0. Remove this environment variable, or set it to true, to use the supported default plugin.

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.

DD_AGENTLESS_LOG_SUBMISSION_ENABLED#

When used with DD_CIVISIBILITY_AGENTLESS_ENABLED=true, enables log submission from the ddtrace.testing pytest plugin directly to the Datadog logs intake. Log records emitted during tests are enriched with the active test span’s dd.trace_id and dd.span_id and forwarded as structured JSON. When using the Datadog Agent instead of agentless mode, set DD_LOGS_INJECTION=true to achieve the same result via the agent’s intake.

Type: Boolean

Default: (no value)

New in version v4.8.0.

DD_TEST_OPTIMIZATION_MANIFEST_FILE#

Enables manifest mode for Bazel offline execution. When set to the path of a manifest file (or a Bazel rlocation), the CIVisibility service reads settings, known tests, and test management data from pre-fetched cache files inside .testoptimization/ instead of making HTTP requests to the Datadog backend. Test skipping is disabled unconditionally in this mode.

Type: String

Default: (no value)

New in version v4.9.0.

DD_TEST_OPTIMIZATION_PAYLOADS_IN_FILES#

Enables payload-files mode for Bazel offline execution. When set to true, test event, coverage, and telemetry payloads are written as JSON files to TEST_UNDECLARED_OUTPUTS_DIR/payloads/{tests,coverage,telemetry}/ instead of being sent over HTTP. CI and Git tags can be provided via DD_TEST_OPTIMIZATION_ENV_DATA_FILE to avoid invoking the git CLI.

Type: Boolean

Default: (no value)

New in version v4.9.0.

DD_TEST_OPTIMIZATION_ENV_DATA_FILE#

Path to a JSON file containing CI and Git environment tags. Used in payload-files mode (DD_TEST_OPTIMIZATION_PAYLOADS_IN_FILES=true) to supply CI/Git metadata without invoking the git CLI. When no other CI provider is detected and this variable is unset, the provider name falls back to bazel.

Type: String

Default: (no value)

New in version v4.9.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_AGENTLESS_ENABLED#

Submit data directly to the Datadog intake instead of through a Datadog Agent. This covers instrumentation telemetry, traces, Remote Configuration, Dynamic Instrumentation, OpenTelemetry metrics and logs, crash reports, Test Optimization and LLM Observability.

DD_API_KEY must be set; enabling agentless submission without one raises an error at startup. DD_SITE selects the intake to submit to.

The per-product settings DD_CIVISIBILITY_AGENTLESS_ENABLED and DD_LLMOBS_AGENTLESS_ENABLED default to this value and can each be set explicitly to override it for that product. An explicit OTEL_EXPORTER_OTLP_ENDPOINT, or its signal- specific variants, likewise keeps OpenTelemetry data going to your own collector.

Health metrics, profiling and tracer flares require an agent and thus have no effect in agentless mode.

Type: Boolean

Default: (no value)

New in version v4.15.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.reque?t"}]'

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”, “tags”, and “discard” fields are optional. The “sample_rate” value must be between 0.0 and 1.0 (inclusive).

Setting “discard” to true on a rule fully drops a trace chunk the rule rejects, excluding it from client-side stats and the Agent.

Note that with partial flushing enabled (the default), a chunk is matched against the trace’s local root span as it stood when that chunk was flushed, so a rule keyed on data only available later in the request (e.g. a resolved HTTP route) may miss chunks flushed earlier in the same trace.

Example: DD_TRACE_SAMPLING_RULES='[{"sample_rate":0.5,"service":"my-service","resource":"my-url","tags":{"my-tag":"example"}}]'

Example (fully drop a noisy, unsampled endpoint): DD_TRACE_SAMPLING_RULES='[{"sample_rate":0.0,"resource":"/health","discard":true}]'

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.

Changed in version v4.15.0: added support for “discard”

Feature Flagging#

DD_FEATURE_FLAGS_ENABLED#

Stable kill switch for Feature Flagging. When False, the provider is disabled regardless of the configured source.

Type: Boolean

Default: True

DD_FEATURE_FLAGS_CONFIGURATION_SOURCE#

Selects where Feature Flagging loads Universal Flag Configuration from. Supported values are agentless (load directly from the Datadog CDN) and remote_config (deliver via the Datadog Agent’s Remote Configuration). offline is reserved and currently unsupported; any unsupported value disables the provider without contacting either source.

Type: String

Default: agentless

DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL#

Overrides the Datadog-managed agentless Universal Flag Configuration endpoint, for local development or an operator-managed proxy. The URL must use HTTP or HTTPS. An origin or root URL receives the standard rules-based server path, so http://localhost:8080 resolves to http://localhost:8080/api/v2/feature-flagging/config/rules-based/server; a URL with a non-root path, such as https://ufc-proxy.internal.example.com/ufc, is used verbatim as the exact endpoint. DD_API_KEY is never sent to a custom endpoint. Only applies when DD_FEATURE_FLAGS_CONFIGURATION_SOURCE is agentless. See Use a custom agentless endpoint.

Type: String

Default: (none)

DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS#

The agentless Universal Flag Configuration polling interval in seconds, capped at one hour.

Type: Integer

Default: 30

DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS#

The per-request timeout in seconds for agentless Universal Flag Configuration polls.

Type: Integer

Default: 5

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 between 0 and 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. Values above 599 are clamped so that truncated stacks, including the omitted-frame indicator, stay within the profiling backend’s 600-location limit.

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 between 0 and 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_GC_ENABLED#

Whether to add Garbage collection frames on stacks that initiated garbage collection.

Type: Boolean

Default: False

DD_PROFILING_STACK_NATIVE_FRAMES#

Whether to enable native function call tracking in stack profiling (Python 3.12+).

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_PYTORCH_MAX_FRAMES#

Maximum number of frames to capture.

Type: Integer

Default: 128

DD_PROFILING_NATIVE_HEAP_ENABLED#

Whether to enable experimental native (C/C++) heap profiling. Requires DD_PROFILING_ENABLED=true, Linux, and a wheel built with DD_PROFILING_NATIVE_HEAP_ENABLED=1. Disabled by default.

Type: Boolean

Default: False

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_MEMORY_MEM_DOMAIN_ENABLED#

Profile PyMem_Malloc/Calloc/Realloc events (allocations in the Mem domain). Requires Python 3.12 or later. Enabled by default.

Type: Boolean

Default: True

DD_PROFILING_LOCK_ENABLED#

Whether to enable the lock profiler.

Type: Boolean

Default: True

DD_PROFILING_LOCK_EXCLUDE_MODULES#

Comma-separated list of module or package names to exclude from lock profiling. Locks created from these modules are not profiled. Setting this environment variable REPLACES the in-tree default rather than appending to it; users who only need to add an entry should reproduce the full default list and append to it. Examples: ddtrace (excludes profiler overhead), django.db,sqlalchemy.pool,urllib3.

Type: String

Default: frozenset({‘http’, ‘asyncio’, ‘datadog’, ‘logging’, ‘threading’, ‘envier’, ‘bytecode’, ‘ddsketch’, ‘anyio’, ‘ddtrace’, ‘uvicorn’, ‘concurrent’, ‘h11’, ‘werkzeug’, ‘wrapt’, ‘gunicorn’})

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

DD_PROFILING_EXCEPTION_COLLECT_MESSAGE#

Whether to collect exception messages, which can contain sensitive data.

Type: Boolean

Default: False

DD_PROFILING_EXCEPTION_ENABLED#

Whether to enable the exception profiler.

Type: Boolean

Default: True

DD_PROFILING_EXCEPTION_SAMPLING_INTERVAL#

Average number of exceptions between samples (uses Poisson distribution). Lower values sample more frequently but add more overhead.This value must be >= 1.

Type: Integer

Default: 100

Dynamic Instrumentation#

DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS#

Maximum wall-time in milliseconds for snapshot capture and serialization per probe invocation.

Type: Integer

Default: 150

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_EVALUATION_TIMEOUT_MS#

Maximum wall-time in milliseconds for condition and template expression evaluation per probe invocation.

Type: Integer

Default: 50

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

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)