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.
The Node.js agent variables that control cross application tracing 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 and will be removed in a future agent version.
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, which is enabled by default as of agent version 8.3.0. Before enabling, read the transition guide.
Distributed tracing
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.
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:
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:
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):
For example, to enable this in the config file, you would use:
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 and substitute remote_parent_sampled for root.
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 does not apply (that is, the traceparent sampled flag is 00).
For example, to enable this in the config file, you would use:
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 and substitute remote_parent_not_sampled for root.
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:
distributed_tracing:{
enabled:true,
sampler:{
adaptive_sampling_target:20
}
}
gRPC server instrumentation
The grpc section controls the behavior of how the gRPC server is instrumented.
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.
Span data is reported for distributed tracing. Distributed tracing must be enabled to report spans. Set span configuration in the span_events section. Options include:
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.
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.
To turn on Infinite Tracing, add the settings below. Set Infinite Tracing configuration in the infinite_tracing section.
Additionally, distributed tracing must be enabled. Note that distributed tracing is enabled by default for Node.js APM agent versions 8.3.0 and greater.
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.