---
title: Java agent distributed tracing settings
source: https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-distributed-tracing-settings
---

Distributed tracing settings control how the agent propagates trace context across services, configures span event collection, and enables Infinite Tracing.

> #### 💡 TIP
>
> Back to the full settings index: [Java agent configuration](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file)

## Distributed tracing [#dt-main]

> #### ⚠️ IMPORTANT
>
> Enabling distributed tracing disables [cross application tracing](#Cross_Application_Tracer), and has other effects on APM features. Before enabling, read the [transition guide](https://docs.newrelic.com/docs/transition-guide-distributed-tracing).
>
> Requires [Java agent version 4.3.0 or higher](https://docs.newrelic.com/docs/agents/java-agent/installation/upgrade-java-agent).

[Distributed tracing](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/get-started/introduction-distributed-tracing) lets you see the path that a request takes as it travels through a distributed system. It is on by default for Java agent version 7.4.0 or higher.

In the config file, you can override this manually in the `distributed_tracing` section. You can also override this using a prefixed system property (`newrelic.config.distributed_tracing`) or an environment variable (`NEW_RELIC_DISTRIBUTED_TRACING_ENABLED`). See the examples below.

For more information about setting up distributed tracing, see [Enable distributed tracing for your Java applications](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/distributed-tracing-go-agent).

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Set this to `false` to disable distributed tracing. For example, in the config file, you would use:

````yml
distributed_tracing:
  enabled: false
```

Here are other options to disable distributed tracing:

[System property](/docs/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties):

```ini
-Dnewrelic.config.distributed_tracing.enabled=false
```

Evironment variable:

```ini
NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=false
```

````

**exclude_newrelic_header**

| Type    | Boolean |
| ------- | ------- |
| Default | `false` |

By default, supported versions of the agent utilize both the `newrelic` header and W3C Trace Context headers for distributed tracing. The `newrelic` distributed tracing header allows interoperability with older agents that don't support W3C Trace Context headers. Agent versions that support W3C Trace Context headers will prioritize them over `newrelic` headers for distributed tracing.

If you do not want to utilize the `newrelic` header, setting this to `true` will result in the agent excluding the `newrelic` header and only using W3C Trace Context headers for distributed tracing.

For example, to exclude `newrelic` headers in the config file, you would use:

````yml
distributed_tracing:
  exclude_newrelic_header: true
```

To exclude `newrelic` headers using a [system property](/docs/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties), you would use:

```ini
-Dnewrelic.config.distributed_tracing.exclude_newrelic_header=true
```

````

**sampler.adaptive_sampling_target**

| Type    | Integer, between 1 (inclusive) and 120 (inclusive) |
| ------- | -------------------------------------------------- |
| Default | `120`                                              |

Sets the global adaptive sampling target, shared by the `root`, `remote_parent_sampled`, and `remote_parent_not_sampled` contexts. This target controls the number of traces per minute the [adaptive sampler](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#adaptive-sampler) attempts to capture. A context can override this global default with its own context-specific `adaptive.sampling_target`.

````yaml
distributed_tracing:
  sampler:
    adaptive_sampling_target: 30  # Applied to all contexts without an explicit override
```

For more information, see [Configure sampling: Adaptive sampling targets](/docs/apm/distributed-tracing/distributed-trace-sampling#adaptive-targets).

````

**sampler.root**

| Type    | String or nested property |
| ------- | ------------------------- |
| Default | `adaptive`                |

Configures the sampler used for the [root context](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#root-context) (distributed traces that originate from the current service). The possible values are:

-   `adaptive`: Use New Relic's default [Adaptive Sampler](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#adaptive-sampler).
    -   Optional parameter: [`sampler.root.adaptive.sampling_target`](#dt-sampler-root-adaptive-sampling_target)
-   `trace_id_ratio_based`: Sample a fixed percentage of traces [based on trace ID](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#trace-id-ratio-based-sampler)
    -   Required parameter: [`sampler.root.trace_id_ratio_based.ratio`](#dt-sampler-root-trace_id_ratio_based-ratio)
-   `always_on`: Sample all root traces.
-   `always_off`: Sample no root traces.

````yaml
distributed_tracing:
  sampler:
    root: adaptive
```

<CollapserGroup>
  <Collapser
    id="dt-sampler-root-adaptive-sampling_target"
    title="root.adaptive.sampling_target"
  >
    <table>
      <tbody>
        <tr>
          <th>
            Type
          </th>

          <td>
            Integer, between 1 (inclusive) and 120 (inclusive)
          </td>
        </tr>

        <tr>
          <th>
            Default
          </th>

          <td>
            [`sampler.adaptive_sampling_target`](#dt-sampler-adaptive_sampling_target)
          </td>
        </tr>

        <tr>
          <th>
            Required
          </th>

          <td>
            No
          </td>
        </tr>
      </tbody>
    </table>

    Overrides the global [`adaptive_sampling_target`](#dt-sampler-adaptive_sampling_target) for the `root` context only, setting the number of root traces per minute the adaptive sampler attempts to capture.

    ```yaml
    distributed_tracing:
      sampler:
        adaptive_sampling_target: 120  # Global default
        root:
          adaptive:
            sampling_target: 5  # Overrides global default to capture 5 traces/min for the root context
    ```
  </Collapser>

  <Collapser
    id="dt-sampler-root-trace_id_ratio_based-ratio"
    title="root.trace_id_ratio_based.ratio"
  >
    <table>
      <tbody>
        <tr>
          <th>
            Type
          </th>

          <td>
            Float, between 0.0 (exclusive) and 1.0 (inclusive)
          </td>
        </tr>

        <tr>
          <th>
            Default
          </th>

          <td>
            None
          </td>
        </tr>

        <tr>
          <th>
            Required
          </th>

          <td>
            Yes
          </td>
        </tr>
      </tbody>
    </table>

    Specifies the percentage of root traces to capture, based on trace ID. See [Configure sampling: Trace ID ratio based sampler](/docs/apm/distributed-tracing/distributed-trace-sampling#trace-id-ratio-based-sampler).

    <Callout variant="important">
      The `ratio` property is required when using the `trace_id_ratio_based` sampler. If a ratio is not set, the default
      Adaptive Sampler will be used for this context instead.
    </Callout>

    ```yaml
    distributed_tracing:
      sampler:
        root:
          trace_id_ratio_based:
            ratio: 0.2  # 20% of root traces
    ```

  </Collapser>
</CollapserGroup>

````

**sampler.remote_parent_sampled**

| Type    | String or nested property |
| ------- | ------------------------- |
| Default | `adaptive`                |

Configures the sampler used for the [remote parent sampled context](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#remote-parent-sampled-context). The possible values are:

-   `adaptive`: Use New Relic's default [Adaptive Sampler](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#adaptive-sampler).
    -   Optional parameter: [`sampler.remote_parent_sampled.adaptive.sampling_target`](#dt-sampler-remote-parent-sampled-adaptive-sampling_target)
-   `trace_id_ratio_based`: Sample a fixed percentage of traces [based on trace ID](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#trace-id-ratio-based-sampler)
    -   Required parameter: [`sampler.remote_parent_sampled.trace_id_ratio_based.ratio`](#dt-sampler-remote-parent-sampled-trace_id_ratio_based-ratio)
-   `always_on`: Sample all `remote_parent_sampled` traces.
-   `always_off`: Sample no `remote_parent_sampled` traces.

````yaml
distributed_tracing:
  sampler:
    remote_parent_sampled: always_on
```

<CollapserGroup>
  <Collapser
    id="dt-sampler-remote-parent-sampled-adaptive-sampling_target"
    title="remote_parent_sampled.adaptive.sampling_target"
  >
    <table>
      <tbody>
        <tr>
          <th>
            Type
          </th>

          <td>
            Integer, between 1 (inclusive) and 120 (inclusive)
          </td>
        </tr>

        <tr>
          <th>
            Default
          </th>

          <td>
            [`sampler.adaptive_sampling_target`](#dt-sampler-adaptive_sampling_target)
          </td>
        </tr>

        <tr>
          <th>
            Required
          </th>

          <td>
            No
          </td>
        </tr>
      </tbody>
    </table>

    Overrides the global [`adaptive_sampling_target`](#dt-sampler-adaptive_sampling_target) for the `remote_parent_sampled` context only.

    Since the Adaptive Sampler usually samples upstream-sampled traces (and does not count these towards the sampling target),
    this setting generally has no effect. To sample only some `remote_parent_sampled` traces, prefer the `trace_id_ratio_based` sampler.

  </Collapser>

  <Collapser
    id="dt-sampler-remote-parent-sampled-trace_id_ratio_based-ratio"
    title="remote_parent_sampled.trace_id_ratio_based.ratio"
  >
    <table>
      <tbody>
        <tr>
          <th>
            Type
          </th>

          <td>
            Float, between 0.0 (exclusive) and 1.0 (inclusive)
          </td>
        </tr>

        <tr>
          <th>
            Default
          </th>

          <td>
            None
          </td>
        </tr>

        <tr>
          <th>
            Required
          </th>

          <td>
            Yes
          </td>
        </tr>
      </tbody>
    </table>

    Specifies the percentage of upstream-sampled traces to capture, based on trace ID. See [Configure sampling: Trace ID ratio based sampler](/docs/apm/distributed-tracing/distributed-trace-sampling#trace-id-ratio-based-sampler).

    <Callout variant="important">
      The `ratio` property is required when using the `trace_id_ratio_based` sampler. If a ratio is not set, the default
      Adaptive Sampler will be used for this context instead.
    </Callout>

    ```yaml
    distributed_tracing:
      sampler:
        remote_parent_sampled:
          trace_id_ratio_based:
            ratio: 0.2  # Sample 20% of traces sampled by upstream
    ```

  </Collapser>
</CollapserGroup>

````

**sampler.remote_parent_not_sampled**

| Type    | String or nested property |
| ------- | ------------------------- |
| Default | `adaptive`                |

Configures the sampler used for the [remote parent not sampled context](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#remote-parent-not-sampled-context) (an upstream service decided NOT to sample this trace). The possible values are:

-   `adaptive`: Use New Relic's default [Adaptive Sampler](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#adaptive-sampler).
    -   Optional parameter: [`sampler.remote_parent_not_sampled.adaptive.sampling_target`](#dt-sampler-remote-parent-not-sampled-adaptive-sampling_target)
-   `trace_id_ratio_based`: Sample a fixed percentage of traces [based on trace ID](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling#trace-id-ratio-based-sampler)
    -   Required parameter: [`sampler.remote_parent_not_sampled.trace_id_ratio_based.ratio`](#dt-sampler-remote-parent-not-sampled-trace_id_ratio_based-ratio)
-   `always_on`: Sample all `remote_parent_not_sampled` traces.
-   `always_off`: Sample no `remote_parent_not_sampled` traces.

````yaml
distributed_tracing:
  sampler:
    remote_parent_not_sampled: always_off
```

<CollapserGroup>
  <Collapser
    id="dt-sampler-remote-parent-not-sampled-adaptive-sampling_target"
    title="remote_parent_not_sampled.adaptive.sampling_target"
  >
    <table>
      <tbody>
        <tr>
          <th>
            Type
          </th>

          <td>
            Integer, between 1 (inclusive) and 120 (inclusive)
          </td>
        </tr>

        <tr>
          <th>
            Default
          </th>

          <td>
            [`sampler.adaptive_sampling_target`](#dt-sampler-adaptive_sampling_target)
          </td>
        </tr>

        <tr>
          <th>
            Required
          </th>

          <td>
            No
          </td>
        </tr>
      </tbody>
    </table>

    Overrides the global [`adaptive_sampling_target`](#dt-sampler-adaptive_sampling_target) for the `remote_parent_not_sampled` context only.

    Since the Adaptive Sampler usually does not sample traces that were not sampled by an upstream service, this setting
    generally has no effect. To guarantee capture of some `remote_parent_not_sampled` traces, prefer the `trace_id_ratio_based` sampler.

  </Collapser>

  <Collapser
    id="dt-sampler-remote-parent-not-sampled-trace_id_ratio_based-ratio"
    title="remote_parent_not_sampled.trace_id_ratio_based.ratio"
  >
    <table>
      <tbody>
        <tr>
          <th>
            Type
          </th>

          <td>
            Float, between 0.0 (exclusive) and 1.0 (inclusive)
          </td>
        </tr>

        <tr>
          <th>
            Default
          </th>

          <td>
            None
          </td>
        </tr>

        <tr>
          <th>
            Required
          </th>

          <td>
            Yes
          </td>
        </tr>
      </tbody>
    </table>

    Specifies the percentage of traces to capture, based on trace ID. See [Configure sampling: Trace ID ratio based sampler](/docs/apm/distributed-tracing/distributed-trace-sampling#trace-id-ratio-based-sampler).

    <Callout variant="important">
      The `ratio` property is required when using the `trace_id_ratio_based` sampler. If a ratio is not set, the default
      Adaptive Sampler will be used for this context instead.
    </Callout>

    ```yaml
    distributed_tracing:
      sampler:
        remote_parent_not_sampled:
          trace_id_ratio_based:
            ratio: 0.05  # Sample 5% even if upstream said not to
    ```

    <Callout variant="caution">
      Overriding upstream "not sampled" decisions can create fragmented traces where only some services are present. Use this pattern only when you have a specific need to see activity in a downstream service even when upstream didn't sample it.
    </Callout>
  </Collapser>
</CollapserGroup>

````

For a deep dive into how these samplers work, adaptive sampling targets, and sampling contexts, see [Configure sampling](https://docs.newrelic.com/docs/apm/distributed-tracing/distributed-trace-sampling). For real-world configuration scenarios, see [Sampler configuration examples](https://docs.newrelic.com/docs/apm/distributed-tracing/sampler-configuration-examples).

## Infinite Tracing

> #### ⚠️ IMPORTANT
>
> Requirements:
>
> -   [Java agent 5.12.1 or higher](https://docs.newrelic.com/docs/agents/java-agent/installation/update-java-agent).
> -   Infinite Tracing does not work if `enable_auto_app_naming` is enabled.

To turn on Infinite Tracing, enable distributed tracing and add the additional setting below. For an example, see [Language agents: Configure distributed tracing](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/enable-configure/language-agents-enable-distributed-tracing#java-config).

**trace_observer.host**

| Type    | String |
| ------- | ------ |
| Default | (none) |

For help getting a valid Infinite Tracing trace observer host entry, see [find or create a Trace Observer](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/enable-configure/language-agents-enable-distributed-tracing#provision-trace-observer).

You can configure this via YAML:

````yml
infinite_tracing:
  trace_observer:
    host: YOUR_TRACE_OBSERVER_HOST
```

You can also use the system property `newrelic.config.infinite_tracing.trace_observer.host` or the environment variable `NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_HOST`.

````

## Span events

[Span events](https://docs.newrelic.com/docs/apm/distributed-tracing/ui-data/span-event) are reported for [distributed tracing](#distributed-tracing). You must enable distributed tracing to report span events.

Set span events configuration in the `span_events` section. These settings can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.span_events` prefixed system property. Options include:

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Used to enable/disable span event reporting.

**max_samples_stored**

| Type    | Integer |
| ------- | ------- |
| Default | `2000`  |
| Max     | `10000` |

-   Determines the number of span events that can be captured during an agent harvest cycle. Available in Java agent 7.4.0 and above.
-   When configuring the agent for [AI monitoring](https://docs.newrelic.com/docs/ai-monitoring/intro-to-ai-monitoring), set to max value `10000`. Ensures that the maximum amount of traces are captured.

    > #### ⚠️ IMPORTANT
    >
    > Increasing the number of span events can lead to additional agent overhead.

**attributes.enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

This setting can be used to turn on or off all attributes for span events. If `attributes.enabled` at the root level is `false`, no attributes will be sent to span events regardless on how this property (`span_events.attributes.enabled`) is set.

**attributes.include**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

If attributes are enabled for span events, all attribute keys found in this list will be sent to New Relic in `span_events`. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

**attributes.exclude**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

All attribute keys found in this list will not be sent to New Relic in span events. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

> #### ⚠️ IMPORTANT
>
> Span event attribute filtering requires [Java agent version 4.10.0 or higher](https://docs.newrelic.com/docs/agents/java-agent/installation/upgrade-java-agent).

## Cross application tracer [#Cross_Application_Tracer]

> #### ⚠️ IMPORTANT
>
> Cross application tracing has been deprecated as of agent version 7.4.0 and will be removed in a future agent version.
>
> Instead of using cross application tracing, we recommend our [distributed tracing](#distributed-tracing) features. Distributed tracing is an improvement on the cross application tracing feature and is recommended for large, distributed systems.

Set the cross application tracing options in the `cross_application_tracer` section. These settings can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.cross_application_tracer` prefixed system property.

[Cross application tracing](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/cross-application-tracing) adds request and response headers to external calls using the Apache HttpClient libraries. This provides better performance data when calling applications monitored by other New Relic agents.

**enabled (DEPRECATED)**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

[Cross application tracing](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/cross-application-tracing) is enabled by default. Set this to false to turn it off.