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

Environment variableDescriptionDefault valueStatus
OTEL_DOTNET_AUTO_HOMEInstallation location.Experimental
OTEL_DOTNET_AUTO_EXCLUDE_PROCESSESNames 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_ENABLEDEnables 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]falseExperimental
OTEL_LOG_LEVELSDK log level. (supported values: none,error,warn,info,debug)infoStable

[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 variableDescriptionDefault valueStatus
OTEL_RESOURCE_ATTRIBUTESKey-value pairs to be used as resource attributes. See Resource SDK for more details.See Resource semantic conventions for details.Stable
OTEL_SERVICE_NAMESets 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 variableDescriptionDefault valueStatus
OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLEDEnables all resource detectors.trueExperimental
OTEL_DOTNET_AUTO_{0}_RESOURCE_DETECTOR_ENABLEDConfiguration 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.trueExperimental

The following resource detectors are included and enabled by default:

IDDescriptionDocumentationStatus
AZUREAPPSERVICEAzure App Service detectorAzure resource detector documentationExperimental
CONTAINERContainer detectorContainer resource detector documentation Not supported on .NET FrameworkExperimental
HOSTHost detectorHost resource detector documentationExperimental
PROCESSProcess detectorProcess resource detector documentationExperimental
PROCESSRUNTIMEProcess Runtime detectorProcess Runtime resource detector documentationExperimental

Propagators

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

Environment variableDescriptionDefault value
OTEL_PROPAGATORSComma-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 variableDescriptionDefault valueStatus
OTEL_TRACES_SAMPLERSampler to be used for traces [1]parentbased_always_onStable
OTEL_TRACES_SAMPLER_ARGString 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 variableDescriptionDefault valueStatus
OTEL_TRACES_EXPORTERTraces exporter to be used. The value can be one of the following: zipkin, otlp, none.otlpStable
OTEL_METRICS_EXPORTERMetrics exporter to be used. The value can be one of the following: otlp, prometheus, none.otlpStable
OTEL_LOGS_EXPORTERLogs exporter to be used. The value can be one of the following: otlp, none.otlpStable

Traces exporter

Environment variableDescriptionDefault valueStatus
OTEL_BSP_SCHEDULE_DELAYDelay interval (in milliseconds) between two consecutive exports.5000Stable
OTEL_BSP_EXPORT_TIMEOUTMaximum allowed time (in milliseconds) to export data30000Stable
OTEL_BSP_MAX_QUEUE_SIZEMaximum queue size.2048Stable
OTEL_BSP_MAX_EXPORT_BATCH_SIZEMaximum batch size. Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE.512Stable

Metrics exporter

Environment variableDescriptionDefault valueStatus
OTEL_METRIC_EXPORT_INTERVALThe time interval (in milliseconds) between the start of two export attempts.60000 for OTLP exporter, 10000 for console exporterStable
OTEL_METRIC_EXPORT_TIMEOUTMaximum allowed time (in milliseconds) to export data.30000 for OTLP exporter, none for console exporterStable

Logs exporter

Environment variableDescriptionDefault valueStatus
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGEWhether the formatted log message should be set or not.falseExperimental

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 variableDescriptionDefault valueStatus
OTEL_EXPORTER_OTLP_ENDPOINTTarget endpoint for the OTLP exporter. See the OpenTelemetry specification for more details.http://localhost:4318 for the http/protobuf protocol, http://localhost:4317 for the grpc protocolStable
OTEL_EXPORTER_OTLP_PROTOCOLOTLP exporter transport protocol. Supported values are grpc, http/protobuf. [1]http/protobufStable
OTEL_EXPORTER_OTLP_TIMEOUTThe max waiting time (in milliseconds) for the backend to process each batch.10000Stable
OTEL_EXPORTER_OTLP_HEADERSComma-separated list of additional HTTP headers sent with each export, for example: Authorization=secret,X-Key=Value.Stable
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMITMaximum allowed attribute value size.noneStable
OTEL_ATTRIBUTE_COUNT_LIMITMaximum allowed span attribute count.128Stable
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMITMaximum allowed attribute value size. Not applicable for metrics..none nStable
OTEL_SPAN_ATTRIBUTE_COUNT_LIMITMaximum allowed span attribute count. Not applicable for metrics..128Stable
OTEL_SPAN_EVENT_COUNT_LIMITMaximum allowed span event count.128Stable
OTEL_SPAN_LINK_COUNT_LIMITMaximum allowed span link count.128Stable
OTEL_EVENT_ATTRIBUTE_COUNT_LIMITMaximum allowed attribute per span event count.128Stable
OTEL_LINK_ATTRIBUTE_COUNT_LIMITMaximum allowed attribute per span link count.128Stable

[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.63.0" /> to the .csproj file.
  • On .NET Framework, the grpc OTLP exporter protocol 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:

Environment variableDescriptionDefault valueStatus
OTEL_EXPORTER_ZIPKIN_ENDPOINTZipkin URLhttp://localhost:9411/api/v2/spansStable

Additional settings

Environment variableDescriptionDefault valueStatus
OTEL_DOTNET_AUTO_TRACES_ENABLEDEnables traces.trueExperimental
OTEL_DOTNET_AUTO_OPENTRACING_ENABLEDEnables OpenTracing tracer.falseExperimental
OTEL_DOTNET_AUTO_LOGS_ENABLEDEnables logs.trueExperimental
OTEL_DOTNET_AUTO_METRICS_ENABLEDEnables metrics.trueExperimental
OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLEDEnables automatic redirection of the assemblies used by the automatic instrumentation on the .NET Framework.trueExperimental
OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCESComma-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_SOURCESComma-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_UNHANDLEDEXCEPTIONControls 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.falseExperimental
OTEL_DOTNET_AUTO_METRICS_ADDITIONAL_SOURCESComma-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_PLUGINSColon-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 variableDescriptionDefault valueStatus
OTEL_DOTNET_AUTO_RULE_ENGINE_ENABLEDEnables RuleEngine.trueExperimental

.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 variableDescriptionRequired valueStatus
COR_ENABLE_PROFILINGCORECLR_ENABLE_PROFILINGEnables the profiler.1Experimental
COR_PROFILERCORECLR_PROFILERCLSID of the profiler.{918728DD-259F-4A6A-AC2B-B85E1B658318}Experimental
COR_PROFILER_PATHCORECLR_PROFILER_PATHPath 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 macOSExperimental
COR_PROFILER_PATH_32CORECLR_PROFILER_PATH_32Path to the 32-bit profiler. Bitness-specific paths take precedence over generic paths.$INSTALL_DIR/win-x86/OpenTelemetry.AutoInstrumentation.Native.dll for WindowsExperimental
COR_PROFILER_PATH_64CORECLR_PROFILER_PATH_64Path to the 64-bit profiler. Bitness-specific paths take precedence over generic paths.$INSTALL_DIR/win-x64/OpenTelemetry.AutoInstrumentation.Native.dll for WindowsExperimental

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 variableRequired valueStatus
DOTNET_STARTUP_HOOKS$INSTALL_DIR/net/OpenTelemetry.AutoInstrumentation.StartupHook.dllExperimental
DOTNET_ADDITIONAL_DEPS$INSTALL_DIR/AdditionalDepsExperimental
DOTNET_SHARED_STORE$INSTALL_DIR/storeExperimental

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 variableDescriptionDefault valueStatus
OTEL_DOTNET_AUTO_LOG_DIRECTORYDirectory of the .NET Tracer logs.See the previous note on default pathsExperimental
OTEL_LOG_LEVELSDK log level. (supported values: none,error,warn,info,debug)infoStable
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLEDWhether the traces console exporter is enabled or not.falseExperimental
OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLEDWhether the metrics console exporter is enabled or not.falseExperimental
OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLEDWhether the logs console exporter is enabled or not.falseExperimental
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGEWhether the log state should be formatted.falseExperimental