Instrument a .NET application

Follow this article to install the latest 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 --prerelease Grafana.OpenTelemetry

Additionally, install the console exporter for local testing:

dotnet add package --prerelease OpenTelemetry.Exporter.Console

Visual Studio

With the chosen project open in Visual Studio, open the NuGet package manager and enable the Include prelease search filter. Then 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