Skip to content

docs(dotnet): Update distributed trace sampler configuration #21981

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

docs(dotnet): Update distributed trace sampler configuration #21981

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
881a3d2
wip - distributed trace sampler configuration update
tippmar-nr Oct 22, 2025
0d38b82
updates
tippmar-nr Oct 23, 2025
f624a71
Add callout for minimum .NET agent version for sampler configuration
tippmar-nr Oct 23, 2025
d8ce756
Convert sampler type and sampler level descriptions to tables for cla…
tippmar-nr Oct 23, 2025
d4bcd0c
fix the syntax error
WriteMayur Oct 24, 2025
8a709c9
Update net-agent-configuration.mdx
WriteMayur Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 159 additions & 2 deletions src/content/docs/apm/agents/net-agent/configuration/net-agent-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3179,11 +3179,11 @@ The `datastoreTracer` element supports the following sub-elements:
The `distributedTracing` element is a child of the `configuration` element.

```xml
<distributedTracing enabled="false"
<distributedTracing enabled="true"
excludeNewrelicHeader="false"/>
```

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.

<Callout variant="important">
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).
Expand Down Expand Up @@ -3263,6 +3263,163 @@ The `distributedTracing` element supports the following attributes:
</Collapser>
</CollapserGroup>

#### Sampler Configuration

<Callout variant="important">
Sampler configuration is available starting with .NET agent version 10.45.0.
</Callout>

The .NET agent currently supports 4 different sampling algorithms that can be configured for use in distributed tracing:

<table>
<thead>
<tr>
<th>
<DNT>
**Sampler Type**
</DNT>
</th>

<th>
<DNT>
**Description**
</DNT>
</th>
</tr>
</thead>

<tbody>
<tr>
<td>
Adaptive Sampler
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
Trace Id Ratio Based Sampler
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
Always On Sampler
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
Always Off Sampler
</td>
<td>
The opposite of Always On; this sampler does not sample any traces. Useful in very specfic cases.
</td>
</tr>
</tbody>
</table>

The supported samplers can be configured at multiple levels:

<table>
<thead>
<tr>
<th>
<DNT>
**Sampler Level**
</DNT>
</th>

<th>
<DNT>
**Description**
</DNT>
</th>
</tr>
</thead>

<tbody>
<tr>
<td>
Root
</td>
<td>
This is the sampler that is applied at the beginning of a trace. By default, the Adaptive Sampler is configured as the Root sampler.
</td>
</tr>
<tr>
<td>
Remote Parent Sampled
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
Remote Parent Not Sampled
</td>
<td>
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.
</td>
</tr>
</tbody>
</table>

The `<sampler>` configuration element is a child of the `<distributedTracing>` element and is structured as follows:

```xml
<distributedTracing ... >
<sampler>
<root>
...
</root>
<remoteParentSampled>
...
</remoteParentSampled>
<remoteParentNotSampled>
...
</remoteParentNotSampled>
</sampler>
</distributedTracing>
```

For each of the sampler levels, one of the following sampler configurations can be specified:

```xml
<default /> # default is a synonym for <adaptive />
<adaptive />
<traceIdRatioBased ratio="0.12" />
<alwaysOn />
<alwaysOff />
```

The `<traceIdRatioBased>` 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.

<Callout variant="important">
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.
</Callout>

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:

<CollapserGroup>
Expand Down
Loading