OpenTelemetry .NET Documentation

The OpenTelemetry .NET API provides abstractions for instrumentation without addressing export or sampling concerns. The core components include:

• Tracing API: Used to generate Spans (represented by the .NET Activity class) to form trace trees.
• Logging API: Integrates with the standard Microsoft.Extensions.Logging API rather than introducing a new one.
• Metrics API: Used to capture and process raw measurements of program execution.
• Baggage API: Allows adding context to metrics, traces, and logs that can be propagated out-of-process.
• Context and Propagation API: Handles the injection and extraction of context data.

OpenTelemetry .NET packages often bundle multiple signals (Traces, Metrics, Logs, Baggage, etc.) into a single package. For example, the OpenTelemetry package contains SDK components for all signals.

Instrumentation packages also follow this model; for instance, OpenTelemetry.Instrumentation.AspNetCore provides Traces, Metrics, and propagation handling in one package rather than splitting them.

The OpenTelemetry Collector Proto defines the protocol used by the OpenTelemetry collector. It is organized into several specialized packages:

• common: Contains common messages shared across different services.
• trace: Contains the Trace Service protos.
• metrics: Contains the Metrics Service protos.
• logs: Contains the Logs Service protos.

OpenTelemetry .NET implements the Trace API using the native .NET System.Diagnostics classes. This means you do not need to use specific OpenTelemetry-branded classes for instrumentation; instead, you use standard .NET types:

• ActivitySource: Represents an OpenTelemetry Tracer.
• Activity: Represents an OpenTelemetry Span.

By using ActivitySource and Activity, your code remains compatible with the standard .NET runtime instrumentation model while allowing OpenTelemetry to collect the data via a configured TracerProvider.

The OpenTelemetry.Api.ProviderBuilderExtensions package provides extension methods and helpers designed to build TracerProviders and MeterProviders using the Microsoft.Extensions.DependencyInjection API (specifically IServiceCollection).

This package is primarily intended for instrumentation library authors who need to integrate with the OpenTelemetry SDK without introducing a direct dependency on the full SDK.

OpenTelemetry .NET exposes experimental APIs in pre-release builds. These APIs are used when the OpenTelemetry Specification marks a feature as experimental or when the SIG (Special Interest Group) members are soliciting community feedback on a design.

Important Note on Visibility:

• In pre-release builds, experimental APIs are exposed as public.
• In stable builds, these same APIs are exposed as internal and cannot be used directly by consumers.

The OpenTelemetry .NET SDK uses specific strategies to ensure high performance and efficiency during metrics aggregation:

1. Pre-Aggregation: Aggregation occurs within the SDK before data is exported, reducing the volume of data transmitted.
2. Cardinality Limits: The SDK respects cardinality limits to prevent indefinite memory usage during 'cardinality explosion' (too many unique attribute combinations).
3. Memory Preallocation: Memory for aggregation is allocated during SDK initialization to avoid on-the-fly allocations and garbage collection on hot code paths.

To maintain high performance, you should aim to avoid heap allocations on hot code paths when using the Metrics API.

OpenTelemetry .NET follows SemVer V2 guidelines. For stable packages, all public APIs (including API, SDK, Exporters, and Instrumentation) are backward compatible within the same MAJOR version. If a method is planned for removal in a future major version, it will first be marked with the [Obsolete] attribute.

Pre-releases: Packages with identifiers like -Alpha, -Beta, or -RC have no API guarantees. Breaking changes and functionality removals can occur in any pre-release. Generally, stability increases in the order: Alpha < Beta < RC.

OpenTelemetry .NET uses diagnostic categories to report information to users. These diagnostics are used by the compiler to:

• Report information about experimental or obsolete code being invoked.
• Suggest improvements to specific code patterns identified through static analysis.

To get started with OpenTelemetry tracing in a .NET console application, follow these steps:

1. Create a new project:

   dotnet new console --output getting-started
   cd getting-started

2. Install the Console Exporter package:

   dotnet add package OpenTelemetry.Exporter.Console

3. Configure the TracerProvider and instrument your code: You must create an ActivitySource to represent your tracer, use it to start an Activity (which represents a Span), and configure a TracerProvider to collect and export those activities.

4. Run the application:

   dotnet run

Upon running, the ConsoleExporter will print the activity details (TraceId, SpanId, Tags, etc.) directly to your terminal.