Grafana OpenTelemetry distribution for .NET

About

This is a pre-configured and pre-packaged bundle of OpenTelemetry .NET components, optimized for Grafana Cloud Application Observability.

It requires only minimal setup and configuration and makes it very easy to emit OpenTelemetry metrics, logs, and traces from your .NET application.

Getting Started

Step 1: Install package

For installing the distribution with the full set of dependencies, add a reference to the Grafana.OpenTelemetry package to your project.

dotnet add package Grafana.OpenTelemetry

Step 2: Enable the Grafana distribution at application startup

The UseGrafana extension method on the TracerProviderBuilder or the MetricProviderBuilder can be used to set up the Grafana distribution. By default, telemetry data will be sent to Grafana Alloy or an OpenTelemetry collector that runs locally and listens to default OTLP ports.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .UseGrafana()
    .Build();

Alternatively, you can send telemetry data directly to Grafana Cloud without involving an agent or collector. This can be configured via the environment variables OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_ENDPOINT, and OTEL_EXPORTER_OTLP_HEADERS.

For details on how to obtain those values, refer to Send data to the Grafana Cloud OTLP endpoint: Quickstart architecture.

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic base64-encoded-token"

Tip

The token for Basic authentication is the base64-encoded value of a Grafana Cloud Instance ID and a service account token separated by a :.

For example, if your Grafana Cloud Instance ID is 12345 and your token is glc_secret, the value for OTEL_EXPORTER_OTLP_HEADERS would be Authorization=Basic MTIzNDU6Z2xjX3NlY3JldA==

Documentation

For detailed documentation and setup instructions, refer to the following documents:

• Installation
• Configuration
• Supported instrumentations
• Supported resource detectors
• Migrating to upstream

Troubleshooting

This project utilizes the self-diagnostics feature of the .NET OpenTelemetry SDK.

To enable self-diagnostics, go to the current working directory of your process and create a configuration file named OTEL_DIAGNOSTICS.json with the following content:

{
    "LogDirectory": ".",
    "FileSize": 32768,
    "LogLevel": "Warning"
}

To disable self-diagnostics, delete the above file.

Community

To engage with the Grafana Application Observability community:

• Chat with us on our community Slack channel. To invite yourself to the Grafana Slack, visit https://grafana.slack.com and join the #application-observability channel.
• Ask questions on the Discussions page.
• File an issue for bugs, issues, and feature suggestions.

Prerelease Packages

We publish prerelease packages to feedz.io for testing and feedback purposes from our repository's continuous integration in GitHub Actions.

These package versions may contain new features or changes that are not yet available in a stable release, which you can use to test the latest functionality with your applications ahead of them being published as part of a stable release to NuGet.org.

To install a prerelease version of our NuGet package, perform the following steps.

First, add/update your NuGet configuration file (e.g., NuGet.config) to include our custom NuGet package source:

<configuration>
  <packageSources>
    <add key="grafana-opentelemetry-dotnet" value="https://f.feedz.io/grafana/grafana-opentelemetry-dotnet/nuget/index.json" />
  </packageSources>
</configuration>

Then, run the following command to add a package reference to the latest prerelease version in feedz.io to the appropriate project(s) in your application:

dotnet add package Grafana.OpenTelemetry --prerelease

Important

Our prerelease package versions are provided solely for the purposes of early feedback.

These package versions are not supported for use in production applications.