From 881a3d262809e65449032a0d038f21460aa209e4 Mon Sep 17 00:00:00 2001 From: Marty Tippin <120425148+tippmar-nr@users.noreply.github.com> Date: Wed, 22 Oct 2025 14:14:39 -0500 Subject: [PATCH 1/6] wip - distributed trace sampler configuration update --- .../configuration/net-agent-configuration.mdx | 63 ++++++++++++++++++- 1 file changed, 61 insertions(+), 2 deletions(-) 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..0648778db7c 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,65 @@ The `distributedTracing` element supports the following attributes: +#### Sampler Configuration + +The .NET agent currently supports 4 different sampling algorithms that can be configured for use in distributed tracing: + +* **Adaptive Sampler** - this is 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** - this is 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 cost. +* **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: +* **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 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 that is not sampled. + +The sampler configuration element is a child of the `` element. + +```xml + + + + ... + + + ... + + + ... + + + +``` + +For each of the sampler levels, one of the following sampler configurations can be specified: +```xml + + + + +``` + +The `` element takes a `sampleRatio`, which is a value between 0.0 and 1.0 specifying the percentage of traces that should be sampled. + +By default, the Adaptive Sampler is used if there is no other configuration specified at a particular sampler level. + +The following environment variables can also be used to configure the distributed trace sampler, 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: +``` +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: From 0d38b829cdbf9dfff1f2a793232571d9556d8fa7 Mon Sep 17 00:00:00 2001 From: Marty Tippin <120425148+tippmar-nr@users.noreply.github.com> Date: Thu, 23 Oct 2025 12:07:19 -0500 Subject: [PATCH 2/6] updates --- .../configuration/net-agent-configuration.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) 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 0648778db7c..909a90d267d 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 @@ -3297,23 +3297,26 @@ The sampler configuration element is a child of the `` eleme For each of the sampler levels, one of the following sampler configurations can be specified: ```xml + # default is a synonym for - + ``` -The `` element takes a `sampleRatio`, which is a value between 0.0 and 1.0 specifying the percentage of traces that should be sampled. +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. -By default, the Adaptive Sampler is used if there is no other configuration specified at a particular sampler level. + +By default, the **Adaptive Sampler** is used if there is no other configuration specified at a particular sampler level. + -The following environment variables can also be used to configure the distributed trace sampler, specifying one of the possible values for the sampler type: +The following environment variables can also 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: +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 From f624a71e9db67ccd11ec013ad96a6f495246f478 Mon Sep 17 00:00:00 2001 From: Marty Tippin <120425148+tippmar-nr@users.noreply.github.com> Date: Thu, 23 Oct 2025 12:29:52 -0500 Subject: [PATCH 3/6] Add callout for minimum .NET agent version for sampler configuration --- .../net-agent/configuration/net-agent-configuration.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) 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 909a90d267d..c6212ae36b0 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 @@ -3263,7 +3263,11 @@ The `distributedTracing` element supports the following attributes: -#### Sampler Configuration +#### Sampler Configuration + + -By default, the **Adaptive Sampler** is used if there is no other configuration specified at a particular sampler level. +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 also be used to configure the distributed trace sampler at the various sampler levels, specifying one of the possible values for the sampler type: +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 From d4bcd0c889367bd73dc87a56431e9c76444737d4 Mon Sep 17 00:00:00 2001 From: WriteMayur Date: Fri, 24 Oct 2025 20:04:59 +0530 Subject: [PATCH 5/6] fix the syntax error --- .../configuration/net-agent-configuration.mdx | 39 ++++++++++--------- 1 file changed, 20 insertions(+), 19 deletions(-) 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 fe99fc25fb2..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 @@ -3265,7 +3265,7 @@ The `distributedTracing` element supports the following attributes: #### Sampler Configuration - Sampler configuration is available starting with .NET agent version 10.45.0 @@ -3374,28 +3374,29 @@ The supported samplers can be configured at multiple levels: 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 - - - - + # 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. From 8a709c9e7e3a6bb70d9914473598c0fd0a5b65af Mon Sep 17 00:00:00 2001 From: WriteMayur Date: Fri, 24 Oct 2025 21:08:35 +0530 Subject: [PATCH 6/6] Update net-agent-configuration.mdx --- .../agents/net-agent/configuration/net-agent-configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 ca4dc9d6ba6..3555fe7872a 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 @@ -3266,7 +3266,7 @@ The `distributedTracing` element supports the following attributes: #### Sampler Configuration -Sampler configuration is available starting with .NET agent version 10.45.0 +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: