OpenTelemetry .NET

The .NET OpenTelemetry implementation.

Table of Contents

Supported .NET versions
Project status
Getting started
Repository structure
Troubleshooting
Extensibility
Releases
Contributing
References

Supported .NET versions

Packages shipped from this repository generally support all the officially supported versions of .NET and .NET Framework (an older Windows-based .NET implementation), except .NET Framework 3.5. Any exceptions to this are noted in the individual README.md files.

Project status

Stable across all 3 signals (Logs, Metrics, and Traces).

Caution

Certain components, marked as pre-release, are still work in progress and can undergo breaking changes before stable release. Check the individual README.md file for each component to understand its current state.

To understand which portions of the OpenTelemetry Specification have been implemented in OpenTelemetry .NET see: Spec Compliance Matrix.

Getting started

If you are new here, please read the getting started docs:

Getting started with Logging

If you are new to logging, it is recommended to first follow the getting started in 5 minutes - ASP.NET Core Application guide or the getting started in 5 minutes - Console Application guide to get up and running.

For general information and best practices see: OpenTelemetry .NET Logs. For a more detailed explanation of SDK logging features see: Customizing OpenTelemetry .NET SDK for Logs.

Getting started with Metrics

If you are new to metrics, it is recommended to first follow the getting started in 5 minutes - ASP.NET Core Application guide or the getting started in 5 minutes - Console Application guide to get up and running.

For general information and best practices see: OpenTelemetry .NET Metrics. For a more detailed explanation of SDK metric features see: Customizing OpenTelemetry .NET SDK for Metrics.

Getting started with Tracing

If you are new to traces, it is recommended to first follow the getting started in 5 minutes - ASP.NET Core Application guide or the getting started in 5 minutes - Console Application guide to get up and running.

For general information and best practices see: OpenTelemetry .NET Traces. For a more detailed explanation of SDK tracing features see: Customizing OpenTelemetry .NET SDK for Tracing.

Repository structure

This repository includes only what is defined in the OpenTelemetry Specification and is shipped as separate packages through NuGet. Each component has an individual README.md and CHANGELOG.md file which covers the instructions on how to install and get started, and details about the individual changes made (respectively). To find all the available components, please take a look at the src folder.

Here are the most commonly used components:

Here are the exporter libraries:

Additional packages including instrumentation libraries, exporters, resource detectors, and extensions can be found in the opentelemetry-dotnet-contrib repository and/or the OpenTelemetry registry.

Troubleshooting

For general instructions see: Troubleshooting. Additionally README.md files for individual components may contain more detailed troubleshooting information.

Extensibility

OpenTelemetry .NET is designed to be extensible. Here are the most common extension scenarios:

Building a custom instrumentation library.
Building a custom exporter for logs, metrics, and traces.
Building a custom processor for logs and traces.
Building a custom sampler for traces.

Releases

For details about upcoming planned releases see: Milestones. The dates and features described in issues and milestones are estimates and subject to change.

For highlights and annoucements for stable releases see: Release Notes.

To access packages, source code, and/or view a list of changes for all components in a release see: Releases.

Nightly builds from this repo are published to MyGet, and can be installed using the https://www.myget.org/F/opentelemetry/api/v3/index.json source.

Digital signing

Starting with the 1.10.0 release the DLLs included in the packages pushed to NuGet are digitally signed using Sigstore. Within each NuGet package the digital signature and its corresponding certificate file are placed alongside the shipped DLL(s) in the /lib folder. When a project targets multiple frameworks each target outputs a dedicated DLL and signing artifacts into a sub folder based on the TFM.

The digitial signature and certificate files share the same name prefix as the DLL to ensure easy identification and association.

To verify the integrity of a DLL inside a NuGet package use the cosign tool from Sigstore:

cosign verify-blob \
    --signature OpenTelemetry.dll-keyless.sig \
    --certificate OpenTelemetry.dll-keyless.pem.cer \
    --certificate-identity "https://github.com/open-telemetry/opentelemetry-dotnet/.github/workflows/publish-packages-1.0.yml@refs/tags/core-1.10.0-rc.1" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
    OpenTelemetry.dll

Note

A successful verification outputs Verify OK.

For more verification options please refer to the cosign documentation.

Contributing

For information about contributing to the project see: CONTRIBUTING.md.

We meet weekly on Tuesdays, and the time of the meeting alternates between 9AM PT and 4PM PT. The meeting is subject to change depending on contributors' availability. Check the OpenTelemetry community calendar for specific dates and for Zoom meeting links.

Meeting notes are available as a public Google doc. If you have trouble accessing the doc, please get in touch on Slack.

The meeting is open for all to join. We invite everyone to join our meeting, regardless of your experience level. Whether you're a seasoned OpenTelemetry developer, just starting your journey, or simply curious about the work we do, you're more than welcome to participate!