diff --git a/src/content/docs/apm/agents/net-agent/configuration/net-agent-configuration.mdx b/src/content/docs/apm/agents/net-agent/configuration/net-agent-configuration.mdx index 021f57d56bf..ca4dc9d6ba6 100644 --- a/src/content/docs/apm/agents/net-agent/configuration/net-agent-configuration.mdx +++ b/src/content/docs/apm/agents/net-agent/configuration/net-agent-configuration.mdx @@ -3179,11 +3179,11 @@ The `datastoreTracer` element supports the following sub-elements: The `distributedTracing` element is a child of the `configuration` element. ```xml - ``` -Distributed tracing lets you see the path that a request takes as it travels through a distributed system. It requires [.NET agent version 8.6.45.0 or higher](/docs/agents/net-agent/installation/update-net-agent) and is on by default in .NET agents 9.0.0.0 and higher. +Distributed tracing lets you see the path that a request takes as it travels through a distributed system. It requires [.NET agent version 8.6.45.0 or higher](/docs/agents/net-agent/installation/update-net-agent) and is enabled by default in .NET agents 9.0.0.0 and higher. Enabling [distributed tracing](/docs/understand-dependencies/distributed-tracing/get-started/introduction-distributed-tracing) disables [cross application tracing](#cross_application_tracer), and has other effects on APM features. Before enabling, read the [planning guide](/docs/transition-guide-distributed-tracing). @@ -3263,6 +3263,163 @@ The `distributedTracing` element supports the following attributes: +#### Sampler Configuration + + +Sampler configuration is available starting with .NET agent version 10.45.0 + + +The .NET agent currently supports 4 different sampling algorithms that can be configured for use in distributed tracing: + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + **Sampler Type** + + + + **Description** + +
+ Adaptive Sampler + + The original sampling algorithm used by the .NET agent and is enabled by default. Sampling decisions are made at random, with the goal of retaining a configured number of samples per sampling period. +
+ Trace Id Ratio Based Sampler + + An implementation of the Open Telemetry Trace Id Ratio Based Sampler which samples a configured percentage of traces based on the (randomly generated) Trace Id. +
+ Always On Sampler + + As the name implies, this sampler wil sample every trace. Note that enabling this sampler can have an impact on application performance and will result in increased data ingest. +
+ Always Off Sampler + + The opposite of Always On; this sampler does not sample any traces. Useful in very specfic cases. +
+ +The supported samplers can be configured at multiple levels: + + + + + + + + + + + + + + + + + + + + + + + + +
+ + **Sampler Level** + + + + **Description** + +
+ Root + + This is the sampler that is applied at the beginning of a trace. By default, the Adaptive Sampler is configured as the Root sampler. +
+ Remote Parent Sampled + + This is the sampler that is applied when the trace has a remote parent (i.e., the trace originated in an upstream service) that has been sampled. It can be configured to use, for example, the Always On sampler to ensure that all traces in the current application are sampled. +
+ Remote Parent Not Sampled + + This is the sampler that is applied when a trace has a remote parent (i.e., the trace originated in an upstream service) that was NOT sampled. +
+ +The `` configuration element is a child of the `` element and is structured as follows: + +```xml + + + + ... + + + ... + + + ... + + + +``` + +For each of the sampler levels, one of the following sampler configurations can be specified: + +```xml + # default is a synonym for + + + + +``` + +The `` element has a required `ratio` attribute, which is a value between 0.0 and 1.0 specifying the percentage of traces that should be sampled. + + +The **Adaptive Sampler** will be used if there is no configuration specified at a particular sampler level or if the configuration element for that level is not specified at all. + + +The following environment variables can be used to configure the distributed trace sampler at the various sampler levels, specifying one of the possible values for the sampler type: +``` +NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT= default | adaptive | traceIdRatioBased | alwaysOn | alwaysOff +NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_SAMPLED = default | adaptive | traceIdRatioBased | alwaysOn | alwaysOff +NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_NOT_SAMPLED = default | adaptive | traceIdRatioBased | alwaysOn | alwaysOff +``` +If `traceIdRatioBased` is specified as the value of one these environment variables, a corresponding environment variable to specify the ratio is also required for the same sampler level: +``` +NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_ROOT_TRACE_ID_RATIO_BASED_RATIO=0.12 +NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_SAMPLED_TRACE_ID_RATIO_BASED_RATIO=0.12 +NEW_RELIC_DISTRIBUTED_TRACING_SAMPLER_REMOTE_PARENT_NOT_SAMPLED_TRACE_ID_RATIO_BASED_RATIO=0.12 +``` + +#### Span event reporting + Distributed tracing reports span events. Span event reporting is enabled by default, but [distributed tracing](/docs/apm/distributed-tracing/getting-started/introduction-distributed-tracing) must be enabled for spans to be reported. To disable span events, choose one of the following options: