OpenTelemetry 1.20.0
OpenTelemetry .NET SDK
Table of Contents
Installation
dotnet add package OpenTelemetry
Introduction
OpenTelemetry SDK is a reference implementation of the OpenTelemetry API. It
implements the Logging API, Metrics API, Tracing API, Resource API, and the
Context API. Once a valid SDK is installed and configured all the OpenTelemetry
API methods, which were no-ops without an SDK, will start emitting telemetry.
This SDK also ships with
ILogger
integration to automatically capture and enrich logs emitted using
Microsoft.Extensions.Logging.
The SDK deals with concerns such as sampling, processing pipelines (exporting telemetry to a particular backend, etc.), metrics aggregation, and other concerns outlined in the OpenTelemetry Specification. In most cases, users indirectly install and enable the SDK when they install an exporter.
To learn how to set up and configure the OpenTelemetry SDK see: Getting started. For additional details about initialization patterns see: Initialize the SDK.
Self-Observability (Experimental)
The SDK can emit metrics about its own internal operations, enabling operators to monitor the health of the telemetry pipeline itself (e.g., detecting dropped telemetry due to queue overflow).
Note
Self-observability metrics are experimental and may change in future
releases. They are emitted under the meter name otel.sdk.experimental.
Opt-in
Self-observability metrics are only emitted when explicitly enabled by
subscribing to the otel.sdk.experimental meter. There is no performance cost
unless enabled.
var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddMeter("otel.sdk.experimental")
.AddOtlpExporter() // or any exporter
.Build();
Available Metrics
These metrics follow the OpenTelemetry SDK Self-Observability Semantic Conventions.
| Metric Name | Instrument | Unit | Description |
|---|---|---|---|
otel.sdk.processor.log.processed |
Counter | {log_record} |
Number of log records processed by the SDK, tagged with outcome. |
otel.sdk.processor.span.processed |
Counter | {span} |
Number of spans processed by the SDK, tagged with outcome. |
Attributes
| Attribute | Description | Example |
|---|---|---|
otel.component.type |
The processor type. | batching_log_processor, simple_log_processor, batching_span_processor, simple_span_processor |
otel.component.name |
Unique instance identifier. | batching_log_processor/0, batching_span_processor/0 |
error.type |
Present only on failure. | queue_full, already_shutdown |
When error.type is absent, the item was successfully accepted by the
processor. This means the processor completed its intended handling of the
item; for the Simple and Batching processors it is recorded when the item is
handed to the exporter, and it does not indicate that the export itself
succeeded or that the item reached the backend. Export failures are not
reflected in this metric. When present:
queue_full- The batch processor's internal queue was full; the item was dropped.already_shutdown- The processor had already been shut down; the item was lost.
Note
Sampling affects otel.sdk.processor.span.processed as follows. Spans dropped
by the sampler (DROP) are not counted, because span processors are not
invoked for them at all. Spans sampled as RECORD_ONLY are counted as
successfully processed because they do reach the processor and by design are
never handed to an exporter.
Troubleshooting
All the components shipped from this repo uses
EventSource
for its internal logging. The name of the EventSource used by OpenTelemetry
SDK is "OpenTelemetry-Sdk". To know the EventSource names used by other
components, refer to the individual readme files.
While it is possible to view these logs using tools such as PerfView, dotnet-trace etc., this SDK also ships a self-diagnostics feature, which helps with troubleshooting.
Self-diagnostics
Self-diagnostics captures the internal logs of all OpenTelemetry components
(every EventSource whose name starts with "OpenTelemetry-") and writes them to
a rolling log file, to the console, or to both. It is disabled by default.
Note
Self-diagnostics are not supported on browser-based platforms (e.g. Blazor WebAssembly).
The quickest way to enable it is with environment variables:
# Write to rolling log files in ./otel-logs
OTEL_DOTNET_SELF_DIAGNOSTICS_LOG_DIRECTORY=./otel-logs
# Or write to stdout and stderr instead, at a lower level
OTEL_DOTNET_SELF_DIAGNOSTICS_SINKS=stdout,stderr
OTEL_LOG_LEVEL=debug
MinimumLevel defaults to Warning, which is intended to be safe to leave
enabled continuously; raise it only while investigating. This diverges from the
OpenTelemetry specification default for OTEL_LOG_LEVEL (info) - set
OTEL_LOG_LEVEL=info to take the specification default. With no sink enabled
the SDK is silent at any level.
It can also be configured in code through the options pipeline:
services.Configure<SelfDiagnosticsOptions>(options =>
{
options.MinimumLevel = LogLevel.Debug;
options.LogDirectory = "/var/log/otel";
});
For the full reference - every option and environment variable, the output format, what to attach to a bug report, the environment variable redaction rules, and runtime reconfiguration - see: Troubleshooting.
Note
The legacy OTEL_DIAGNOSTICS.json file mechanism still works but is
superseded by the above and will be removed in a future major version. See
Legacy self-diagnostics
mechanism.
References
Showing the top 20 packages that depend on OpenTelemetry.
| Packages | Downloads |
|---|---|
|
OpenTelemetry.Exporter.OpenTelemetryProtocol
OpenTelemetry protocol exporter for OpenTelemetry .NET
|
1,787 |
|
OpenTelemetry.Extensions.Hosting
Contains extensions to start OpenTelemetry in applications using Microsoft.Extensions.Hosting
|
409 |
|
OpenTelemetry.Extensions.Hosting
Contains extensions to start OpenTelemetry in applications using Microsoft.Extensions.Hosting
|
144 |
|
OpenTelemetry.Exporter.Prometheus.AspNetCore
ASP.NET Core middleware for hosting OpenTelemetry .NET Prometheus Exporter
|
139 |
|
OpenTelemetry.Exporter.OpenTelemetryProtocol
OpenTelemetry protocol exporter for OpenTelemetry .NET
|
61 |
|
OpenTelemetry.Exporter.Console
Console exporter for OpenTelemetry .NET
|
56 |
|
OpenTelemetry.Exporter.OpenTelemetryProtocol
OpenTelemetry protocol exporter for OpenTelemetry .NET
|
55 |
|
OpenTelemetry.Instrumentation.StackExchangeRedis
StackExchange.Redis instrumentation for OpenTelemetry .NET
|
54 |
|
OpenTelemetry.Exporter.Console
Console exporter for OpenTelemetry .NET
|
54 |
|
OpenTelemetry.Exporter.OpenTelemetryProtocol
OpenTelemetry protocol exporter for OpenTelemetry .NET
|
53 |
|
OpenTelemetry.Exporter.Console
Console exporter for OpenTelemetry .NET
|
53 |
|
OpenTelemetry.Exporter.Console
Console exporter for OpenTelemetry .NET
|
52 |
|
Azure.Monitor.OpenTelemetry.Exporter
An OpenTelemetry .NET exporter that exports to Azure Monitor
|
51 |
|
OpenTelemetry.Extensions.Hosting
Contains extensions to start OpenTelemetry in applications using Microsoft.Extensions.Hosting
|
51 |
|
OpenTelemetry.Exporter.Console
Console exporter for OpenTelemetry .NET
|
51 |
|
OpenTelemetry.Exporter.Console
Console exporter for OpenTelemetry .NET
|
50 |
|
OpenTelemetry.Extensions.Hosting
Contains extensions to start OpenTelemetry in applications using Microsoft.Extensions.Hosting
|
50 |
|
OpenTelemetry.Exporter.OpenTelemetryProtocol
OpenTelemetry protocol exporter for OpenTelemetry .NET
|
49 |
For highlights and announcements see: https://github.com/open-telemetry/opentelemetry-dotnet/blob/core-1.20.0/RELEASENOTES.md.
For detailed changes see: https://github.com/open-telemetry/opentelemetry-dotnet/blob/core-1.20.0/src/OpenTelemetry/CHANGELOG.md.
.NET 10.0
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.20.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 10.0.0)
- Microsoft.Extensions.Diagnostics.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 10.0.0)
.NET Framework 4.6.2
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.20.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 10.0.0)
- Microsoft.Extensions.Diagnostics.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 10.0.0)
.NET 8.0
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.20.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 8.0.0)
- Microsoft.Extensions.Diagnostics.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 8.0.0)
.NET 9.0
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.20.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 9.0.0)
- Microsoft.Extensions.Diagnostics.Abstractions (>= 9.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 9.0.0)
.NET Standard 2.0
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.20.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 10.0.0)
- Microsoft.Extensions.Diagnostics.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 10.0.0)
.NET Standard 2.1
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.20.0)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 10.0.0)
- Microsoft.Extensions.Diagnostics.Abstractions (>= 10.0.0)
- Microsoft.Extensions.Logging.Configuration (>= 10.0.0)
| Version | Downloads | Last updated |
|---|---|---|
| 1.20.0 | 5 | 10/16/2026 |
| 1.20.0-rc.1 | 4 | 10/15/2026 |
| 1.19.1 | 16 | 09/23/2026 |
| 1.19.1-rc.1 | 19 | 09/21/2026 |
| 1.19.0 | 15 | 09/18/2026 |
| 1.19.0-rc.1 | 22 | 09/18/2026 |
| 1.18.0 | 23 | 08/21/2026 |
| 1.18.0-rc.1 | 20 | 08/21/2026 |
| 1.17.0 | 136 | 07/18/2026 |
| 1.17.0-rc.1 | 21 | 07/19/2026 |
| 1.16.0 | 22 | 06/13/2026 |
| 1.16.0-rc.1 | 24 | 06/13/2026 |
| 1.15.3 | 1,779 | 04/24/2026 |
| 1.15.2 | 39 | 04/08/2026 |
| 1.15.1 | 49 | 03/27/2026 |
| 1.15.0 | 49 | 01/24/2026 |
| 1.14.0 | 4 | 09/27/2026 |
| 1.14.0-rc.1 | 56 | 12/11/2025 |
| 1.13.1 | 50 | 12/12/2025 |
| 1.13.0 | 44 | 12/20/2025 |
| 1.12.0 | 422 | 09/28/2026 |
| 1.11.2 | 47 | 12/14/2025 |
| 1.11.1 | 36 | 12/18/2025 |
| 1.11.0 | 37 | 12/12/2025 |
| 1.11.0-rc.1 | 39 | 12/13/2025 |
| 1.10.0 | 40 | 12/13/2025 |
| 1.10.0-rc.1 | 7 | 10/01/2026 |
| 1.10.0-beta.1 | 39 | 12/14/2025 |
| 1.9.0 | 51 | 12/15/2025 |
| 1.9.0-rc.1 | 41 | 12/11/2025 |
| 1.9.0-alpha.1 | 37 | 12/13/2025 |
| 1.8.1 | 2 | 10/04/2026 |
| 1.8.0 | 34 | 12/20/2025 |
| 1.8.0-rc.1 | 2 | 09/29/2026 |
| 1.8.0-beta.1 | 43 | 12/20/2025 |
| 1.7.0 | 34 | 12/14/2025 |
| 1.7.0-rc.1 | 49 | 12/25/2025 |
| 1.7.0-alpha.1 | 30 | 12/11/2025 |
| 1.6.0 | 32 | 12/14/2025 |
| 1.6.0-rc.1 | 32 | 12/13/2025 |
| 1.6.0-alpha.1 | 38 | 12/12/2025 |
| 1.5.1 | 6 | 09/30/2026 |
| 1.5.0 | 36 | 12/20/2025 |
| 1.5.0-rc.1 | 35 | 12/16/2025 |
| 1.5.0-alpha.2 | 39 | 12/15/2025 |
| 1.5.0-alpha.1 | 35 | 12/14/2025 |
| 1.4.0 | 46 | 12/11/2025 |
| 1.4.0-rc.4 | 36 | 12/14/2025 |
| 1.4.0-rc.3 | 34 | 12/12/2025 |
| 1.4.0-rc.2 | 44 | 12/14/2025 |
| 1.4.0-rc.1 | 34 | 12/13/2025 |
| 1.4.0-beta.3 | 42 | 12/11/2025 |
| 1.4.0-beta.2 | 4 | 10/08/2026 |
| 1.4.0-beta.1 | 44 | 12/14/2025 |
| 1.4.0-alpha.2 | 36 | 12/14/2025 |
| 1.4.0-alpha.1 | 32 | 12/14/2025 |
| 1.3.2 | 40 | 12/12/2025 |
| 1.3.1 | 47 | 12/11/2025 |
| 1.3.0 | 37 | 12/14/2025 |
| 1.3.0-rc.2 | 41 | 12/14/2025 |
| 1.3.0-beta.2 | 38 | 12/14/2025 |
| 1.3.0-beta.1 | 51 | 12/14/2025 |
| 1.2.0 | 41 | 12/14/2025 |
| 1.2.0-rc5 | 37 | 12/12/2025 |
| 1.2.0-rc4 | 43 | 12/13/2025 |
| 1.2.0-rc3 | 31 | 12/12/2025 |
| 1.2.0-rc2 | 30 | 12/12/2025 |
| 1.2.0-rc1 | 35 | 12/12/2025 |
| 1.2.0-beta2.1 | 4 | 09/28/2026 |
| 1.2.0-beta1 | 33 | 12/24/2025 |
| 1.2.0-alpha4 | 38 | 12/14/2025 |
| 1.2.0-alpha3 | 36 | 12/22/2025 |
| 1.2.0-alpha2 | 29 | 12/29/2025 |
| 1.2.0-alpha1 | 44 | 12/20/2025 |
| 1.1.0 | 40 | 12/14/2025 |
| 1.1.0-rc1 | 31 | 12/14/2025 |
| 1.1.0-beta4 | 35 | 12/23/2025 |
| 1.1.0-beta3 | 46 | 12/29/2025 |
| 1.1.0-beta2 | 47 | 12/29/2025 |
| 1.1.0-beta1 | 38 | 12/23/2025 |
| 1.0.1 | 43 | 12/13/2025 |
| 1.0.0-rc4 | 30 | 12/14/2025 |
| 1.0.0-rc3 | 35 | 12/14/2025 |
| 1.0.0-rc2 | 39 | 12/15/2025 |
| 1.0.0-rc1.1 | 37 | 12/14/2025 |
| 0.8.0-beta.1 | 40 | 12/11/2025 |
| 0.7.0-beta.1 | 37 | 12/20/2025 |
| 0.6.0-beta.1 | 41 | 12/11/2025 |
| 0.5.0-beta.2 | 37 | 12/11/2025 |
| 0.4.0-beta.2 | 58 | 12/12/2025 |
| 0.3.0-beta.1 | 48 | 12/12/2025 |
| 0.2.0-alpha.275 | 38 | 12/12/2025 |
| 0.2.0-alpha.220 | 32 | 12/12/2025 |
| 0.2.0-alpha.179 | 30 | 12/12/2025 |
| 0.2.0-alpha.100 | 32 | 12/20/2025 |
| 0.2.0-alpha.40 | 28 | 12/20/2025 |
| 0.2.0-alpha.5 | 32 | 12/12/2025 |