Skip to content

Latest commit

 

History

History
524 lines (409 loc) · 88.7 KB

config.md

File metadata and controls

524 lines (409 loc) · 88.7 KB

Configuration

Configuration methods

You can apply 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]_INSTRUMENTATION_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
    • OTEL_DOTNET_AUTO_SQLCLIENT_NETFX_ILREWRITE_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 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

[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

Instrumentations

All instrumentations are enabled by default for all signal types (traces, metrics, and logs).

You can disable all instrumentations for a specific signal type by setting the OTEL_DOTNET_AUTO_{SIGNAL}_INSTRUMENTATION_ENABLED environment variable to false.

For a more granular approach, you can disable specific instrumentations for a given signal type by setting the OTEL_DOTNET_AUTO_{SIGNAL}_{0}_INSTRUMENTATION_ENABLED environment variable to false, where {SIGNAL} is the type of signal, for example TRACES, and {0} is the case-sensitive name of the instrumentation.

Environment variable Description Default value Status
OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED Enables all instrumentations. true Experimental
OTEL_DOTNET_AUTO_TRACES_INSTRUMENTATION_ENABLED Enables all trace instrumentations. Overrides OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED. Inherited from the current value of OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED Experimental
OTEL_DOTNET_AUTO_TRACES_{0}_INSTRUMENTATION_ENABLED Configuration pattern for enabling a specific trace instrumentation, where {0} is the uppercase id of the instrumentation you want to enable. Overrides OTEL_DOTNET_AUTO_TRACES_INSTRUMENTATION_ENABLED. Inherited from the current value of OTEL_DOTNET_AUTO_TRACES_INSTRUMENTATION_ENABLED Experimental
OTEL_DOTNET_AUTO_METRICS_INSTRUMENTATION_ENABLED Disables all metric instrumentations. Overrides OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED. Inherited from the current value of OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED Experimental
OTEL_DOTNET_AUTO_METRICS_{0}_INSTRUMENTATION_ENABLED Configuration pattern for enabling a specific metric instrumentation, where {0} is the uppercase id of the instrumentation you want to enable. Overrides OTEL_DOTNET_AUTO_METRICS_INSTRUMENTATION_ENABLED. Inherited from the current value of OTEL_DOTNET_AUTO_METRICS_INSTRUMENTATION_ENABLED Experimental
OTEL_DOTNET_AUTO_LOGS_INSTRUMENTATION_ENABLED Disables all log instrumentations. Overrides OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED. Inherited from the current value of OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED Experimental
OTEL_DOTNET_AUTO_LOGS_{0}_INSTRUMENTATION_ENABLED Configuration pattern for enabling a specific log instrumentation, where {0} is the uppercase id of the instrumentation you want to enable. Overrides OTEL_DOTNET_AUTO_LOGS_INSTRUMENTATION_ENABLED. Inherited from the current value of OTEL_DOTNET_AUTO_LOGS_INSTRUMENTATION_ENABLED Experimental

Traces instrumentations

Status: Mixed. Traces are stable, but particular instrumentation are in Experimental status due to lack of stable semantic convention.

ID Instrumented library Supported versions Instrumentation type Status
ASPNET ASP.NET (.NET Framework) MVC / WebApi [1] Not supported on .NET * [2] source & bytecode Experimental
ASPNETCORE ASP.NET Core Not supported on .NET Framework * source Experimental
AZURE Azure SDK [3] source Experimental
ELASTICSEARCH Elastic.Clients.Elasticsearch * [4] source Experimental
ELASTICTRANSPORT Elastic.Transport ≥0.4.16 source Experimental
ENTITYFRAMEWORKCORE Microsoft.EntityFrameworkCore Not supported on .NET Framework ≥6.0.12 source Experimental
GRAPHQL GraphQL Not supported on .NET Framework ≥7.5.0 source Experimental
GRPCNETCLIENT Grpc.Net.Client ≥2.52.0 & < 3.0.0 source Experimental
HTTPCLIENT System.Net.Http.HttpClient and System.Net.HttpWebRequest * source Experimental
KAFKA Confluent.Kafka ≥1.4.0 & < 3.0.0 [5] bytecode Experimental
MASSTRANSIT MassTransit Not supported on .NET Framework ≥8.0.0 source Experimental
MONGODB MongoDB.Driver.Core / MongoDB.Driver ≥2.7.0 < 3.5.0 bytecode Experimental
MYSQLCONNECTOR MySqlConnector ≥2.0.0 source Experimental
MYSQLDATA MySql.Data Not supported on .NET Framework ≥8.1.0 source Experimental
NPGSQL Npgsql ≥6.0.0 source Experimental
NSERVICEBUS NServiceBus ≥8.0.0 & < 10.0.0 source & bytecode Experimental
ORACLEMDA Oracle.ManagedDataAccess.Core and Oracle.ManagedDataAccess Not supported on ARM64 ≥23.4.0 source Experimental
RABBITMQ RabbitMQ.Client ≥5.0.0 source or bytecode [6] Experimental
QUARTZ Quartz Not supported on .NET Framework 4.7.1 and older ≥3.4.0 source Experimental
SQLCLIENT Microsoft.Data.SqlClient, System.Data.SqlClient [7] and System.Data (shipped with .NET Framework) * [8] source Experimental
STACKEXCHANGEREDIS StackExchange.Redis Not supported on .NET Framework ≥2.6.122 & < 3.0.0 source & bytecode Experimental
WCFCLIENT WCF * source & bytecode Experimental
WCFSERVICE WCF Not supported on .NET. * source & bytecode Experimental

[1]: Only integrated pipeline mode is supported.

[2]: ASP.NET (.NET Framework) MVC / WebApi is not supported on ARM64.

[3]: Azure. prefixed packages, released after October 1, 2021.

[4]: Elastic.Clients.Elasticsearch version ≥8.0.0 and <8.10.0. Version ≥8.10.0 is supported by Elastic.Transport instrumentation.

[5]: Confluent.Kafka is supported from version ≥1.8.2 on ARM64 for Windows and Linux, and ≥1.9.2 on macOS.

[6]: RabbitMq.Client needs bytecode instrumentation only for 5.* and 6.* versions, 7.0.0+ uses only source instrumentation.

[7]: System.Data.SqlClient is deprecated.

[8]: Microsoft.Data.SqlClient v3.* is not supported on .NET Framework, due to issue. System.Data.SqlClient is supported from version 4.8.5.

Metrics instrumentations

Status: Mixed. Metrics are stable, but particular instrumentation are in Experimental status due to lack of stable semantic convention.

ID Instrumented library Documentation Supported versions Instrumentation type Status
ASPNET ASP.NET Framework Not supported on .NET ASP.NET metrics * source & bytecode Experimental
ASPNETCORE ASP.NET Core Not supported on .NET Framework ASP.NET Core metrics * source Experimental
HTTPCLIENT System.Net.Http.HttpClient and System.Net.HttpWebRequest HttpClient metrics * source Experimental
NETRUNTIME OpenTelemetry.Instrumentation.Runtime Runtime metrics * source Experimental
NPGSQL Npgsql Not supported on .NET Framework Npgsql metrics ≥6.0.0 source Experimental
NSERVICEBUS NServiceBus NServiceBus metrics ≥8.0.0 & < 10.0.0 source & bytecode Experimental
PROCESS OpenTelemetry.Instrumentation.Process Process metrics * source Experimental
SQLCLIENT Microsoft.Data.SqlClient, System.Data.SqlClient [1] and System.Data (shipped with .NET Framework) SqlClient metrics * [2] source Experimental

[1]: System.Data.SqlClient is deprecated.

[2]: Microsoft.Data.SqlClient v3.* is not supported on .NET Framework, due to issue. System.Data.SqlClient is supported from version 4.8.5.

Logs instrumentations

Status: Experimental.

ID Instrumented library Supported versions Instrumentation type Status
ILOGGER Microsoft.Extensions.Logging Not supported on .NET Framework ≥8.0.0 bytecode or source [1] Experimental
LOG4NET log4net [2] ≥2.0.13 && < 4.0.0 bytecode Experimental

[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.

[2]: Instrumentation provides both trace context injection and logs bridge.

Instrumentation options

Environment variable Description Default value Status
OTEL_DOTNET_AUTO_GRAPHQL_SET_DOCUMENT Whether the GraphQL instrumentation can pass raw queries through the graphql.document attribute. Queries might contain sensitive information. false Experimental
OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT Whether the Oracle Client instrumentation can pass SQL statements through the db.statement attribute. Queries might contain sensitive information. If set to false, db.statement is recorded only for executing stored procedures. false Experimental
OTEL_DOTNET_AUTO_TRACES_ASPNET_INSTRUMENTATION_CAPTURE_REQUEST_HEADERS A comma-separated list of HTTP header names. ASP.NET instrumentations will capture HTTP request header values for all configured header names. Experimental
OTEL_DOTNET_AUTO_TRACES_ASPNET_INSTRUMENTATION_CAPTURE_RESPONSE_HEADERS A comma-separated list of HTTP header names. ASP.NET instrumentations will capture HTTP response header values for all configured header names. Not supported on IIS Classic mode. Experimental
OTEL_DOTNET_AUTO_TRACES_ASPNETCORE_INSTRUMENTATION_CAPTURE_REQUEST_HEADERS A comma-separated list of HTTP header names. ASP.NET Core instrumentations will capture HTTP request header values for all configured header names. Experimental
OTEL_DOTNET_AUTO_TRACES_ASPNETCORE_INSTRUMENTATION_CAPTURE_RESPONSE_HEADERS A comma-separated list of HTTP header names. ASP.NET Core instrumentations will capture HTTP response header values for all configured header names. Experimental
OTEL_DOTNET_AUTO_TRACES_GRPCNETCLIENT_INSTRUMENTATION_CAPTURE_REQUEST_METADATA A comma-separated list of gRPC metadata names. Grpc.Net.Client instrumentations will capture gRPC request metadata values for all configured metadata names. Experimental
OTEL_DOTNET_AUTO_TRACES_GRPCNETCLIENT_INSTRUMENTATION_CAPTURE_RESPONSE_METADATA A comma-separated list of gRPC metadata names. Grpc.Net.Client instrumentations will capture gRPC response metadata values for all configured metadata names. Experimental
OTEL_DOTNET_AUTO_TRACES_HTTP_INSTRUMENTATION_CAPTURE_REQUEST_HEADERS A comma-separated list of HTTP header names. HTTP Client instrumentations will capture HTTP request header values for all configured header names. Experimental
OTEL_DOTNET_AUTO_TRACES_HTTP_INSTRUMENTATION_CAPTURE_RESPONSE_HEADERS A comma-separated list of HTTP header names. HTTP Client instrumentations will capture HTTP response header values for all configured header names. Experimental
OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION Whether the ASP.NET Core instrumentation turns off redaction of the url.query attribute value. false Experimental
OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION Whether the HTTP client instrumentation turns off redaction of the url.full attribute value. false Experimental
OTEL_DOTNET_EXPERIMENTAL_ASPNET_DISABLE_URL_QUERY_REDACTION Whether the ASP.NET instrumentation turns off redaction of the url.query attribute value. false Experimental
OTEL_DOTNET_AUTO_SQLCLIENT_NETFX_ILREWRITE_ENABLED [1] false Experimental

[1]: Enables IL rewriting of SqlCommand on .NET Framework to ensure CommandText is present for SqlClient instrumentation, which is required for db.query.text and db.query.summary to be populated. Previously, CommandText was only available for stored procedures. With this setting enabled, it is also available for raw queries. This changes the behavior of events emitted by the SqlEventSource, which might impact other parts of the application if this mechanism is used.

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 [1], console, none. See the OpenTelemetry specification for more details. otlp Stable
OTEL_METRICS_EXPORTER Comma-separated list of exporters. Supported options: otlp, prometheus, console, none. See the OpenTelemetry specification for more details. otlp Stable
OTEL_LOGS_EXPORTER Comma-separated list of exporters. Supported options: otlp, console, none. See the OpenTelemetry specification for more details. otlp Stable

[1]: zipkin is deprecated and will be removed in the upcoming release.

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_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT Maximum allowed log record attribute value size. none Stable
OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT Maximum allowed log record attribute 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 of grpc.
  • On .NET 8 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.

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 Deprecated
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 created metrics. 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 8 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-arm64/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 if the .NET CLR Profiler is not used.

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

If the .NET CLR Profiler is used and the DOTNET_STARTUP_HOOKS environment variable is not set, the profiler looks for OpenTelemetry.AutoInstrumentation.StartupHook.dll in an appropriate directory relative to the OpenTelemetry.AutoInstrumentation.Native.dll file location. The folder structure can match the ZIP archive structure or the NuGet package structure (either platform dependent or independent). If the startup hook assembly is not found, the profiler loading will be aborted.

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_LOGGER AutoInstrumentation diagnostic logs sink. (supported values: none,file,console) file Experimental
OTEL_DOTNET_AUTO_LOG_FILE_SIZE Maximum size (in bytes) of a single log file created by the Auto Instrumentation 10 485 760 (10 MB) Experimental