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:
Environment variables
Environment variables are the main way to configure the settings.
App.config
orWeb.config
fileFor an application running on .NET Framework, you can use a web configuration file (
web.config
) or an application configuration file (app.config
) to configure theOTEL_*
settings.⚠️ Only settings starting with
OTEL_
can be set usingApp.config
orWeb.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>
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.
- If the application is hosted on IIS in .NET Framework this will be
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
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_DOTNET_AUTO_HOME | Installation location. | Experimental | |
OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES | Names of the executable files that the profiler cannot instrument. Supports multiple comma-separated values, for example: ReservedProcess.exe,powershell.exe . If unset, the profiler attaches to all processes by default. [1][2] | Experimental | |
OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED | Enables possibility to fail process when automatic instrumentation cannot be executed. It is designed for debugging purposes. It should not be used in production environment. [1] | false | Experimental |
OTEL_DOTNET_AUTO_LOGGER | AutoInstrumentation diagnostic logs sink. (supported values: none ,file ,console ) | file | Experimental |
OTEL_LOG_LEVEL | SDK log level. (supported values: none ,error ,warn ,info ,debug ) | info | Stable |
[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
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes. See Resource SDK for more details. | See Resource semantic conventions for details. | Stable |
OTEL_SERVICE_NAME | Sets the value of the service.name resource attribute. If service.name is provided in OTEL_RESOURCE_ATTRIBUTES , the value of OTEL_SERVICE_NAME takes precedence. | See Service name automatic detection under Configuration method section. | Stable |
Resource detectors
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLED | Enables all resource detectors. | true | Experimental |
OTEL_DOTNET_AUTO_{0}_RESOURCE_DETECTOR_ENABLED | Configuration pattern for enabling a specific resource detector, where {0} is the uppercase ID of the resource detector you want to enable. Overrides OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLED . | true | Experimental |
The following resource detectors are included and enabled by default:
ID | Description | Documentation | Status |
---|---|---|---|
AZUREAPPSERVICE | Azure App Service detector | Azure resource detector documentation | Experimental |
CONTAINER | Container detector | Container resource detector documentation Not supported on .NET Framework | Experimental |
HOST | Host detector | Host resource detector documentation | Experimental |
OPERATINGSYSTEM | Operating System detector | Operating System resource detector documentation | Experimental |
PROCESS | Process detector | Process resource detector documentation | Experimental |
PROCESSRUNTIME | Process Runtime detector | Process Runtime resource detector documentation | Experimental |
Propagators
Propagators allow applications to share context. See the OpenTelemetry specification for more details.
Environment variable | Description | Default value |
---|---|---|
OTEL_PROPAGATORS | Comma-separated list of propagators. Supported options: tracecontext , baggage , b3multi , b3 . See the OpenTelemetry specification for more details. | tracecontext,baggage |
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.
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_TRACES_SAMPLER | Sampler to be used for traces [1] | parentbased_always_on | Stable |
OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument [2] | Stable |
[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.
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_TRACES_EXPORTER | Comma-separated list of exporters. Supported options: otlp , zipkin , console , none . | otlp | Stable |
OTEL_METRICS_EXPORTER | Comma-separated list of exporters. Supported options: otlp , prometheus , console , none . | otlp | Stable |
OTEL_LOGS_EXPORTER | Comma-separated list of exporters. Supported options: otlp , console , none . | otlp | Stable |
Traces exporter
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports. | 5000 | Stable |
OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | Stable |
OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size. | 2048 | Stable |
OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size. Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE . | 512 | Stable |
Metrics exporter
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_METRIC_EXPORT_INTERVAL | The time interval (in milliseconds) between the start of two export attempts. | 60000 for OTLP exporter, 10000 for console exporter | Stable |
OTEL_METRIC_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data. | 30000 for OTLP exporter, none for console exporter | Stable |
Logs exporter
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE | Whether the formatted log message should be set or not. | false | Experimental |
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:
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | Target endpoint for the OTLP exporter. See the OpenTelemetry specification for more details. | http/protobuf : http://localhost:4318 , grpc : http://localhost:4317 | Stable |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Equivalent to OTEL_EXPORTER_OTLP_ENDPOINT , but applies only to traces. | http/protobuf : http://localhost:4318/v1/traces , grpc : http://localhost:4317 | Stable |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Equivalent to OTEL_EXPORTER_OTLP_ENDPOINT , but applies only to metrics. | http/protobuf : http://localhost:4318/v1/metrics , grpc : http://localhost:4317 | Stable |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Equivalent to OTEL_EXPORTER_OTLP_ENDPOINT , but applies only to logs. | http/protobuf : http://localhost:4318/v1/logs , grpc : http://localhost:4317 | Stable |
OTEL_EXPORTER_OTLP_PROTOCOL | OTLP exporter transport protocol. Supported values are grpc , http/protobuf . [1] | http/protobuf | Stable |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | Equivalent to OTEL_EXPORTER_OTLP_PROTOCOL , but applies only to traces. | http/protobuf | Stable |
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Equivalent to OTEL_EXPORTER_OTLP_PROTOCOL , but applies only to metrics. | http/protobuf | Stable |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Equivalent to OTEL_EXPORTER_OTLP_PROTOCOL , but applies only to logs. | http/protobuf | Stable |
OTEL_EXPORTER_OTLP_TIMEOUT | The max waiting time (in milliseconds) for the backend to process each batch. | 10000 (10s) | Stable |
OTEL_EXPORTER_OTLP_TRACES_TIMEOUT | Equivalent to OTEL_EXPORTER_OTLP_TIMEOUT , but applies only to traces. | 10000 (10s) | Stable |
OTEL_EXPORTER_OTLP_METRICS_TIMEOUT | Equivalent to OTEL_EXPORTER_OTLP_TIMEOUT , but applies only to metrics. | 10000 (10s) | Stable |
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT | Equivalent to OTEL_EXPORTER_OTLP_TIMEOUT , but applies only to logs. | 10000 (10s) | Stable |
OTEL_EXPORTER_OTLP_HEADERS | Comma-separated list of additional HTTP headers sent with each export, for example: Authorization=secret,X-Key=Value . | Stable | |
OTEL_EXPORTER_OTLP_TRACES_HEADERS | Equivalent to OTEL_EXPORTER_OTLP_HEADERS , but applies only to traces. | Stable | |
OTEL_EXPORTER_OTLP_METRICS_HEADERS | Equivalent to OTEL_EXPORTER_OTLP_HEADERS , but applies only to metrics. | Stable | |
OTEL_EXPORTER_OTLP_LOGS_HEADERS | Equivalent to OTEL_EXPORTER_OTLP_HEADERS , but applies only to logs. | Stable | |
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size. | none | Stable |
OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count. | 128 | Stable |
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size. Not applicable for metrics.. | none | Stable |
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count. Not applicable for metrics.. | 128 | Stable |
OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count. | 128 | Stable |
OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count. | 128 | Stable |
OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count. | 128 | Stable |
OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count. | 128 | Stable |
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | The aggregation temporality to use on the basis of instrument kind. [2] | cumulative | Stable |
[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 ofgrpc
. - On .NET 6 and higher, the application must reference
Grpc.Net.Client
to use thegrpc
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
Warning
Do NOT use in production.
Prometheus exporter is intended for the inner dev loop. Production environments
can use a combination of OTLP exporter with
OpenTelemetry Collector
having
otlp
receiver
and
prometheus
exporter.
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:
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_EXPORTER_ZIPKIN_ENDPOINT | Zipkin URL | http://localhost:9411/api/v2/spans | Stable |
Additional settings
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_DOTNET_AUTO_TRACES_ENABLED | Enables traces. | true | Experimental |
OTEL_DOTNET_AUTO_OPENTRACING_ENABLED | Enables OpenTracing tracer. | false | Experimental |
OTEL_DOTNET_AUTO_LOGS_ENABLED | Enables logs. | true | Experimental |
OTEL_DOTNET_AUTO_METRICS_ENABLED | Enables metrics. | true | Experimental |
OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED | Enables automatic redirection of the assemblies used by the automatic instrumentation on the .NET Framework. | true | Experimental |
OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES | Comma-separated list of additional System.Diagnostics.ActivitySource names to be added to the tracer at the startup. Use it to capture manually instrumented spans. | Experimental | |
OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_LEGACY_SOURCES | Comma-separated list of additional legacy source names to be added to the tracer at the startup. Use it to capture System.Diagnostics.Activity objects created without using the System.Diagnostics.ActivitySource API. | Experimental | |
OTEL_DOTNET_AUTO_FLUSH_ON_UNHANDLEDEXCEPTION | Controls whether the telemetry data is flushed when an AppDomain.UnhandledException event is raised. Set to true when you suspect that you are experiencing a problem with missing telemetry data and also experiencing unhandled exceptions. | false | Experimental |
OTEL_DOTNET_AUTO_METRICS_ADDITIONAL_SOURCES | Comma-separated list of additional System.Diagnostics.Metrics.Meter names to be added to the meter at the startup. Use it to capture manually instrumented spans. | Experimental | |
OTEL_DOTNET_AUTO_PLUGINS | Colon-separated list of OTel SDK instrumentation plugin types, specified with the assembly-qualified name. Note: This list must be colon-separated because the type names may include commas. See more info on how to write plugins at plugins.md. | Experimental |
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.
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_DOTNET_AUTO_RULE_ENGINE_ENABLED | Enables RuleEngine. | true | Experimental |
.NET CLR Profiler
The CLR uses the following environment variables to set up the profiler. See .NET Runtime Profiler Loading for more information.
.NET Framework environment variable | .NET environment variable | Description | Required value | Status |
---|---|---|---|---|
COR_ENABLE_PROFILING | CORECLR_ENABLE_PROFILING | Enables the profiler. | 1 | Experimental |
COR_PROFILER | CORECLR_PROFILER | CLSID of the profiler. | {918728DD-259F-4A6A-AC2B-B85E1B658318} | Experimental |
COR_PROFILER_PATH | CORECLR_PROFILER_PATH | Path to the profiler. | $INSTALL_DIR/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so for Linux glibc, $INSTALL_DIR/linux-musl-x64/OpenTelemetry.AutoInstrumentation.Native.so for Linux musl, $INSTALL_DIR/osx-x64/OpenTelemetry.AutoInstrumentation.Native.dylib for macOS | Experimental |
COR_PROFILER_PATH_32 | CORECLR_PROFILER_PATH_32 | Path to the 32-bit profiler. Bitness-specific paths take precedence over generic paths. | $INSTALL_DIR/win-x86/OpenTelemetry.AutoInstrumentation.Native.dll for Windows | Experimental |
COR_PROFILER_PATH_64 | CORECLR_PROFILER_PATH_64 | Path to the 64-bit profiler. Bitness-specific paths take precedence over generic paths. | $INSTALL_DIR/win-x64/OpenTelemetry.AutoInstrumentation.Native.dll for Windows | Experimental |
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.
Environment variable | Required value | Status |
---|---|---|
DOTNET_STARTUP_HOOKS | $INSTALL_DIR/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll | Experimental |
DOTNET_ADDITIONAL_DEPS | $INSTALL_DIR/AdditionalDeps | Experimental |
DOTNET_SHARED_STORE | $INSTALL_DIR/store | Experimental |
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.
Environment variable | Description | Default value | Status |
---|---|---|---|
OTEL_DOTNET_AUTO_LOG_DIRECTORY | Directory of the .NET Tracer logs. | See the previous note on default paths | Experimental |
OTEL_LOG_LEVEL | SDK log level. (supported values: none ,error ,warn ,info ,debug ) | info | Stable |
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED | Whether the traces console exporter is enabled or not. | false | Deprecated |
OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED | Whether the metrics console exporter is enabled or not. | false | Deprecated |
OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED | Whether the logs console exporter is enabled or not. | false | Deprecated |
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE | Whether the log state should be formatted. | false | Experimental |
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!