open-telemetry
/
opentelemetry-dotnet-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
opentelemetry-dotnet-instru.../docs/config.md

34 KiB
Raw Blame History

Configuration

Global settings

Environment variable Description Default value
OTEL_DOTNET_AUTO_HOME Installation location.
OTEL_DOTNET_AUTO_INCLUDE_PROCESSES Names of the executable files that the profiler can instrument. Supports multiple comma-separated values, for example: MyApp.exe,dotnet.exe. If unset, the profiler attaches to all processes by default.
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. The list is processed after OTEL_DOTNET_AUTO_INCLUDE_PROCESSES. If unset, the profiler attaches to all processes by default.

Resources

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

Environment variable Description Default value
OTEL_RESOURCE_ATTRIBUTES Key-value pairs to be used as resource attributes. See Resource SDK for more details. See Resource semantic conventions for details.
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. unknown_service:%ProcessName%

Instrumentations

Environment variable Description Default value
OTEL_DOTNET_AUTO_INTEGRATIONS_FILE List of bytecode instrumentations JSON configuration filepaths, delimited by the platform-specific path separator (; on Windows, : on Linux and macOS). For example: %ProfilerDirectory%/integrations.json. It is required for bytecode instrumentations.
OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS Comma-separated list of traces source instrumentations you want to enable. Set to none to disable all trace instrumentations. all available instrumentations
OTEL_DOTNET_AUTO_TRACES_DISABLED_INSTRUMENTATIONS Comma-separated list of traces source and bytecode instrumentations you want to disable.
OTEL_DOTNET_AUTO_METRICS_ENABLED_INSTRUMENTATIONS Comma-separated list of metrics source instrumentations you want to enable. Set to none to disable all metric instrumentations. all available instrumentations
OTEL_DOTNET_AUTO_METRICS_DISABLED_INSTRUMENTATIONS Comma-separated list of metrics source instrumentations you want to disable.
OTEL_DOTNET_AUTO_LOGS_ENABLED_INSTRUMENTATIONS Comma-separated list of logs source instrumentations you want to enable. Set to none to disable all metric instrumentations. all available instrumentations
OTEL_DOTNET_AUTO_LOGS_DISABLED_INSTRUMENTATIONS Comma-separated list of logs source instrumentations you want to disable.

Traces instrumentations

ID Instrumented library Supported versions Instrumentation type
AspNet ASP.NET Framework * source
AspNet ASP.NET Core * source
GraphQL GraphQL ≥2.3.0 & < 3.0.0 bytecode
GrpcNetClient Grpc.Net.Client ≥2.43.0 & < 3.0.0 source
HttpClient System.Net.Http.HttpClient and System.Net.HttpWebRequest * source
MassTransit MassTransit Not supported on .NET Framework ≥8.0.0 source
MongoDB MongoDB.Driver.Core Not supported on .NET Framework ≥2.13.3 & < 3.0.0 source & bytecode
MySqlData MySql.Data Not supported on .NET Framework ≥6.10.7 source & bytecode [1]
Npgsql Npgsql ≥6.0.0 source
SqlClient Microsoft.Data.SqlClient and System.Data.SqlClient * source
StackExchangeRedis StackExchange.Redis Not supported on .NET Framework ≥2.0.405 < 3.0.0 source & bytecode
Wcf System.ServiceModel No support for server side on .NET. For configuration see WCF Instrumentation Configuration * [2] source 
1
2

≥ 4.7.0.

Metrics instrumentations

ID Instrumented library Supported versions Instrumentation type
AspNet ASP.NET Framework [1] * source
AspNet ASP.NET Core [2] * source
HttpClient System.Net.Http.HttpClient and System.Net.HttpWebRequest * source
NetRuntime OpenTelemetry.Instrumentation.Runtime * source
Process OpenTelemetry.Instrumentation.Process * source 
1

is also enabled.

2

Microsoft.AspNetCore.Hosting.HttpRequestIn spans.

Logs instrumentations

ID Instrumented library Supported versions Instrumentation type
ILogger Microsoft.Extensions.Logging Not supported on .NET Framework ≥6.0.0 bytecode or source [1]

[1]: For ASP.NET Core applications, the LoggingBuilder instrumentation can be enabled without using the .NET CLR Profiler by setting the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable to OpenTelemetry.AutoInstrumentation.AspNetCoreBootstrapper.

Instrumentation options

Environment variable Description Default value
OTEL_DOTNET_AUTO_GRAPHQL_SET_DOCUMENT Whether GraphQL instrumentation can pass raw queries as graphql.document attribute. This may contain sensitive information and therefore is disabled by default. false

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

Exporters

Exporters output the telemetry.

Environment variable Description Default value
OTEL_TRACES_EXPORTER Traces exporter to be used. The value can be one of the following: zipkin, jaeger, otlp, none. otlp
OTEL_METRICS_EXPORTER Metrics exporter to be used. The value can be one of the following: otlp, prometheus, none. otlp
OTEL_METRIC_EXPORT_INTERVAL The time interval (in milliseconds) between the start of two export attempts. 60000 for OTLP exporter, 10000 for console exporter
OTEL_LOGS_EXPORTER Logs exporter to be used. The value can be one of the following: otlp, none. otlp
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE Whether the formatted log message should be set or not. false

Jaeger

To enable the Jaeger exporter, set the OTEL_TRACES_EXPORTER environment variable to jaeger.

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

Environment variable Description Default value
OTEL_EXPORTER_JAEGER_AGENT_HOST Host name for the Jaeger agent. Used for the udp/thrift.compact protocol. localhost
OTEL_EXPORTER_JAEGER_AGENT_PORT Port for the Jaeger agent. Used for the udp/thrift.compact protocol. 6831
OTEL_EXPORTER_JAEGER_ENDPOINT Jaeger Collector HTTP endpoint. Used for the http/thrift.binary protocol. http://localhost:14268
OTEL_EXPORTER_JAEGER_PROTOCOL Protocol to use for Jaeger exporter. Supported values are udp/thrift.compact, http/thrift.binary udp/thrift.compact

OTLP

To enable the OTLP exporter, set the OTEL_TRACES_EXPORTER/OTEL_METRICS_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
OTEL_EXPORTER_OTLP_ENDPOINT Target 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 protocol
OTEL_EXPORTER_OTLP_PROTOCOL OTLP exporter transport protocol. Supported values are grpc, http/protobuf. [1] http/protobuf
OTEL_EXPORTER_OTLP_TIMEOUT The max waiting time (in milliseconds) for the backend to process each batch. 10000
OTEL_EXPORTER_OTLP_HEADERS Comma-separated list of additional HTTP headers sent with each export, for example: Authorization=secret,X-Key=Value.

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

Prometheus

⚠️ 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.

Zipkin

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
OTEL_EXPORTER_ZIPKIN_ENDPOINT Zipkin URL. http://localhost:8126

Additional settings

Environment variable Description Default value
OTEL_DOTNET_AUTO_TRACES_ENABLED Enables trace provider together with traces source instrumentations. true
OTEL_DOTNET_AUTO_OPENTRACING_ENABLED Enables OpenTracing tracer. false
OTEL_DOTNET_AUTO_METRICS_ENABLED Enables meter provider together with metrics source instrumentations. true
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.
OTEL_DOTNET_AUTO_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.
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
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.
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.

.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
COR_ENABLE_PROFILING CORECLR_ENABLE_PROFILING Enables the profiler. 1
COR_PROFILER CORECLR_PROFILER CLSID of the profiler. {918728DD-259F-4A6A-AC2B-B85E1B658318}
COR_PROFILER_PATH CORECLR_PROFILER_PATH Path to the profiler. $INSTALL_DIR/OpenTelemetry.AutoInstrumentation.Native.dll for Windows, $INSTALL_DIR/OpenTelemetry.AutoInstrumentation.Native.so for Linux, $INSTALL_DIR/OpenTelemetry.AutoInstrumentation.Native.dylib for macOS
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
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

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
OTEL_DOTNET_AUTO_INTEGRATIONS_FILE

.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
DOTNET_STARTUP_HOOKS $INSTALL_DIR/net6.0/OpenTelemetry.AutoInstrumentation.StartupHook.dll
DOTNET_ADDITIONAL_DEPS $INSTALL_DIR/AdditionalDeps
DOTNET_SHARED_STORE $INSTALL_DIR/store

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
OTEL_DOTNET_AUTO_LOG_DIRECTORY Directory of the .NET Tracer logs. See the previous note on default paths
OTEL_DOTNET_AUTO_DEBUG Enables debugging mode for the tracer. false
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED Whether the traces console exporter is enabled or not. false
OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED Whether the metrics console exporter is enabled or not. false
OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED Whether the logs console exporter is enabled or not. false
OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE Whether the log state should be formatted. false