Configuration and settings

Configuration methods

You can apply or edit configuration settings in the following ways, with environment variables taking precedence over App.config or Web.config file:

1. Environment variables

   Environment variables are the main way to configure the settings.

2. App.config or Web.config file

   For an application running on .NET Framework, you can use a web configuration file (web.config) or an application configuration file (app.config) to configure the OTEL_* settings.

   ⚠️ Only settings starting with OTEL_ can be set using App.config or Web.config. However, the following settings are not supported:

   • OTEL_DOTNET_AUTO_HOME
   • OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
   • OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_INSTRUMENTATIONS_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_{INSTRUMENTATION_ID}_INSTRUMENTATION_ENABLED
   • OTEL_DOTNET_AUTO_LOG_DIRECTORY
   • OTEL_LOG_LEVEL
   • OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED

   Example with OTEL_SERVICE_NAME setting:

   <configuration>
   <appSettings>
       <add key="OTEL_SERVICE_NAME" value="my-service-name" />
   </appSettings>
   </configuration>
   

3. Service name automatic detection

   If no service name is explicitly configured one will be generated for you. This can be helpful in some circumstances.

   • If the application is hosted on IIS in .NET Framework this will be SiteName\VirtualPath ex: MySite\MyApp
   • If that is not the case it will use the name of the application entry Assembly.

By default we recommend using environment variables for configuration. However, if given setting supports it, then:

• use Web.config for configuring an ASP.NET application (.NET Framework),
• use App.config for configuring a Windows Service (.NET Framework).

Global settings

[1] If OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED is set to true then processes excluded from instrumentation by OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES will fail instead of silently continue.

[2] Notice that applications launched via dotnet MyApp.dll have process name dotnet or dotnet.exe.

Resources

A resource is the immutable representation of the entity producing the telemetry. See Resource semantic conventions for more details.

Resource attributes

Resource detectors

The following resource detectors are included and enabled by default:

Propagators

Propagators allow applications to share context. See the OpenTelemetry specification for more details.

Samplers

Samplers let you control potential noise and overhead introduced by OpenTelemetry instrumentation by selecting which traces you want to collect and export. See the OpenTelemetry specification for more details.

[1]: Supported values are:

• always_on,
• always_off,
• traceidratio,
• parentbased_always_on,
• parentbased_always_off,
• parentbased_traceidratio.

[2]: For traceidratio and parentbased_traceidratio samplers: Sampling probability, a number in the [0..1] range, e.g. “0.25”. Default is 1.0.

Exporters

Exporters output the telemetry.

Traces exporter

Metrics exporter

Logs exporter

OTLP

Status: Stable

To enable the OTLP exporter, set the OTEL_TRACES_EXPORTER/OTEL_METRICS_EXPORTER/OTEL_LOGS_EXPORTER environment variable to otlp.

To customize the OTLP exporter using environment variables, see the OTLP exporter documentation. Important environment variables include:

[1]: Considerations on the OTEL_EXPORTER_OTLP_PROTOCOL:

• The OpenTelemetry .NET Automatic Instrumentation defaults to http/protobuf, which differs from the OpenTelemetry .NET SDK default value of grpc.
• On .NET 6 and higher, the application must reference Grpc.Net.Client to use the grpc OTLP exporter protocol. For example, by adding <PackageReference Include="Grpc.Net.Client" Version="2.65.0" /> to the .csproj file.
• On .NET Framework, the grpc OTLP exporter protocol is not supported.

[2]: The recognized (case-insensitive) values for OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE are:

• Cumulative: Choose cumulative aggregation temporality for all instrument kinds.
• Delta: Choose Delta aggregation temporality for Counter, Asynchronous Counter and Histogram instrument kinds, choose Cumulative aggregation for UpDownCounter and Asynchronous UpDownCounter instrument kinds.
• LowMemory: This configuration uses Delta aggregation temporality for Synchronous Counter and Histogram and uses Cumulative aggregation temporality for Synchronous UpDownCounter, Asynchronous Counter, and Asynchronous UpDownCounter instrument kinds.
  • ⚠️ This value known from specification is not supported.

Prometheus

Status: Experimental

To enable the Prometheus exporter, set the OTEL_METRICS_EXPORTER environment variable to prometheus.

The exporter exposes the metrics HTTP endpoint on http://localhost:9464/metrics and it caches the responses for 300 milliseconds.

See the Prometheus Exporter HttpListener documentation. to learn more.

Zipkin

Status: Stable

To enable the Zipkin exporter, set the OTEL_TRACES_EXPORTER environment variable to zipkin.

To customize the Zipkin exporter using environment variables, see the Zipkin exporter documentation. Important environment variables include:

Additional settings

RuleEngine

RuleEngine is a feature that validates OpenTelemetry API, SDK, Instrumentation, and Exporter assemblies for unsupported scenarios, ensuring that OpenTelemetry automatic instrumentation is more stable by backing of instead of crashing. It works on .NET 6 and higher.

Enable RuleEngine only during the first run of the application, or when the deployment changes or the Automatic Instrumentation library is upgraded. Once validated, there’s no need to revalidate the rules when the application restarts.

.NET CLR Profiler

The CLR uses the following environment variables to set up the profiler. See .NET Runtime Profiler Loading for more information.

Setting OpenTelemetry .NET Automatic Instrumentation as a .NET CLR Profiler is required for .NET Framework.

On .NET, the .NET CLR Profiler is used only for bytecode instrumentation. If having just source instrumentation is acceptable, you can unset or remove the following environment variables:

COR_ENABLE_PROFILING
COR_PROFILER
COR_PROFILER_PATH_32
COR_PROFILER_PATH_64
CORECLR_ENABLE_PROFILING
CORECLR_PROFILER
CORECLR_PROFILER_PATH
CORECLR_PROFILER_PATH_32
CORECLR_PROFILER_PATH_64

.NET Runtime

On .NET it is required to set the DOTNET_STARTUP_HOOKS environment variable.

The DOTNET_ADDITIONAL_DEPS and DOTNET_SHARED_STORE environment variable are used to mitigate assembly version conflicts in .NET.

Internal logs

The default directory paths for internal logs are:

• Windows: %ProgramData%\OpenTelemetry .NET AutoInstrumentation\logs
• Linux: /var/log/opentelemetry/dotnet
• macOS: /var/log/opentelemetry/dotnet

If the default log directories can’t be created, the instrumentation uses the path of the current user’s temporary folder instead.