---
title: Configuring the Java Tracing Library
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Configure the Datadog Tracing
  Library > Configuring the Java Tracing Library
---

# Configuring the Java Tracing Library

After you set up the tracing library with your code and configure the Agent to collect APM data, optionally configure the tracing library as desired, including setting up [Unified Service Tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/).
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.
All configuration options below have system property and environment variable equivalents. If the same key type is set for both, the system property configuration takes priority. System properties can be set as JVM flags.

### Converting between system properties and environment variables{% #converting-between-system-properties-and-environment-variables %}

Unless otherwise stated, you can convert between system properties and environment variables with the following transformations:

- To set a system property as an environment variable, uppercase the property name and replace `.` or `-` with `_`. For example, `dd.service` becomes `DD_SERVICE`.
- To set an environment variable as a system property, lowercase the variable name and replace `_` with `.` For example, `DD_TAGS` becomes `dd.tags`.

**Note**: When using the Java tracer's system properties, list the properties before `-jar`. This ensures the properties are read in as JVM options.

## Configuration options{% #configuration-options %}

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

{% dl %}

{% dt %}
`dd.service`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_SERVICE`**Default**: `unnamed-java-app`The name of a set of processes that do the same job. Used for grouping stats for your application. Available for versions 0.50.0+.
{% /dd %}

{% dt %}
`dd.env`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_ENV`**Default**: `none`Your application environment (for example, production, staging). Available for versions 0.48+.
{% /dd %}

{% dt %}
`dd.version`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_VERSION`**Default**: `null`Your application version (for example, 2.5, 202003181415, 1.3-alpha). Available for versions 0.48+.
{% /dd %}

{% /dl %}

### Traces{% #traces %}

{% dl %}

{% dt %}
`dd.trace.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_ENABLED`**Default**: `true`When `false` tracing agent is disabled.See also [DD_APM_TRACING_ENABLED](https://docs.datadoghq.com/tracing/trace_collection/library_config/#traces).
{% /dd %}

{% dt %}
`dd.trace.config`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CONFIG`**Default**: `null`Optional path to a file where configuration properties are provided one per each line. For instance, the file path can be provided as via `-Ddd.trace.config=<FILE_PATH>.properties`, with setting the service name in the file with `dd.service=<SERVICE_NAME>`**Note**: Don't rely on `dd.trace.config` as the only mechanism to enable or disable SDK-dependent products (for example, Profiler and Dynamic Instrumentation). Instead, use the corresponding system properties or environment variables (or `application_monitoring.yaml` for Single Step Instrumentation).
{% /dd %}

{% dt %}
`dd.service.mapping`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_SERVICE_MAPPING`**Default**: `null`**Example**: `mysql:my-mysql-service-name-db, postgresql:my-postgres-service-name-db`Dynamically rename services via configuration. Useful for making databases have distinct names across different services.
{% /dd %}

{% dt %}
`dd.writer.type`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_WRITER_TYPE`**Default**: `DDAgentWriter`Default value sends traces to the Agent. Configuring with `LoggingWriter` instead writes traces out to the console.
{% /dd %}

{% dt %}
`dd.trace.agent.port`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_AGENT_PORT`**Default**: `8126`The port number the Agent is listening on for configured host. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network/#configure-ports) sets `receiver_port` or `DD_APM_RECEIVER_PORT` to something other than the default `8126`, then `dd.trace.agent.port` or `dd.trace.agent.url` must match it.
{% /dd %}

{% dt %}
`dd.trace.agent.unix.domain.socket`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_AGENT_UNIX_DOMAIN_SOCKET`**Default**: `null`This can be used to direct trace traffic to a proxy, to later be sent to a remote Datadog Agent.
{% /dd %}

{% dt %}
`dd.trace.agent.url`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_AGENT_URL`**Default**: `null`The URL to send traces to. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network/#configure-ports) sets `receiver_port` or `DD_APM_RECEIVER_PORT` to something other than the default `8126`, then `dd.trace.agent.port` or `dd.trace.agent.url` must match it. The URL value can start with `http://` to connect using HTTP or with `unix://` to use a Unix Domain Socket. When set this takes precedence over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT`. Available for versions 0.65+.
{% /dd %}

{% dt %}
`dd.trace.agent.timeout`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_AGENT_TIMEOUT`**Default**: `10`Timeout in seconds for network interactions with the Datadog Agent.
{% /dd %}

{% dt %}
`dd.trace.client-ip.enabled`
{% /dt %}

{% dd %}
**Default**: `false`Enable client IP collection from relevant IP headers in HTTP request spans. Automatically enabled when `dd.appsec.enabled=true`.
{% /dd %}

{% dt %}
`dd.trace.header.tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HEADER_TAGS`**Default**: `null`**Example**: `CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name`Accepts a map of case-insensitive header keys to tag names and automatically applies matching header values as tags on traces. Also accepts entries without a specified tag name that are automatically mapped to tags of the form `http.request.headers.<header-name>` and `http.response.headers.<header-name>` respectively.Prior to version 0.96.0 this setting only applied to request header tags. To change back to the old behavior, add the setting `-Ddd.trace.header.tags.legacy.parsing.enabled=true` or the environment variable `DD_TRACE_HEADER_TAGS_LEGACY_PARSING_ENABLED=true`.Starting in version 1.18.3, if [Agent Remote Configuration](https://docs.datadoghq.com/tracing/guide/remote_config) is enabled where this service runs, you can set `DD_TRACE_HEADER_TAGS` in the [Software Catalog](https://app.datadoghq.com/services) UI.
{% /dd %}

{% dt %}
`dd.trace.request_header.tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_REQUEST_HEADER_TAGS`**Default**: `null`**Example**: `CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name`Accepts a map of case-insensitive header keys to tag names and automatically applies matching request header values as tags on traces. Also accepts entries without a specified tag name that are automatically mapped to tags of the form `http.request.headers.<header-name>`.Available since version 0.96.0.
{% /dd %}

{% dt %}
`dd.trace.response_header.tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_RESPONSE_HEADER_TAGS`**Default**: `null`**Example**: `CASE-insensitive-Header:my-tag-name,User-ID:userId,My-Header-And-Tag-Name`Accepts a map of case-insensitive header keys to tag names and automatically applies matching response header values as tags on traces. Also accepts entries without a specified tag name that are automatically mapped to tags of the form `http.response.headers.<header-name>`.Available since version 0.96.0.
{% /dd %}

{% dt %}
`dd.trace.header.baggage`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HEADER_BAGGAGE`**Default**: `null`**Example**: `CASE-insensitive-Header:my-baggage-name,User-ID:userId,My-Header-And-Baggage-Name`Accepts a map of case-insensitive header keys to baggage keys and automatically applies matching request header values as baggage on traces. On propagation the reverse mapping is applied: Baggage is mapped to headers.Available since version 1.3.0.
{% /dd %}

{% dt %}
`dd.trace.annotations`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_ANNOTATIONS`**Default**: ([listed here](https://github.com/DataDog/dd-trace-java/blob/master/dd-java-agent/instrumentation/trace-annotation/src/main/java/datadog/trace/instrumentation/trace_annotation/TraceAnnotationsInstrumentation.java#L37))**Example**: `com.some.Trace;io.other.Trace`A list of method annotations to treat as `@Trace`.
{% /dd %}

{% dt %}
`dd.trace.methods`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_METHODS`**Default**: `null`**Example**: `package.ClassName[method1,method2,...];AnonymousClass$1[call];package.ClassName[*]`List of class/interface and methods to trace. Similar to adding `@Trace`, but without changing code. **Note:** The wildcard method support (`[*]`) does not accommodate constructors, getters, setters, synthetic, toString, equals, hashcode, or finalizer method calls. `dd.trace.methods` is not intended for tracing large numbers of methods and classes. To find CPU, memory, and IO bottlenecks, broken down by method name, class name, and line number, consider the [Continuous Profiler](https://docs.datadoghq.com/profiler/) product instead.
{% /dd %}

{% dt %}
`dd.trace.classes.exclude`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CLASSES_EXCLUDE`**Default**: `null`**Example**: `package.ClassName,package.ClassName$Nested,package.Foo*,package.other.*`A list of fully qualified classes (that may end with a wildcard to denote a prefix) which will be ignored (not modified) by the tracer. Must use the jvm internal representation for names (eg package.ClassName$Nested and not package.ClassName.Nested)
{% /dd %}

{% dt %}
`dd.trace.partial.flush.min.spans`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_PARTIAL_FLUSH_MIN_SPANS`**Default**: `1000`Set a number of partial spans to flush on. Useful to reduce memory overhead when dealing with heavy traffic or long running traces.
{% /dd %}

{% dt %}
`dd.trace.split-by-tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_SPLIT_BY_TAGS`**Default**: `null`**Example**: `aws.service`Used to rename the service name associated with spans to be identified with the corresponding span tag
{% /dd %}

{% dt %}
`dd.trace.health.metrics.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HEALTH_METRICS_ENABLED`**Default**: `true`When set to `true` sends tracer health metrics
{% /dd %}

{% dt %}
`dd.trace.health.metrics.statsd.host`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HEALTH_METRICS_STATSD_HOST`**Default**: Same as `dd.jmxfetch.statsd.host`Statsd host to send health metrics to
{% /dd %}

{% dt %}
`dd.trace.health.metrics.statsd.port`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HEALTH_METRICS_STATSD_PORT`**Default**: Same as `dd.jmxfetch.statsd.port`Statsd port to send health metrics to
{% /dd %}

{% dt %}
`dd.trace.obfuscation.query.string.regexp`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP`**Default**: `null`A regex to redact sensitive data from incoming requests' query string reported in the `http.url` tag (matches are replaced with).
{% /dd %}

{% dt %}
`dd.trace.servlet.async-timeout.error`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_SERVLET_ASYNC_TIMEOUT_ERROR`**Default**: `true`By default, long running asynchronous requests will be marked as an error, setting this value to false allows to mark all timeouts as successful requests.
{% /dd %}

{% dt %}
`dd.trace.span.tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_SPAN_TAGS`**Default**: `none`**Example**: `tag1:value1,tag2:value2`A list of default tags to be added to every span.
{% /dd %}

{% dt %}
`dd.trace.jmx.tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_JMX_TAGS`**Default**: `none`**Example**: `tag1:value1,tag2:value2`A list of span tags to be added to every jmx metric.
{% /dd %}

{% dt %}
`dd.trace.startup.logs`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_STARTUP_LOGS`**Default**: `true`When `false`, informational startup logging is disabled. Available for versions 0.64+.
{% /dd %}

{% dt %}
`dd.trace.debug`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_DEBUG`**Default**: `false`When `true`, debug mode for the Datadog Java Tracer is enabled.
{% /dd %}

{% dt %}
`datadog.slf4j.simpleLogger.jsonEnabled`
{% /dt %}

{% dd %}
**Environment Variable**: Not available**Default**: `false`When `true`, Datadog Java tracer logs are written in JSON. Available for versions 1.48.0+.**Note**: This setting is specific to the embedded SLF4J simple logger and does not support environment variables. `dd.log.format.json` is the preferred configuration option.
{% /dd %}

{% dt %}
`dd.trace.servlet.principal.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_SERVLET_PRINCIPAL_ENABLED`**Default**: `false`When `true`, user principal is collected. Available for versions 0.61+.
{% /dd %}

{% dt %}
`dd.trace.rate.limit`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_RATE_LIMIT`**Default**: `100`Maximum number of spans to sample per second, per process, when `DD_TRACE_SAMPLING_RULES` or `DD_TRACE_SAMPLE_RATE` is set. Otherwise, the Datadog Agent controls rate limiting.
{% /dd %}

{% dt %}
`dd.http.server.tag.query-string`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_HTTP_SERVER_TAG_QUERY_STRING`**Default**: `true`When set to `true` query string parameters and fragment get added to web server spans
{% /dd %}

{% dt %}
`dd.http.server.route-based-naming`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_HTTP_SERVER_ROUTE_BASED_NAMING`**Default**: `true`When set to `false` http framework routes are not used for resource names. *This can change resource names and derived metrics if changed.*
{% /dd %}

{% dt %}
`dd.trace.http.server.path-resource-name-mapping`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HTTP_SERVER_PATH_RESOURCE_NAME_MAPPING`**Default**: `{}` (empty)Maps HTTP request paths to custom resource names. Provide a comma‑separated list of `pattern:resource_name` pairs:– `pattern`: An [Ant‑style path pattern](https://ant.apache.org/manual/dirtasks.html#patterns) that must match the value of the `http.path_group` span tag.– `resource_name`: The custom resource name to assign if the pattern matches.If `*` is used as the `resource_name` for a matching pattern, the original, unnormalized request path combined with the HTTP method is used as the resource name. For example, given the rule `/test/**:*`, a `GET` request for `/test/some/path` results in the resource name `GET /test/some/path`.Mappings are evaluated in order of priority, and the first matching rule applies. Unmatched request paths use the default normalization behavior.**Example**: Using `-Ddd.trace.http.server.path-resource-name-mapping=/admin/*.jsp:/admin-page,/admin/user/**:/admin/user` yields:
| Request path               | Resource path |
| -------------------------- | ------------- |
| `/admin/index.jsp`         | `/admin-page` |
| `/admin/user/12345/delete` | `/admin/user` |
| `/user/12345`              | `/user/?`     |

{% /dd %}

{% dt %}
`dd.trace.http.client.path-resource-name-mapping`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HTTP_CLIENT_PATH_RESOURCE_NAME_MAPPING`**Default**: `{}` (empty)Maps HTTP client request paths to custom resource names. Uses the same format as `dd.trace.http.server.path-resource-name-mapping`, but applies to HTTP client spans instead of server spans.
{% /dd %}

{% dt %}
`dd.trace.status404rule.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_STATUS404RULE_ENABLED`**Default**: `true`By default, HTTP 404 responses use "404" as the span resource name. When `false`, HTTP 404 responses keep the original URL path as the resource name.
{% /dd %}

{% dt %}
`dd.trace.128.bit.traceid.generation.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED`**Default**: `true`When `true`, the tracer generates 128 bit Trace IDs, and encodes Trace IDs as 32 lowercase hexadecimal characters with zero padding.
{% /dd %}

{% dt %}
`dd.trace.128.bit.traceid.logging.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED`**Default**: `false`When `true`, the tracer will inject 128 bit Trace IDs as 32 lowercase hexadecimal characters with zero padding, and 64 bit Trace IDs as decimal numbers. Otherwise, the tracer always injects Trace IDs as decimal numbers.
{% /dd %}

{% dt %}
`dd.trace.otel.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_OTEL_ENABLED`**Default**: `false`When `true`, OpenTelemetry-based tracing for [custom](https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/java/otel/) instrumentation is enabled.
{% /dd %}

{% dt %}
`dd.trace.cloud.payload.tagging.services`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CLOUD_PAYLOAD_TAGGING_SERVICES`**Default**: `ApiGateway,ApiGatewayV2,EventBridge,Sqs,Sns,S3,Kinesis`**Example**: `S3,Sso`To enable [AWS payload tagging](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging/?code-lang=java) for additional services, use this setting.
{% /dd %}

{% dt %}
`dd.trace.cloud.request.payload.tagging`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING`**Default**: N/A (disabled)**Example**: `$.Metadata.UserId,$.phoneNumber`A comma-separated string of JSONPath entries to redact from AWS SDK requests. Setting this enables [AWS payload tagging](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging/?code-lang=java) for requests.
{% /dd %}

{% dt %}
`dd.trace.cloud.response.payload.tagging`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING`**Default**: N/A (disabled)**Example**: `$.Metadata.Credentials.*`A comma-separated string of JSONPath entries to redact from AWS SDK responses. Setting this enables [AWS payload tagging](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging/?code-lang=java) for responses.
{% /dd %}

{% dt %}
`dd.trace.cloud.payload.tagging.max-depth`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH`**Default**: `10`An integer representing the maximum depth of an AWS SDK request/response payload to use for [AWS payload tagging](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging/?code-lang=java).
{% /dd %}

{% dt %}
`dd.trace.cloud.payload.tagging.max-tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_TAGS`**Default**: `758`An integer representing the maximum number of tags to extract per a span to be used for [AWS payload tagging](https://docs.datadoghq.com/tracing/guide/aws_payload_tagging/?code-lang=java).
{% /dd %}

{% /dl %}

### Agent{% #agent %}

{% dl %}

{% dt %}
`dd.tags`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TAGS`**Default**: `null`**Example**: `layer:api,team:intake,key:value`A list of default tags to be added to every span, profile, and JMX metric. If DD_ENV or DD_VERSION is used, it overrides any env or version tag defined in DD_TAGS. Available for versions 0.50.0+.
{% /dd %}

{% dt %}
`dd.agent.host`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_AGENT_HOST`**Default**: `localhost`Hostname for where to send traces to. If using a containerized environment, configure this to be the host IP. See [Tracing Docker Applications](https://docs.datadoghq.com/tracing/setup/docker/) for more details.
{% /dd %}

{% dt %}
`dd.instrumentation.telemetry.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_INSTRUMENTATION_TELEMETRY_ENABLED`**Default**: `true`When `true`, the tracer collects [telemetry data](https://docs.datadoghq.com/tracing/configure_data_security/#telemetry-collection). Available for versions 0.104+. Defaults to `true` for versions 0.115+.
{% /dd %}

{% /dl %}

### Databases{% #databases %}

{% dl %}

{% dt %}
`dd.trace.db.client.split-by-instance`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE`**Default**: `false`When set to `true` db spans get assigned the instance name as the service name
{% /dd %}

{% dt %}
`dd.trace.db.client.split-by-host`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_DB_CLIENT_SPLIT_BY_HOST`**Default**: `false`When set to `true` db spans get assigned the remote database hostname as the service name
{% /dd %}

{% dt %}
`dd.dbm.propagation.mode`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_DBM_PROPAGATION_MODE`**Default**: `null`When set to `service` or `full`, enables Database Monitoring and APM correlation. For more information, see [Correlate Database Monitoring and Traces](https://docs.datadoghq.com/database_monitoring/connect_dbm_and_apm/?tab=java).
{% /dd %}

{% /dl %}

### AAP{% #aap %}

{% dl %}

{% dt %}
`dd.appsec.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_APPSEC_ENABLED`**Default**: `false`When `true`, enables Datadog App and API Protection Monitoring. Additionally, this automatically enables client IP collection (`dd.trace.client-ip.enabled`).For more information, see [Enabling AAP for Java](https://docs.datadoghq.com/security/application_security/setup/threat_detection/java/).
{% /dd %}

{% /dl %}

### Errors{% #errors %}

{% dl %}

{% dt %}
`dd.trace.http.client.tag.query-string`
{% /dt %}

{% dd %}
**System Property (Deprecated)**: `dd.http.client.tag.query-string`**Environment Variable**: `DD_TRACE_HTTP_CLIENT_TAG_QUERY_STRING`**Environment Variable (Deprecated)**: `DD_HTTP_CLIENT_TAG_QUERY_STRING`**Default**: `true`By default, query string parameters and fragments are added to the `http.url` tag on web client spans. Set to `false` to prevent the collection of this data.
{% /dd %}

{% dt %}
`dd.trace.http.client.error.statuses`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HTTP_CLIENT_ERROR_STATUSES`**Default**: `400-499`A range of errors can be accepted. By default 4xx errors are reported as errors for http clients. This configuration overrides that. Ex. `dd.trace.http.client.error.statuses=400-403,405,410-499`
{% /dd %}

{% dt %}
`dd.trace.http.server.error.statuses`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_HTTP_SERVER_ERROR_STATUSES`**Default**: `500-599`A range of errors can be accepted. By default 5xx status codes are reported as errors for http servers. This configuration overrides that. Ex. `dd.trace.http.server.error.statuses=500,502-599`
{% /dd %}

{% dt %}
`dd.grpc.client.error.statuses`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_GRPC_CLIENT_ERROR_STATUSES`**Default**: `1-16`A range of errors can be accepted. By default, gRPC status codes 1 to 16 are reported as errors for gRPC clients. This configuration overrides that. Ex. `dd.grpc.client.error.statuses=1-4,7-10`
{% /dd %}

{% dt %}
`dd.grpc.server.error.statuses`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_GRPC_SERVER_ERROR_STATUSES`**Default**: `2-16`A range of errors can be accepted. By default, gRPC status codes 2 to 16 are reported as errors for gRPC servers. This configuration overrides that. Ex. `dd.grpc.server.error.statuses=2-4,7-10`
{% /dd %}

{% /dl %}

### Logs{% #logs %}

{% dl %}

{% dt %}
`dd.log.level`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_LOG_LEVEL`**Default**: `INFO`Sets the internal log level for the Datadog Java Tracer. Valid values: `DEBUG`, `INFO`, `WARN`, `ERROR`.Available since version 1.36.0
{% /dd %}

{% dt %}
`dd.log.format.json`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_LOG_FORMAT_JSON`**Default**: `false`When `true`, outputs Datadog Java Tracer logs in a JSON format compatible with the Datadog Logs UI.Available since version 1.58.0
{% /dd %}

{% dt %}
`dd.logs.injection`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_LOGS_INJECTION`**Default**: `true`Enabled automatic MDC key injection for Datadog trace and span IDs. See [Advanced Usage](https://docs.datadoghq.com/agent/logs/advanced_log_collection) for details.Starting in version 1.18.3, if [Agent Remote Configuration](https://docs.datadoghq.com/tracing/guide/remote_config) is enabled where this service runs, you can set `DD_LOGS_INJECTION` in the [Software Catalog](https://app.datadoghq.com/services) UI.
{% /dd %}

{% /dl %}

### Trace context propagation{% #trace-context-propagation %}

For information about valid values and using the following configuration options, see [Propagating Java Trace Context](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/).

{% dl %}

{% dt %}
`dd.trace.propagation.style.inject`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_PROPAGATION_STYLE_INJECT`**Default**: `datadog,tracecontext`A comma-separated list of header formats to include to propagate distributed traces between services.Available since version 1.9.0
{% /dd %}

{% dt %}
`dd.trace.propagation.style.extract`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_PROPAGATION_STYLE_EXTRACT`**Default**: `datadog,tracecontext`A comma-separated list of header formats from which to attempt to extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue.Available since version 1.9.0
{% /dd %}

{% dt %}
`dd.trace.propagation.style`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_PROPAGATION_STYLE`**Default**: `datadog,tracecontext`A comma-separated list of header formats from which to attempt to inject and extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue. The more specific `dd.trace.propagation.style.inject` and `dd.trace.propagation.style.extract` configuration settings take priority when present.Available since version 1.9.0
{% /dd %}

{% dt %}
`trace.propagation.extract.first`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_PROPAGATION_EXTRACT_FIRST`**Default**: `false`When set to `true`, stop extracting trace context when a valid one is found.
{% /dd %}

{% /dl %}

### JMX metrics{% #jmx-metrics %}

{% dl %}

{% dt %}
`dd.jmxfetch.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_ENABLED`**Default**: `true`Enable collection of JMX metrics by Java Tracing Agent.
{% /dd %}

{% dt %}
`dd.jmxfetch.config.dir`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_CONFIG_DIR`**Default**: `null`**Example**: `/path/to/directory/etc/conf.d`Additional configuration directory for JMX metrics collection. The Java Agent looks for `jvm_direct:true` in the `instance` section in the `yaml` file to change configuration.
{% /dd %}

{% dt %}
`dd.jmxfetch.config`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_CONFIG`**Default**: `null`**Example**: `path/to/file/conf.yaml,other/path/to/file/conf.yaml`Additional metrics configuration file for JMX metrics collection. The Java Agent looks for `jvm_direct:true` in the `instance` section in the `yaml` file to change configuration.
{% /dd %}

{% dt %}
`dd.jmxfetch.check-period`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_CHECK_PERIOD`**Default**: `15000`How often to send JMX metrics (in ms).
{% /dd %}

{% dt %}
`dd.jmxfetch.refresh-beans-period`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_REFRESH_BEANS_PERIOD`**Default**: `600`How often to refresh list of available JMX beans (in seconds).
{% /dd %}

{% dt %}
`dd.jmxfetch.statsd.host`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_STATSD_HOST`**Default**: Same as `agent.host`Statsd host to send JMX metrics to. If you are using Unix Domain Sockets, use an argument like 'unix://PATH_TO_UDS_SOCKET'. Example: `unix:///var/datadog-agent/dsd.socket`
{% /dd %}

{% dt %}
`dd.jmxfetch.statsd.port`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_STATSD_PORT`**Default**: `8125`StatsD port to send JMX metrics to. If you are using Unix Domain Sockets, input 0.
{% /dd %}

{% dt %}
`dd.jmxfetch.<integration-name>.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JMXFETCH_<INTEGRATION_NAME>_ENABLED`**Default**: `false`JMX integration to enable (for example, Kafka or ActiveMQ).
{% /dd %}

{% /dl %}

### Integrations{% #integrations %}

See how to disable integrations in the [integrations](https://docs.datadoghq.com/tracing/compatibility_requirements/java#disabling-integrations) compatibility section.

{% dl %}

{% dt %}
`dd.integration.opentracing.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_INTEGRATION_OPENTRACING_ENABLED`**Default**: `true`By default the tracing client detects if a GlobalTracer is being loaded and dynamically registers a tracer into it. By turning this to false, this removes any tracer dependency on OpenTracing.
{% /dd %}

{% dt %}
`dd.hystrix.tags.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_HYSTRIX_TAGS_ENABLED`**Default**: `false`By default the Hystrix group, command, and circuit state tags are not enabled. This property enables them.
{% /dd %}

{% dt %}
`dd.trace.elasticsearch.body.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_ELASTICSEARCH_BODY_ENABLED`**Default**: `false`When set to `true`, the body is added to Elasticsearch and OpenSearch spans.
{% /dd %}

{% dt %}
`dd.trace.elasticsearch.params.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_ELASTICSEARCH_PARAMS_ENABLED`**Default**: `true`When set to `true`, the query string parameters are added to Elasticsearch and OpenSearch spans.
{% /dd %}

{% dt %}
`dd.trace.cassandra.keyspace.statement.extraction.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_CASSANDRA_KEYSPACE_STATEMENT_EXTRACTION_ENABLED`**Default**: `false`By default, the keyspace is extracted only if it is configured during session creation. When set to `true`, the keyspace can also be extracted by examining the metadata in the query results.
{% /dd %}

{% dt %}
`dd.trace.websocket.messages.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_WEBSOCKET_MESSAGES_ENABLED`**Default**: `false`Enables tracing sent and received websocket messages (text and binary) and connection close events.
{% /dd %}

{% dt %}
`dd.trace.websocket.messages.inherit.sampling`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_WEBSOCKET_MESSAGES_INHERIT_SAMPLING`**Default**: `true`By default, websocket messages preserve the same sampling as the span captured during the handshake. This ensures that, if a handshake span has been sampled, all the messages in its session will also be sampled. To disable that behavior and sample each websocket message independently, set this configuration to `false`.
{% /dd %}

{% dt %}
`dd.trace.websocket.messages.separate.traces`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_WEBSOCKET_MESSAGES_SEPARATE_TRACES`**Default**: `true`By default, each received message generates a new trace. The handshake is linked to it as a span link. Setting this parameter to `false` causes all the spans captured during the session to be in the same trace.
{% /dd %}

{% dt %}
`dd.trace.websocket.tag.session.id`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_TRACE_WEBSOCKET_TAG_SESSION_ID`**Default**: `false`When set to `true`, the websocket spans have the tag `websocket.session.id` containing the session ID when available.
{% /dd %}

{% /dl %}

**Note**:

- If the same key type is set for both, the system property configuration takes priority.

- System properties can be used as JVM parameters.

- By default, JMX metrics from your application are sent to the Datadog Agent thanks to DogStatsD over port `8125`. Make sure that [DogStatsD is enabled for the Agent](https://docs.datadoghq.com/extend/dogstatsd/#setup).

  - If you are running the Agent as a container, ensure that `DD_DOGSTATSD_NON_LOCAL_TRAFFIC` [is set to `true`](https://docs.datadoghq.com/agent/docker/#dogstatsd-custom-metrics), and that port `8125` is open on the Agent container.
  - In Kubernetes, [bind the DogStatsD port to a host port](https://docs.datadoghq.com/extend/dogstatsd/); in ECS, [set the appropriate flags in your task definition](https://docs.datadoghq.com/agent/amazon_ecs/#create-an-ecs-task).

### UDS{% #uds %}

{% dl %}

{% dt %}
`dd.jdk.socket.enabled`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_JDK_SOCKET_ENABLED`**Default**: `true`Enable native JDK support for Unix Domain Sockets.
{% /dd %}

{% /dl %}

### Examples{% #examples %}

#### `dd.service.mapping`{% #ddservicemapping %}

Example with system property:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.service.mapping=postgresql:web-app-pg -jar path/to/application.jar
```

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/service_mapping.1e4418c4e7268a9e5d7f9b4bdbec658c.png?auto=format"
   alt="service mapping" /%}

#### `dd.tags`{% #ddtags %}

Setting a global env for spans and JMX metrics:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -jar path/to/application.jar
```

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/trace_global_tags.4924c1f09967c8f6142bb1f7038d1822.png?auto=format"
   alt="trace global tags" /%}

#### `dd.trace.span.tags`{% #ddtracespantags %}

Example with adding project:test to every span:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.trace.span.tags=project:test -jar path/to/application.jar
```

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/trace_span_tags.b12c31702ad1ba44461b517dbffa45a5.png?auto=format"
   alt="trace span tags" /%}

#### `dd.trace.jmx.tags`{% #ddtracejmxtags %}

Setting custom.type:2 on a JMX metric:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.trace.span.tags=project:test -Ddd.trace.jmx.tags=custom.type:2 -jar path/to/application.jar
```

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/trace_jmx_tags.ab1f3a6c1f86e1f8c3dae578bb95be87.png?auto=format"
   alt="trace JMX tags" /%}

#### `dd.trace.methods`{% #ddtracemethods %}

Example with system property:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.trace.methods="hello.GreetingController[doSomeStuff,doSomeOtherStuff];hello.Randomizer[randomize]" -jar path/to/application.jar
```

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/trace_methods.a4cf3dfe0943fd95ddc07a0c41b22f75.png?auto=format"
   alt="trace methods" /%}

#### `dd.trace.db.client.split-by-instance`{% #ddtracedbclientsplit-by-instance %}

Example with system property:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.env=dev -Ddd.service=web-app -Ddd.trace.db.client.split-by-instance=TRUE -jar path/to/application.jar
```

DB Instance 1, `webappdb`, now gets its own service name that is the same as the `db.instance` span metadata:

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/split_by_instance_1.1b1cc98848cf748b3d517f040d2060de.png?auto=format"
   alt="instance 1" /%}

DB Instance 2, `secondwebappdb`, now gets its own service name that is the same as the `db.instance` span metadata:

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/split_by_instance_2.bfe603fda9eb49d96941c7db0e16e4c9.png?auto=format"
   alt="instance 2" /%}

Similarly on the service map, you would now see one web app making calls to two different Postgres databases.

#### `dd.http.server.tag.query-string`{% #ddhttpservertagquery-string %}

Example with system property:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.service=web-app -Ddd.env=dev -Ddd.http.server.tag.query-string=TRUE -jar path/to/application.jar
```

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/query_string.9b5adfddf595f54c9b29de7efd0309bd.png?auto=format"
   alt="query string" /%}

#### `dd.trace.enabled`{% #ddtraceenabled %}

Example with system property and debug app mode:

```shell
java -javaagent:/path/to/dd-java-agent.jar -Ddd.trace.enabled=false -Ddd.trace.debug=true -jar path/to/application.jar
```

Debug app logs show that `Tracing is disabled, not installing instrumentations.`

#### `dd.jmxfetch.config.dir` and `dd.jmxfetch.config`{% #ddjmxfetchconfigdir-and-ddjmxfetchconfig %}

Example configuration:

- Either the combination of: `DD_JMXFETCH_CONFIG_DIR=<DIRECTORY_PATH>` + `DD_JMXFETCH_CONFIG=conf.yaml`
- Or directly: `DD_JMXFETCH_CONFIG=<DIRECTORY_PATH>/conf.yaml`

With the following content for `conf.yaml`:

```yaml
init_config:
instances:
    - jvm_direct: true
      port: '<PORT>'
      conf:
          - include:
                bean:
                    - java.lang:type=MemoryPool,name=Metaspace
                attribute:
                    Usage.used:
                        metric_type: gauge
                        alias: sb.usage.used
```

Would produce the following result:

{% image
   source="https://datadog-docs.imgix.net/images/tracing/setup/java/jmxfetch_example.69f52b3d632f112e76941720a3ff4bd7.png?auto=format"
   alt="JMX fetch example" /%}

See the [Java integration documentation](https://docs.datadoghq.com/integrations/java/?tab=host#metric-collection) to learn more about Java metrics collection with JMX fetch.

#### Deprecated extraction and injection settings{% #deprecated-extraction-and-injection-settings %}

These extraction and injection settings have been deprecated in favor of the `dd.trace.propagation.style.inject`, `dd.trace.propagation.style.extract`, and `dd.trace.propagation.style` settings since version 1.9.0. See [Propagating Java Trace Context](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/). The previous `b3` setting for both B3 multi header and B3 single header has been replaced with the new settings `b3multi` and `b3single`.

{% dl %}

{% dt %}
`dd.propagation.style.inject`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_PROPAGATION_STYLE_INJECT`**Default**: `datadog`A comma-separated list of header formats to include to propagate distributed traces between services.Deprecated since version 1.9.0
{% /dd %}

{% dt %}
`dd.propagation.style.extract`
{% /dt %}

{% dd %}
**Environment Variable**: `DD_PROPAGATION_STYLE_EXTRACT`**Default**: `datadog`A comma-separated list of header formats from which to attempt to extract distributed tracing propagation data. The first format found with complete and valid headers is used to define the trace to continue.Deprecated since version 1.9.0
{% /dd %}

{% /dl %}

## Further Reading{% #further-reading %}

- [Datadog Java APM source code](https://github.com/DataDog/dd-trace-java)
- [Explore your services, resources and traces](https://docs.datadoghq.com/tracing/glossary/)
- [Propagating trace context with headers](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/)
- [OpenTelemetry Environment Variable Configurations](https://docs.datadoghq.com/opentelemetry/interoperability/environment_variable_support)