Instrument a .NET application

The Grafana OpenTelemetry distribution for .NET is our pre-configured and pre-packaged bundle of OpenTelemetry .NET components, optimized for Grafana Cloud Application Observability.

Recommended set up

Grafana Labs recommends you set up instrumentation through the Grafana Cloud connection tiles. This opinionated approach includes all the binaries, configuration, and connection parameters you need to set up OpenTelemetry and Application Observability.

Advanced manual set up

For advanced use cases, follow the rest of this documentation to manually set up and configure OpenTelemetry instrumentation for .NET applications.

Before you begin

Ensure you have a .NET development environment and application 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 the package.

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 the appropriate code tab from below that matches your environment and modify it for your application.

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’ve successfully instrumented your application, run your application, generate some traffic, and you should see metrics and logs outputted to the console.

Example metrics output:

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

Example logs output:

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