Configuring additional features for .NET monitoring

Configuring Kafka trace correlation headers

To configure the format for Kafka trace correlation headers, set the INSTANA_KAFKA_HEADER_FORMAT environment variable to binary, string, or both. Do not disable Kafka trace correlation entirely with INSTANA_KAFKA_TRACE_CORRELATION=false.

Another alternative is to configure the Kafka trace correlation options at the level of the Instana host agent.

For more information, see Kafka Header Migration.

Ignoring processes

To ignore monitoring of certain processes in Windows, complete the following steps:

Add the INSTANA_REWRITER_BACKOFF environment variable on the host level.
Set its value to a list of pool names or process names that is separated by semicolons as shown in the following example:
```
INSTANA_REWRITER_BACKOFF=my_pool_1;process_1;my_pool_2
```
Restart the IIS services with the iisreset command so that IIS can load a new environment.

Whitelisting processes

You can configure Instana to trace only specific processes by using the whitelist feature. When the whitelist is configured, only processes that match the specified patterns are instrumented for tracing. All other processes are excluded.

The whitelist feature uses case-insensitive regular expressions and supports semicolon-separated values, enabling you to define multiple patterns for flexible process matching.

To enable whitelisting for specific processes, complete the following steps:

Add the INSTANA_NET_WHITELIST environment variable on the host level.
Set its value to a semicolon-separated list of process names or regex patterns as shown in the following example:
```
INSTANA_NET_WHITELIST="^(weBapi|cORe).*;customerService;myApp.dll"
```
where:
- ^(weBapi|cORe).* matches processes starting with webapi or core (case-insensitive). This pattern uses regex anchors and wildcards to match multiple related applications.
- customerService performs a case-insensitive match against process file names that start with customerService. For example, it matches CustomerService.dll or customerServiceAPI.dll.
- myApp.dll matches the specific application with full file name and file extension.
Restart the application so that the environment variable takes effect.

When the whitelist is configured, the profiler checks each process against the whitelist patterns during initialization. Only processes that match at least one pattern are instrumented. If no match is found, the profiler exits without attaching to the process.

The whitelist feature is particularly useful in environments where you want to:

Reduce overhead by tracing only critical applications
Isolate specific services for monitoring
Exclude nonproduction or test processes from tracing

Note:

If the INSTANA_NET_WHITELIST environment variable is not set or is empty, all processes are eligible for tracing (subject to any blacklist rules configured with INSTANA_REWRITER_BACKOFF).

Configuring span filtering

You can use the span filtering feature to control which spans are collected and sent to Instana, helping you reduce data volume and focus on the most relevant traces. The .NET sensor supports flexible span filtering through multiple configuration methods.

For details, see Span Filtering.

Enabling AutoProfile

For .NET users, AutoProfile is available for .NET applications that run on both Linux and Windows.

Enabling AutoProfile on Linux

To enable AutoProfile, add the following settings to your agent's configuration.yml file:

com.instana.plugin.netcore:
  profiling:
    enabled: true

You can also enable AutoProfile by setting the environment variable INSTANA_AUTO_PROFILE to true.

Enabling AutoProfile on Windows

To enable AutoProfile, complete the following steps:

Add the following settings to your agent's configuration.yml file:
```
com.instana.plugin.netcore:
  profiling:
    enabled: true
```
Set the environment variable INSTANA_AUTO_PROFILE to true.

For more information, see Analyze Profiles.

Adding custom tracing with the .NET SDK

You can optionally use the Instana .NET Tracing SDK to add custom spans to your application code.

To use custom tracing in addition to the standard Instana instrumentation, add the Instana.Tracing.Core.Sdk NuGet package to your application.

For more information about adding distributed tracing capabilities to your code, see .NET or .NET Core Tracing SDK.

Configuring event-driven instrumentation

Instana supports event-driven instrumentation, which captures telemetry data by listening to events emitted by instrumented libraries in the .NET environment. Instead of rewriting Intermediate Language (IL) code at runtime, the Instana .NET Tracer subscribes to these events and converts them into distributed traces.

Requirements

.NET 6.0 or later, OR .NET Core 3.1 or later with DiagnosticSource 6.0+ package
Instana .NET Sensor 1.0.96 or later

Enabling or disabling event-driven tracing

By default, event-driven instrumentation is disabled. You can explicitly enable it by setting the following environment variable:

# Enable event-driven tracing (disabled by default)
INSTANA_ENABLE_EVENT_TRACING=true

Filtering ActivitySource events

You can control which ActivitySource events to exclude or include by configuring the environment variables as shown in the following examples:

Blacklist specific sources:

# Exclude specific ActivitySource names (comma-separated)
INSTANA_DOTNET_BLACKLISTED_ACTIVITYSOURCES="MyApp.Internal,ThirdParty.Debug"

Whitelist specific sources that are already blacklisted by default:

# Include only specific ActivitySource names (comma-separated)
INSTANA_DOTNET_WHITELISTED_ACTIVITYSOURCES="MyApp.Api,MyApp.Services"

To avoid duplicate instrumentation and unnecessary noise, Instana blacklists the following ActivitySource patterns by default:

Table 1. ActivitySource patterns
System.Net internal activities	System threading	ASP.NET Core internal hosting	Other activities
`System.Net.Sockets` `System.Net.Security` `System.Net.Quic` `System.Net.NetworkInformation` `System.Net.Mail` `System.Net.Experimental.*`	`System.Threading.*`	`Microsoft.Extensions.` `Microsoft.AspNetCore.Experimental.` `Microsoft.AspNetCore.Hosting` `Microsoft.AspNetCore.Server.Kestrel.Transport.Sockets` `Microsoft.AspNetCore.Server.Kestrel.Connections` `Microsoft.AspNetCore.Routing.EndpointMiddleware`	`Experimental.*`