---
title: Node.js agent distributed tracing settings
source: https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration-distributed-tracing-settings
---

This page covers the Node.js agent settings for distributed tracing, including W3C trace context headers, sampling controls, span events, Infinite Tracing, and gRPC server instrumentation.

> #### 💡 TIP
>
> Back to the full settings index: [Node.js agent configuration](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration)

## Cross application tracing (DEPRECATED) [#cross-app-tracing]

The Node.js agent variables that control [cross application tracing](https://docs.newrelic.com/docs/apm/transactions/cross-application-traces/introduction-cross-application-traces) typically appear in the `cross_application_tracer` section of your app's `newrelic.js` configuration file:

> #### ⚠️ IMPORTANT
>
> Cross application tracing has been deprecated in favor of [Distributed tracing](https://docs.newrelic.com/docs/enable-distributed-tracing) and will be removed in a future agent version.

**enabled**

| Type                             | Boolean                                      |
| -------------------------------- | -------------------------------------------- |
| Default                          | `false`                                      |
| [Environ variable](#environment) | `NEW_RELIC_CROSS_APPLICATION_TRACER_ENABLED` |

When set to `true`, allows tracing of transactions across more than one New Relic-monitored applications.

> #### ⚠️ IMPORTANT
>
> Cross application tracing (CAT) has been deprecated and will be removed in a future major release. For cross-service visibility, we recommend using [distributed tracing](#distributed-tracing), which is enabled by default as of agent version 8.3.0. Before enabling, read the [transition guide](https://docs.newrelic.com/docs/transition-guide-distributed-tracing).

## Distributed tracing [#dt-main]

[Distributed tracing](https://docs.newrelic.com/docs/intro-distributed-tracing) lets you see the path that a request takes as it travels through a distributed system. When configuring via the config file, place the following option in the `distributed_tracing` section. It is turned on by default in Node.js agents 8.3.0 and higher.

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

For more information about setting up distributed tracing, see [Enable distributed tracing for your Node.js  applications](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/distributed-tracing-nodejs-agent).

**enabled**

| Type                             | Boolean                                 |
| -------------------------------- | --------------------------------------- |
| Default                          | `true`                                  |
| [Environ variable](#environment) | `NEW_RELIC_DISTRIBUTED_TRACING_ENABLED` |

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

````js
distributed_tracing: {
  enabled: false
}
```

````

**exclude_newrelic_header**

| Type                             | Boolean                                                 |
| -------------------------------- | ------------------------------------------------------- |
| Default                          | `false`                                                 |
| [Environ variable](#environment) | `NEW_RELIC_DISTRIBUTED_TRACING_EXCLUDE_NEWRELIC_HEADER` |

Set this to `true` to exclude the New Relic header that is attached to outbound requests, and instead only rely on W3C Trace Context Headers for distributed tracing. If this is `false` then both types of headers are used.

For example, to enable this in the config file, you would use:

````js
distributed_tracing: {
  enabled: true,
  exclude_newrelic_header: true
}
```

````

**sampler.root**

| Type                             | String or object                             |
| -------------------------------- | -------------------------------------------- |
| Default                          | `adaptive`                                   |
| [Environ variable](#environment) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT` |

Controls how sampling decisions are made for root spans-transactions that don't have a remote parent (meaning they lack an incoming `traceparent` or `newrelic` distributed tracing header). Valid values are:

-   `adaptive` (default): Uses the built-in New Relic adaptive sampling algorithm.
-   `always_on`: Samples all spans.
-   `always_off`: Doesn't sample any spans.
-   `trace_id_ratio_based`: Samples a fixed ratio of traces, determined deterministically by the trace ID.

    For example, to set this in the config file, you would use:

    ```js
    distributed_tracing: {
      enabled: true,
      sampler: {
        root: 'always_on'
      }
    }
    ```

    When set to `trace_id_ratio_based`, you must also provide a `ratio` (a number between `0` and `1`):

    ```js
    distributed_tracing: {
      enabled: true,
      sampler: {
        root: {
          trace_id_ratio_based: {
            ratio: 0.5
          }
        }
      }
    }
    ```

    Or via environment variables:

    ```ini
    NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT=trace_id_ratio_based
    NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT_TRACE_ID_RATIO_BASED_RATIO=0.5
    ```

    When you set this to `adaptive`, you can optionally override the sampling target (to 1–120 transactions/minute) specifically for this sampler:

    ```js
    distributed_tracing: {
      enabled: true,
      sampler: {
        root: {
          adaptive: {
            sampling_target: 50
          }
        }
      }
    }
    ```

    Or via environment variables:

    ```ini
    NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT=adaptive
    NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT_ADAPTIVE_SAMPLING_TARGET=50
    ```

**sampler.remote_parent_sampled**

| Type                             | String or object                                              |
| -------------------------------- | ------------------------------------------------------------- |
| Default                          | `adaptive`                                                    |
| [Environ variable](#environment) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_SAMPLED` |

When the traceparent header has a sampled flag of `01`, this controls how to handle sampling of spans. The allowable string values are:

-   `adaptive` (default): Uses the built-in New Relic adaptive sampling algorithm.
-   `always_on`: Samples all spans.
-   `always_off`: Doesn't sample any spans.
-   `trace_id_ratio_based`: Samples a fixed ratio of traces, determined deterministically by the trace ID.

    This setting takes precedence over [`remote_parent_not_sampled`](#dt-sampler-remote-parent-not-sampled) when both could apply.

    For example, to enable this in the config file, you would use:

    ```js
    distributed_tracing: {
      enabled: true,
      sampler: {
        remote_parent_sampled: 'always_on'
      }
    }
    ```

    When you set this to `trace_id_ratio_based`, you must provide a `ratio` value of `0`–`1`. When you set this to `adaptive`, you can optionally override the sampling target specifically for this sampler. For the equivalent syntax, see the object-form and environment variable examples under [`sampler.root`](#dt-sampler-root) and substitute `remote_parent_sampled` for `root`.

**sampler.remote_parent_not_sampled**

| Type                             | String or object                                                  |
| -------------------------------- | ----------------------------------------------------------------- |
| Default                          | `adaptive`                                                        |
| [Environ variable](#environment) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_NOT_SAMPLED` |

When the traceparent header has a sampled flag of `00`, this controls how to handle sampling of spans. The allowable string values are:

-   `adaptive` (default): Uses the built-in New Relic adaptive sampling algorithm.
-   `always_on`: Samples all spans.
-   `always_off`: Doesn't sample any spans.
-   `trace_id_ratio_based`: Samples a fixed ratio of traces, determined deterministically by the trace ID.

    This setting only takes effect when [`remote_parent_sampled`](#dt-sampler-remote-parent-sampled) does not apply (that is, the traceparent sampled flag is `00`).

    For example, to enable this in the config file, you would use:

    ```js
    distributed_tracing: {
      enabled: true,
      sampler: {
        remote_parent_not_sampled: 'always_on'
      }
    }
    ```

    When you set this to `trace_id_ratio_based`, you must provide a `ratio` value of `0`–`1`. When you set this to `adaptive`, you can optionally override the sampling target specifically for this sampler.  For the equivalent syntax, see the object-form and environment variable examples under [`sampler.root`](#dt-sampler-root) and substitute `remote_parent_not_sampled` for `root`.

**sampler.adaptive_sampling_target**

| Type                             | Integer                                                          |
| -------------------------------- | ---------------------------------------------------------------- |
| Default                          | `10`                                                             |
| [Environ variable](#environment) | `NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ADAPTIVE_SAMPLING_TARGET` |

The sampling target for adaptive sampling, in transactions per minute, used when configuring the default/adaptive sampler. Must be within the range `[1, 120]` (inclusive). Upon connecting to New Relic, this value is sent to the collector, and the `sampling_target` value returned in the connect response is used as the effective sampling target for adaptive sampling in the agent.

For example, to set this in the config file, you would use:

````js
distributed_tracing: {
  enabled: true,
  sampler: {
    adaptive_sampling_target: 20
  }
}
```

````

## gRPC server instrumentation [#grpc_server]

The `grpc` section controls the behavior of how the gRPC server is instrumented.

**record_errors**

| Type                             | Boolean                        |
| -------------------------------- | ------------------------------ |
| Default                          | `true`                         |
| [Environ variable](#environment) | `NEW_RELIC_GRPC_RECORD_ERRORS` |

When enabled, the agent will send all error gRPC status codes to New Relic, that is, nonzero status codes. If disabled, the server instrumentation will not send any nonzero status codes to New Relic.

**ignore_status_codes**

| Type                             | Array of Integers                    |
| -------------------------------- | ------------------------------------ |
| Default                          | `[]`                                 |
| [Environ variable](#environment) | `NEW_RELIC_GRPC_IGNORE_STATUS_CODES` |

Comma-delimited list of gRPC status codes for the error collector to ignore, both on client-side and server-side instrumentation.

> #### ⚠️ CAUTION
>
> Errors recorded using [`newrelic.noticeError()`](https://newrelic.github.io/node-newrelic/API.html#noticeError) do not obey this configuration value.

## Span events

[Span data](https://docs.newrelic.com/docs/apm/distributed-tracing/ui-data/span-event) is reported for [distributed tracing](#distributed-tracing). Distributed tracing must be enabled to report spans. Set span configuration in the `span_events` section. Options include:

**enabled**

| Type                             | Boolean                         |
| -------------------------------- | ------------------------------- |
| Default                          | `true`                          |
| [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ENABLED` |

Turns reporting of span events on or off.

**attributes.enabled**

| Type                             | Boolean                                    |
| -------------------------------- | ------------------------------------------ |
| Default                          | `true`                                     |
| [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_ENABLED` |

This setting can be used to turn reporting of attributes on or off for spans. If `attributes.enabled` at the root level is `false`, no attributes will be sent with spans regardless on how this is set.

**attributes.include**

| Type                             | Array                                      |
| -------------------------------- | ------------------------------------------ |
| Default                          | `[]`                                       |
| [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_INCLUDE` |

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

**attributes.exclude**

| Type                             | Array                                      |
| -------------------------------- | ------------------------------------------ |
| Default                          | `[]`                                       |
| [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_ATTRIBUTES_EXCLUDE` |

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

**max_samples_stored**

| Type                             | Integer                                    |
| -------------------------------- | ------------------------------------------ |
| Default                          | `2000`                                     |
| [Environ variable](#environment) | `NEW_RELIC_SPAN_EVENTS_MAX_SAMPLES_STORED` |

-   Defines the maximum number of events the agent collects per minute. If there are more than this number, the agent collects a statistical sampling.
-   We do not recommend configuring past 10k. The server will cap data at 10k per-minute.
-   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
    >
    > `max_samples_stored` configuration settings require [Node.JS agent version 8.3.0 or higher](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/update-nodejs-agent/).

## Infinite Tracing

To turn on Infinite Tracing, add the settings below. Set Infinite Tracing configuration in the `infinite_tracing` section.
Additionally, distributed tracing must be [enabled](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/distributed-tracing-nodejs-agent). Note that distributed tracing is enabled by default for Node.js APM agent versions 8.3.0 and greater.

**trace_observer.host**

| Type                             | String                                           |
| -------------------------------- | ------------------------------------------------ |
| Default                          | (none)                                           |
| [Environ variable](#environment) | `NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_HOST` |

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

**span_events.queue_size**

| Type                             | Number                                              |
| -------------------------------- | --------------------------------------------------- |
| Default                          | `10000`                                             |
| [Environ variable](#environment) | `NEW_RELIC_INFINITE_TRACING_SPAN_EVENTS_QUEUE_SIZE` |

The amount of Infinite Tracing spans the agent will hold in memory before dropping them.

This setting should rarely need to changed from the default as the queue is not in use the majority of the time. The queue is in use only during reconnections to the Infinite Tracing endpoint while the agent is unable to stream data. It's possible the agent will drop Infinite Tracing spans during these periods, in that case increasing this number can help.

**batching**

| Type                             | Boolean                               |
| -------------------------------- | ------------------------------------- |
| Default                          | `true`                                |
| [Environ variable](#environment) | `NEW_RELIC_INFINITE_TRACING_BATCHING` |

This setting sends spans in batches of 250 or every 5 seconds.

This setting should not be changed as the amount of egress will increase significantly.

**compression**

| Type                             | Boolean                                  |
| -------------------------------- | ---------------------------------------- |
| Default                          | `true`                                   |
| [Environ variable](#environment) | `NEW_RELIC_INFINITE_TRACING_COMPRESSION` |

This setting gzip compresses span(s).

This setting should not be changed as the amount of egress will increase significantly.