---
title: Configure the Datadog Tracing Library
description: >-
  Configure Datadog tracing libraries with environment variables, runtime
  settings, and language-specific options for optimal APM performance.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Configure the Datadog Tracing
  Library
---

# Configure the Datadog Tracing Library

This page describes configuration options that behave consistently across all languages. To view these common configuration options, see Common configuration options.
To verify your runtime configuration and confirm settings, view the current configuration of your service in Datadog. Navigate to the **APM Service Page**, click **Service Config**, and select the **SDK Configuration** tab.
For configuration options specific to your programming language, choose your language from the options below:

- [Java](https://docs.datadoghq.com/tracing/trace_collection/library_config/java/)
- [Python](https://docs.datadoghq.com/tracing/trace_collection/library_config/python/)
- [Ruby](https://docs.datadoghq.com/tracing/trace_collection/library_config/ruby/)
- [Go](https://docs.datadoghq.com/tracing/trace_collection/library_config/go/)
- [Node.js](https://docs.datadoghq.com/tracing/trace_collection/library_config/nodejs/)
- [PHP](https://docs.datadoghq.com/tracing/trace_collection/library_config/php/)
- [C++](https://docs.datadoghq.com/tracing/trace_collection/library_config/cpp/)
- [.Net](https://docs.datadoghq.com/tracing/trace_collection/library_config/dotnet-core/)
- [.Net](https://docs.datadoghq.com/tracing/trace_collection/library_config/dotnet-framework/)
- [Rust](https://docs.datadoghq.com/tracing/trace_collection/library_config/rust/)

To instrument an application written in a language that does not yet have official library support, see the list of [community tracing libraries](https://docs.datadoghq.com/extend/community/libraries.md#apm-tracing-client-libraries).

## Common configuration options{% #common-configuration-options %}

The following configuration options behave consistently across the latest versions of all Datadog SDKs, unless otherwise noted:

### Agent{% #agent %}

{% dl %}

{% dt %}
`DD_TRACE_AGENT_URL`
{% /dt %}

{% dd %}
**Default**: `http://localhost:8126`**Supported Input**: A string representing an HTTP or UDS url**Description**: The URL for connecting the tracer to the Datadog agent. Valid URL schemas include `http://` and `unix://` (UNIX Domain Sockets). This value takes precedence over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT` if set.
{% /dd %}

{% dt %}
`DD_DOGSTATSD_PORT`
{% /dt %}

{% dd %}
**Default**: `8125`**Supported Input**: Integer between 0 and 65535**Caveats**: Not supported in C++, Ruby, .NET**Description**: Specifies the port number for the DogStatsD server to which runtime metrics are sent.
{% /dd %}

{% dt %}
`DD_DOGSTATSD_HOST`
{% /dt %}

{% dd %}
**Default**: `localhost`**Supported Input**: String representing a hostname or IP address**Caveats**: Not supported in C++, Ruby, .NET**Description**: Specifies the hostname or IP address of the DogStatsD server to which runtime metrics are sent.
{% /dd %}

{% /dl %}

### Unified Service Tagging{% #unified-service-tagging %}

{% dl %}

{% dt %}
`DD_VERSION`
{% /dt %}

{% dd %}
**Default**: `null`**Supported Input**: A string representing an application version**Caveats**: Node.js defaults to the version number from package.json**Description**: Adds a `version` tag to all spans, except for [Inferred services](https://docs.datadoghq.com/tracing/services/inferred_services.md)
{% /dd %}

{% dt %}
`DD_SERVICE`
{% /dt %}

{% dd %}
**Default**: `null`, the SDK tries to automatically determine a service name**Supported Input**: A string representing an application service name**Description**: Sets the default service name used for most spans. SDKs may set a different service name for inferred services. Integration spans may use their own default names, which can differ from the value specified in `DD_SERVICE`
{% /dd %}

{% dt %}
`DD_ENV`
{% /dt %}

{% dd %}
**Default**: `null`**Supported Input**: A string representing an application environment name (for example, `prod`, `dev`)**Description**: Adds an environment tag to all spans generated by the tracer instance.
{% /dd %}

{% dt %}
`DD_TAGS`
{% /dt %}

{% dd %}
**Default**: `null`**Supported Input**: A string representing key value pairs that are delimited by a colon and separated by a comma and/or a space (for example, `<key1>:<value1>, <key2>:<value2>`\>)**Description**: Tags to apply to produced data. Must be a list of `<key>:<value>` separated by commas and/or spaces.
{% /dd %}

{% /dl %}

### Diagnostics{% #diagnostics %}

{% dl %}

{% dt %}
`DD_TRACE_LOG_DIRECTORY`
{% /dt %}

{% dd %}
**Default**: Varies by SDK, environment, and runtime. Please read more in the specific configuration page above for your chosen language**Supported Input**: A valid full or relative directory path that exists on the system**Caveats**: Not supported in Java, Node.js, Ruby, Python**Description**: Specifies the directory where tracer log files should be routed. If the directory does not exist, the SDK falls back to its default diagnostic logging method.
{% /dd %}

{% /dl %}

### Metrics{% #metrics %}

{% dl %}

{% dt %}
`DD_RUNTIME_METRICS_ENABLED`
{% /dt %}

{% dd %}
**Default**: `false`**Supported Input**: Boolean (`true`/`false`)**Caveats**: Not supported in C++ or PHP**Description**: Enables or disables the collection of [runtime metrics](https://docs.datadoghq.com/tracing/metrics/runtime_metrics.md) (such as garbage collection stats, memory usage, and thread counts) for the application.
{% /dd %}

{% /dl %}

### Traces{% #traces %}

{% dl %}

{% dt %}
`DD_APM_TRACING_ENABLED`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean**Description**: Enables or disables sending traces from the application, without impacting other library features such as profiling, Datadog App and API Protection (AAP), Data Streams Monitoring (DSM), and more.
{% /dd %}

{% dt %}
`DD_TRACE_ENABLED`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean**Caveats**: Fully disables the library, including other library features, in Node.js, PHP, Ruby, .NET, and C++. Partially disables the library in Java and Python. Behaves identically to `DD_APM_TRACING_ENABLED` in Go.**Description**: Enables or disables sending traces from the application.
{% /dd %}

{% dt %}
`DD_LOGS_INJECTION`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean (`true`/`false`)**Caveats**: Not supported in C++ or Go.**Description**: Enables or disables the automatic injection of trace context (trace ID, span ID) into JSON/structured application logs. This allows for correlation between traces and logs.
{% /dd %}

{% dt %}
`DD_TRACE_RATE_LIMIT`
{% /dt %}

{% dd %}
**Default**: `100`**Supported Input**: A positive integer**Caveats**: `200` is the default value of `DD_TRACE_RATE_LIMIT` in C++**Description**: Sets the maximum number of traces to sample per second; applies only when either `DD_TRACE_SAMPLING_RULES` or `DD_TRACE_SAMPLE_RATE` is set.
{% /dd %}

{% dt %}
`DD_TRACE_HEADER_TAGS`
{% /dt %}

{% dd %}
**Default**: `null`**Supported Input**: A comma-separated string representing a list of case-insensitive HTTP headers, with an optional mapping to a custom tag name. Example: `User-Agent:my-user-agent,Content-Type`.**Description**: Automatically apply specified HTTP headers as span tags. If a custom tag name is not specified, the tag key defaults to `http.request.headers.<normalized-header-name>` for request headers and `http.response.headers.<normalized-header-name>` for response headers.
{% /dd %}

{% dt %}
`DD_TRACE_SAMPLE_RATE`
{% /dt %}

{% dd %}
**Default**: `-1`. If unset, the tracer defers to the Datadog Agent to control sample rate.**Supported Input**: A number between 0.0 and 1.0, inclusive.**Caveats**: This variable is deprecated in favor of `DD_TRACE_SAMPLING_RULES`, which provides more flexible and granular sampling control.**Description**: Controls the trace ingestion sample rate between the Datadog Agent and the backend. Must be a number between 0.0 and 1.0, where 1.0 means all traces are sent to the backend and 0.0 means none are sent. This is precise up to 6 digits, applies globally to all traces, and does not support per-service or per-operation targeting.
{% /dd %}

{% dt %}
`DD_TRACE_SAMPLING_RULES`
{% /dt %}

{% dd %}
**Default**: `null`. If unset or no rules match, the tracer defers to the Datadog Agent to dynamically adjust sample rate across traces.**Supported Input**: A JSON array of [user-defined rules](https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms.md?tab=java#in-tracing-libraries-user-defined-rules).**Description**: Enables fine-grained control over trace ingestion, allowing you to target specific services, operations, resources, or tagged traces. Defined by a JSON array of objects, where each object must include a `sample_rate` between 0.0 and 1.0 (inclusive), and can optionally include fields such as `service`, `name`, `resource`, `tags`, and `max_per_second`. Objects are evaluated in the order listed; the first matching object determines the trace's sample rate. For more information, see [Ingestion Mechanisms](https://docs.datadoghq.com/tracing/trace_pipeline/ingestion_mechanisms.md).**Examples**:
- Sample 20% of all traces:

  ```
  [{"sample_rate": 0.2}]
  ```

- Sample 10% of traces where the service name starts with `a` and the operation name is `b`, and 20% of all others:

  ```
  [{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]
  ```

- Sample 40% of traces with the resource name `HTTP GET`:

  ```
  [{"resource": "HTTP GET", "sample_rate": 0.4}]
  ```

- Sample 100% of traces with the tag `tier=premium`:

  ```
  [{"tags": {"tier": "premium"}, "sample_rate": 1}]
  ```

- Sample up to 50 traces per second at a 50% rate for the service `my-service` and operation name `http.request`:

  ```
  [{"service": "my-service", "name": "http.request", "sample_rate": 0.5, "max_per_second": 50}]
  ```

{% /dd %}

{% dt %}
`DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP`
{% /dt %}

{% dd %}
**Default**:
```
(?i)(?:(?:"|%22)?)(?:(?:old[-_]?|new[-_]?)?p(?:ass)?w(?:or)?d(?:1|2)?|pass(?:[-_]?phrase)?|secret|(?:api[-_]?|private[-_]?|public[-_]?|access[-_]?|secret[-_]?|app(?:lication)?[-_]?)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._-]+)?)
```

{% /dd %}

{% dd %}
**Supported Input**: A regex string
{% /dd %}

{% dd %}
**Description**: Applies a regex to redact sensitive data from query strings on incoming HTTP requests. The default regex matches various sensitive data patterns, including passwords, tokens, API keys, private keys, and authorization terms. Matches are replaced with `<redacted>`. If an empty string is passed, no obfuscation occurs. The resulting value is reported in the `http.url` tag.
{% /dd %}

{% dt %}
`DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean (`true`/`false`)**Description**: Controls whether new traces use 128-bit W3C trace IDs (32-character hexadecimal strings) or 64-bit Datadog trace IDs (16-character hexadecimal strings). The default is `true` to support W3C trace context propagation.
{% /dd %}

{% dt %}
`DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean (`true`/`false`)**Caveats**: Not supported in C++**Description**: Controls whether 128-bit trace IDs are logged in their full 32-character format or truncated to 16 characters. Set to `false` for compatibility with systems that expect the shorter format.
{% /dd %}

{% dt %}
`DD_TRACE_CLIENT_IP_ENABLED`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean (`true`/`false`)**Caveats**: Not supported in C++**Description**: Enables or disables the automatic collection of client IP addresses from HTTP request headers. When enabled, the IP address is stored in the `http.client_ip` span tag.
{% /dd %}

{% dt %}
`DD_TRACE_EXPERIMENTAL_FEATURES_ENABLED`
{% /dt %}

{% dd %}
**Default**: `null`**Supported Input**: A comma-separated list of configuration options that support experimental features.**Supported Values**: `all`, `DD_TAGS` (Java, .NET)**Caveats**: Only supported in Java and .NET**Description**: Enables experimental features for specific configuration options. When enabled, these features may provide additional functionality but are not yet considered stable and may change or be removed in future releases. You can enable all experimental features using the keyword `all`, or list individual features explicitly.
{% /dd %}

{% /dl %}

### Integrations{% #integrations %}

{% dl %}

{% dt %}
`DD_TRACE_<INTEGRATION>_ENABLED`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean**Caveats**: Not supported in Go; [Some Java integrations are disabled by default](https://docs.datadoghq.com/tracing/trace_collection/compatibility/java.md#framework-integrations-disabled-by-default).**Description**: Enables or disables instrumentation for the specified `<INTEGRATION>`. The integration name must be in uppercase (for example, `DD_TRACE_KAFKA_ENABLED=true`)
{% /dd %}

{% dt %}
`DD_TRACE_HTTP_CLIENT_ERROR_STATUSES`
{% /dt %}

{% dd %}
**Default**: `400-499`**Supported Input**: A comma-separated string of the form `from-to`, where `from` and `to` are integers. Singular values are also accepted (for example, `400-403,405,410-499`).**Caveats**: Not supported in Node.js**Description**: Defines the inclusive range of status codes to be considered as errors on automatically collected HTTP client spans. Only the values within the specified range are considered errors.
{% /dd %}

{% dt %}
`DD_TRACE_HTTP_SERVER_ERROR_STATUSES`
{% /dt %}

{% dd %}
**Default**: `500-599`**Supported Input**: A comma-separated string of the form `from-to`, where `from` and `to` are integers. Singular values are also accepted (for example, `400-403,405,410-499`).**Caveats**: Not supported in Node.js**Description**: Defines the inclusive range of status codes to be considered errors on `http.server` span kinds. Only the values within the specified range are considered errors.
{% /dd %}

{% dt %}
`DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING`
{% /dt %}

{% dd %}
**Default**: `true`**Supported Input**: Boolean**Caveats**: Not supported in Node.js; Disabled by default in Go**Description**: Enables or disables the inclusion of the query string in the `http.url` span tag value for automatically collected HTTP spans.
{% /dd %}

{% dt %}
`DD_TRACE_CLIENT_IP_HEADER`
{% /dt %}

{% dd %}
**Default**: `null`**Supported Input**: Any non-empty string**Description**: Configures a custom header name from which to source the `http.client_ip` tag value. If this variable is set, all other IP-related headers are ignored (for example, setting `DD_TRACE_CLIENT_IP_HEADER=custom-ip-header` and including the header `custom-ip-header: 5.6.7.9` in a request results in a span tagged with `"http.client_ip": "5.6.7.9"`). If an empty string or null value is passed, IP headers are queried in this order:
- `x-forwarded-for`
- `x-real-ip`
- `true-client-ip`
- `x-client-ip`
- `x-forwarded`
- `forwarded-for`
- `x-cluster-client-ip`
- `fastly-client-ip`
- `cf-connecting-ip`
- `cf-connecting-ipv6`

{% /dd %}

{% /dl %}

### Context propagation{% #context-propagation %}

{% dl %}

{% dt %}
`DD_TRACE_BAGGAGE_MAX_ITEMS`
{% /dt %}

{% dd %}
**Default**: `64`**Supported Input**: A positive integer**Description**: The maximum number of key-value pairs in the baggage header.
{% /dd %}

{% dt %}
`DD_TRACE_BAGGAGE_MAX_BYTES`
{% /dt %}

{% dd %}
**Default**: `8192`**Supported Input**: A positive integer**Description**: The maximum number of bytes in the baggage header value. Values less than 3 bytes prevent propagation, because this is the minimum size for a valid key-value pair (for example, `k=v`).
{% /dd %}

{% dt %}
`DD_TRACE_BAGGAGE_TAG_KEYS`
{% /dt %}

{% dd %}
**Default**: `user.id,session.id,account.id`**Supported Input**: A comma-separated string representing a list of case-sensitive baggage keys**Caveats**: Not supported in C++**Description**: A comma-separated list of baggage keys that are automatically applied as span tags to the local root span. For example, a baggage key `user.id` is tagged as `baggage.user.id`This feature only applies to baggage extracted from incoming HTTP headers. Baggage set with the baggage API is not included.
- To tag all baggage items, set the value to `*`. Use this with caution to avoid exposing sensitive data in tags.
- To disable this feature, set the value to an empty string.

{% /dd %}

{% /dl %}