DocumentationGrafana CloudMonitor applicationsApplication ObservabilityInstrumentation setupInstrument.NET

Set up production instrumentation for .NET

Follow these steps set up production Application Observability with a telemetry collector:

1. Install the instrumentation library
2. Configure an application
3. Set up a telemetry data collector
4. Run the application
5. Observe the service in Application Observability

Install the instrumentation library

Install the latest release of the Grafana OpenTelemetry Distribution for .NET.

To install the distribution with the full set of dependencies, add a reference to the Grafana.OpenTelemetry package to a project.

sh Copy

dotnet add package --prerelease Grafana.OpenTelemetry

Configure an application to use the UseGrafana extension method on a TracerProviderBuilder and a MetricProviderBuilder:

csharp Copy

using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
using Grafana.OpenTelemetry;

public class Program
{
    public static void Main(string[] args)
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .UseGrafana()
            .Build();
        using var meterProvider = Sdk.CreateMeterProviderBuilder()
            .UseGrafana()
            .Build();
    }
}

Configure an application

Next, customize the following shell script to configure an application:

shell Copy

export OTEL_SERVICE_NAME=<Service Name>
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<Environment>,service.namespace=<Namespace>,service.version=<Version>,service.instance.id=<Instance>

dotnet run

1. Choose a Service Name to identify the service, for example cart
2. Add attributes to filter data:
   • deployment.environment: Name of the deployment environment (staging or production)
   • service.namespace: A namespace to group similar services (e.g. shop would create shop/cart in Application Observability)
   • service.version: The application version, to see if a new version has introduced a bug
   • service.instance.id: The unique instance, for example the Pod name (a UUID is generated by default)

Set up a telemetry data collector

In production environments, a robust and flexible observability setup needs to process telemetry data before ingestion into databases. Follow the collector setup documentation to set up a collector to process and send telemetry data to Application Observability.

Finally, set the following environment variables from the exporter configuration:

For example, for a local Grafana Alloy:

shell Copy

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Run the application

Finally, run the application with the shell script and make some requests to the service to send data to Grafana Cloud.

Observe the service in Application Observability

Open Application observability:

1. Navigate to a stack https://<your-stack-name.>grafana.net
2. Expand the top left menu below the Grafana logo
3. Click on Application

Activate metrics generation

Application Observability relies on metrics generated from traces already sent to Grafana Cloud Traces.

Metrics generation is self-serve, and can be enabled during onboarding and disabled from Application Observability configuration.

To complete the setup, click Activate Application Observability to enable metrics generation.

Visualize and discover

Discover more about Application Observability in the documentation:

• Service Inventory: filter, and search services and view RED metrics.
• Service Overview: traces, logs, RED metrics, operations, and runtime information.
• Service Map: graph of connected services, service dependencies, and data flow.

Configuration options

The Grafana OpenTelemetry .NET distribution can be configured with the standard OTLP exporter environment variables.

Additional distribution specific configuration options are also available.

Enabling self-diagnostics

To enable self-diagnostics, go to the current working directory of the process and create a configuration file named OTEL_DIAGNOSTICS.json with the following content:

json Copy

{
  "LogDirectory": ".",
  "FileSize": 32768,
  "LogLevel": "Warning"
}

While enabled, diagnostic logs will be written to the same directory.

To disable self-diagnostics, delete the file OTEL_DIAGNOSTICS.json.

Troubleshooting

If services are not visible in Application Observability, these are the most common causes:

No traffic

Make a few requests to the service to send data to Grafana Cloud.

Be patient

It can take up to 5 minutes until the data is visible in Application Observability.

Look for errors

Look for errors - either on the console or in Docker or Kubernetes logs, using Application Observability logs doesn’t make sense in this case.

If there are errors sending telemetry data, one of the parameters is usually wrong.

A 5xx response code means that there’s something wrong with the Grafana Cloud OTLP Gateway.

Check diagnostic logs

Enable self-diagnostic logging to verify the application is sending data. The log files will be written to the same directory as the process.

Log exporter data

If the application is sending data to a data collector (Grafana Agent or OpenTelemetry Collector), log the data there and check there are no errors forwarding the telemetry data to Grafana Cloud.

Migrating to upstream

All functionality provided by the Grafana OpenTelemetry distribution for .NET can also be utilized by manually installing and configuring upstream OpenTelemetry .NET packages. Follow these steps to migrate from this distribution to the upstream OpenTelemetry .NET project.

• Replace all environment variables or web.config/app.config values with the “grafana” prefix as explained here
• Install and activate the OpenTelemetry SDK, as covered in the upstream Getting Started guide
• Setup the OTLP exporter for metrics, logs, and traces - see the exporter README for details. The exporter will respect the previously set environment variables:
  • OTEL_EXPORTER_OTLP_PROTOCOL
  • OTEL_EXPORTER_OTLP_ENDPOINT
• Install and configure any desired instrumentation packages listed here
• Add the recommended OpenTelemetry resource attributes via the OTEL_RESOURCE_ATTRIBUTES environment variable
  • service.name
  • service.namespace
  • service.instance.id
  • service.version
  • deployment.environment

shell Copy

export OTEL_RESOURCE_ATTRIBUTES=service.instance.id=<pod123>,deployment.environment=...