OpenTelemetry .NET

The .NET OpenTelemetry implementation.

<details> <summary>Table of Contents</summary>

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

</details>

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:

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

bash
$TAG="core-1.14.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

Versions 1.10.0 - 1.14.0-rc.1

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

bash
$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:

bash
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!