Instrument a .NET application

The recommended way to instrument your .NET application and send data to Grafana Cloud is to use the Grafana Cloud connection tiles.

If you have advanced setup and configuration needs that the connection tiles don’t cater for you can manually set up instrumentation and ingestion.

Recommended setup

For most use cases, Grafana Labs recommends to use the Grafana Cloud integration tiles to set up and send OpenTelemetry data to Grafana Cloud. This opinionated approach includes all the binaries, connection parameters, and configuration snippets you need to set up OpenTelemetry and Application Observability for .NET applications.

Integration tiles are available to guide you to set up a production architecture with:

The Grafana Labs distribution of the OpenTelemetry SDK for .Net with Grafana Alloy
Grafana Beyla eBPF auto-instrumentation and Grafana Alloy
OpenTelemetry (OTLP) with Grafana Alloy, for an application already instrumented with OpenTelemetry

To use the recommended set up for .NET, refer to the Grafana Cloud, Instrument and send data documentation.

Advanced manual setup

For advanced use cases you can manual set up the packaged release of the Grafana OpenTelemetry distribution for .NET and instrument your application running on Windows or Linux for Grafana Cloud Application Observability. The distribution is a pre-configured bundle of open source OpenTelemetry .NET components, optimized for Grafana Cloud Application Observability.

Before you begin

The is the first step to get telemetry data into Application Observability, you need:

A .NET development environment. Either:
- The dotnet command line application.
- Visual Studio with the NuGet package manager.
A .NET application to instrument built using .NET 6+ or .NET Framework version 4.6.2 or higher.

Install the SDK

Use either the command line or through Visual Studio to install pre-packaged OpenTelemetry SDK from the Grafana OpenTelemetry distribution for .NET.

Command line

Run the following command in the project folder:

dotnet add package Grafana.OpenTelemetry

Additionally, install the console exporter for local testing:

dotnet add package OpenTelemetry.Exporter.Console

Visual Studio

Open a project in Visual Studio and search for and install the Grafana.OpenTelemetry package.

Additionally, install the OpenTelemetry.Exporter.Console package for local testing.

Instrument your application

Choose an option below to see an example of an instrumented application. To instrument your application, review the example and modify your application to match.

Warning
The AddConsoleExporter calls in the sample are only present for local testing purposes. Remove these calls for production applications.

// .NET 6+ console
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
using Grafana.OpenTelemetry;

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .UseGrafana()
    .AddConsoleExporter()
    .Build();
using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .UseGrafana()
    .AddConsoleExporter()
    .Build();
using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.UseGrafana()
            .AddConsoleExporter();
    });
});

// .NET 6+ ASP.NET Core
using Grafana.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .WithTracing(configure =>
    {
        configure.UseGrafana()
            .AddConsoleExporter();
    })
    .WithMetrics(configure =>
    {
        configure.UseGrafana()
            .AddConsoleExporter();
    });
builder.Logging.AddOpenTelemetry(options =>
{
    options.UseGrafana()
        .AddConsoleExporter();
});

// .NET Framework
using Grafana.OpenTelemetry;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

namespace DemoApplication
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        private TracerProvider tracerProvider;
        private MeterProvider meterProvider;

        protected void Application_Start()
        {
            // MVC, Web API, etc. configuration

            tracerProvider = Sdk.CreateTracerProviderBuilder()
                .UseGrafana()
                .Build();
            meterProvider = Sdk.CreateMeterProviderBuilder()
                .UseGrafana()
                .Build();
        }

        protected void Application_End()
        {
            tracerProvider?.Dispose();
            meterProvider?.Dispose();
        }
    }
}

Test your instrumentation

To test if you successfully instrumented your application and are producing telemetry data, run the application. The console output should print references to metrics and logs.

Metric example:

Metric Name: process.cpu.count, The number of processors (CPU cores) available to the current process., Unit: {processors}, Meter: OpenTelemetry.Instrumentation.Process/0.5.0.3
(2024-06-05T02:14:47.6851243Z, 2024-06-05T02:14:57.7092810Z] LongSumNonMonotonic
Value: 12

Log example:

LogRecord.Timestamp:               2024-06-05T02:14:47.9338272Z
LogRecord.CategoryName:            Microsoft.Hosting.Lifetime
LogRecord.Severity:                Info
LogRecord.SeverityText:            Information
LogRecord.Body:                    Now listening on: {address}
LogRecord.Attributes (Key:Value):
    address: http://localhost:5117
    OriginalFormat (a.k.a Body): Now listening on: {address}
LogRecord.EventId:                 14
LogRecord.EventName:               ListeningOnAddress