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.
- The
- 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
TheAddConsoleExporter
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
Next steps
- Create a free Grafana Cloud account
- Configure your telemetry data destination:
- Grafana Cloud OTLP endpoint: for a quick local development and testing setup
- OpenTelemetry Collector: for a robust and scalable production setup
- Observe your services in Application Observability