opentelemetry-dotnet

OpenTelemetry .NET

The .NET OpenTelemetry implementation.

Table of Contents

• Supported .NET versions
• Project status
• Getting started
  • Getting started with Logging
  • Getting started with Metrics
  • Getting started with Tracing
• 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:

• OpenTelemetry API
• OpenTelemetry SDK
• OpenTelemetry Hosting Extensions

Here are the exporter libraries:

• Console
• In-memory
• OTLP (OpenTelemetry Protocol)
• Prometheus AspNetCore
• Prometheus HttpListener
• Zipkin (Deprecated)

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 announcements 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 artifacts 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 digital signature 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:

Version 1.14.0 and later

These versions are using bundle format known from cosign 3.0+.

TAG="core-1.16.0"
cosign verify-blob \
    --bundle OpenTelemetry.dll.sigstore.json \
    --certificate-identity "https://github.com/open-telemetry/opentelemetry-dotnet/.github/workflows/publish-packages-1.0.yml@refs/tags/$TAG" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
    --use-signed-timestamps \
    OpenTelemetry.dll

[!NOTE] A successful verification outputs Verified OK.

Versions 1.10.0 - 1.14.0-rc.1

These versions are using separate signature and certificate files format known from cosign 2.x.

TAG="core-1.12.0"
cosign verify-blob \
    --signature OpenTelemetry.dll-keyless.sig \
    --certificate OpenTelemetry.dll-keyless.pem \
    --certificate-identity "https://github.com/open-telemetry/opentelemetry-dotnet/.github/workflows/publish-packages-1.0.yml@refs/tags/$TAG" \
    --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.

Attestation

Starting with the 1.14.0 release the DLLs included in the packages pushed to NuGet are attested using GitHub Artifact attestations.

To verify the attestation of a DLL inside a NuGet package use the GitHub CLI:

gh attestation verify --owner open-telemetry .\OpenTelemetry.dll

[!NOTE] A successful verification outputs Verification succeeded!.

For more verification options please refer to the gh attestation verify 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 the #otel-dotnet channel on CNCF Slack. If you are new to the CNCF Slack community, you can create an account.

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!

Maintainers

• Alan West, New Relic
• Martin Costello, Grafana Labs
• Piotr Kiełkowicz, Splunk
• Rajkumar Rangaraj, Microsoft

For more information about the maintainer role, see the community repository.

Approvers

• Cijo Thomas, Microsoft

For more information about the approver role, see the community repository.

Triagers

For more inf