Skip to content

README updates #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
martincostello merged 1 commit into from
Jun 5, 2025
Merged

README updates #143

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 42 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
<!-- markdownlint-disable -->
# Grafana OpenTelemetry distribution for .NET

<!-- markdownlint-disable MD013 MD033 -->
<p>
<img src="internal/img/Grafana_icon.png" alt="Grafana logo" height="70"/ >
<img src="https://opentelemetry.io/img/logos/opentelemetry-logo-nav.png" alt="OpenTelemetry logo" width="70"/ >
<img src="internal/img/Grafana_icon.png" alt="Grafana logo" height="70" />
<img src="https://opentelemetry.io/img/logos/opentelemetry-logo-nav.png" alt="OpenTelemetry logo" width="70" />
</p>
<!-- markdownlint-enable -->

# Grafana OpenTelemetry distribution for .NET
<!-- markdownlint-enable MD013 MD033 -->

<!-- markdown-link-check-disable -->
[![Build](https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/unit-tests.yml/badge.svg?branch=main)](https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/unit-tests.yml)
[![OATS](https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/oats.yml/badge.svg?branch=main)](https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/oats.yml)
[![NuGet](https://img.shields.io/nuget/v/Grafana.OpenTelemetry?logo=nuget&label=NuGet&color=blue)](https://www.nuget.org/profiles/Grafana)
[![SDK](https://img.shields.io/badge/otel--sdk-1.9.0-blue?style=flat&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-dotnet)
[![Slack](https://img.shields.io/badge/join%20slack-%23app--o11y-brightgreen.svg?logo=slack)](https://grafana.slack.com/archives/C05E87XRK3J)
[![Build][ci-badge]][ci-status]
[![OATS][oats-badge]][oats-status]
[![NuGet][package-badge-version]][package-download]
[![SDK][otel-badge]][otel]
[![Slack][slack-badge]][slack-channel]
<!-- markdown-link-check-enable -->

## About

This is a pre-configured and pre-packaged bundle of [OpenTelemetry .NET components](http://github.com/open-telemetry/opentelemetry-dotnet-contrib),
optimized for [Grafana Cloud Application Observability](https://grafana.com/docs/grafana-cloud/monitor-applications/application-observability/).
This is a pre-configured and pre-packaged bundle of [OpenTelemetry .NET components][otel-contrib],
optimized for [Grafana Cloud Application Observability][app-o11y].

It requires only minimal setup and configuration and makes it very easy to emit
OpenTelemetry metrics, logs, and traces from your .NET application.
Expand All @@ -28,8 +28,7 @@ OpenTelemetry metrics, logs, and traces from your .NET application.
### Step 1: Install package

For installing the distribution with the full set of dependencies, add a
reference to the [`Grafana.OpenTelemetry`](https://www.nuget.org/packages/Grafana.OpenTelemetry)
package to your project.
reference to the [`Grafana.OpenTelemetry`][package] package to your project.

```sh
dotnet add package Grafana.OpenTelemetry
Expand All @@ -39,7 +38,7 @@ dotnet add package Grafana.OpenTelemetry

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 OTel collector
default, telemetry data will be sent to Grafana Alloy or an OpenTelemetry collector
that runs locally and listens to default OTLP ports.

```csharp
Expand All @@ -53,9 +52,8 @@ 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 [Push directly from
applications using the OpenTelemetry
SDKs](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/#push-directly-from-applications-using-the-opentelemetry-sdks).
For details on how to obtain those values, refer to
[Send data to the Grafana Cloud OTLP endpoint: Quickstart architecture][push-oltp].

```sh
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
Expand All @@ -76,10 +74,9 @@ documents:

## Troubleshooting

This project utilizes the [self-diagnostics feature of the .NET OpenTelemetry SDK](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/README.md#self-diagnostics).
This project utilizes the [self-diagnostics feature of the .NET OpenTelemetry SDK][self-diagnostics].

To enable self-diagnostics, go to the
[current working directory](https://en.wikipedia.org/wiki/Working_directory) of
To enable self-diagnostics, go to the [current working directory][working-dir] of
your process and create a configuration file named `OTEL_DIAGNOSTICS.json` with
the following content:

Expand All @@ -98,9 +95,26 @@ To disable self-diagnostics, delete the above file.
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/](https://grafana.slack.com)
and join the [#application-observability](https://grafana.slack.com/archives/C05E87XRK3J)
channel.
* Ask questions on the [Discussions page](https://github.com/grafana/grafana-opentelemetry-dotnet/discussions).
* [File an issue](https://github.com/grafana/grafana-opentelemetry-dotnet/issues/new)
for bugs, issues, and feature suggestions.
Grafana Slack, visit <https://grafana.slack.com>
and join the [#application-observability][slack-channel] channel.
* Ask questions on the [Discussions page][discussions].
* [File an issue][issues] for bugs, issues, and feature suggestions.

[app-o11y]: https://grafana.com/docs/grafana-cloud/monitor-applications/application-observability/
[ci-badge]: https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/unit-tests.yml/badge.svg?branch=main
[ci-status]: https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/unit-tests.yml
[discussions]: https://github.com/grafana/grafana-opentelemetry-dotnet/discussions
[issues]: https://github.com/grafana/grafana-opentelemetry-dotnet/issues/new
[oats-badge]: https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/oats.yml/badge.svg?branch=main
[oats-status]: https://github.com/grafana/grafana-opentelemetry-dotnet/actions/workflows/oats.yml
[otel]: https://github.com/open-telemetry/opentelemetry-dotnet
[otel-badge]: https://img.shields.io/badge/OTel--SDK-1.9.0-blue?style=flat&logo=opentelemetry
[otel-contrib]: http://github.com/open-telemetry/opentelemetry-dotnet-contrib
[package]: https://www.nuget.org/packages/Grafana.OpenTelemetry
[package-badge-version]: https://img.shields.io/nuget/v/Grafana.OpenTelemetry?logo=nuget&label=NuGet&color=blue
[package-download]: https://www.nuget.org/profiles/Grafana
[push-oltp]: https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/#quickstart-architecture
[self-diagnostics]: https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/README.md#self-diagnostics
[slack-badge]: https://img.shields.io/badge/%20Slack-%23app--o11y-brightgreen.svg?logo=slack
[slack-channel]: https://grafana.slack.com/archives/C05E87XRK3J
[working-dir]: https://en.wikipedia.org/wiki/Working_directory
Loading