OpenTelemetry.Instrumentation.GrpcNetClient

Grpc.Net.Client Instrumentation for OpenTelemetry

This is an Instrumentation Library which instruments Grpc.Net.Client and collects traces about outgoing gRPC requests.

This component is based on the OpenTelemetry semantic conventions for traces. These conventions are in Development, and hence, this package is a pre-release. Until a stable version is released, there can be breaking changes.

Supported .NET Versions

This package targets all supported versions of .NET and netstandard2.1 and hence can be used in any .NET versions implementing netstandard2.1.

Steps to enable OpenTelemetry.Instrumentation.GrpcNetClient

Step 1: Install Package

Add a reference to the OpenTelemetry.Instrumentation.GrpcNetClient package. Also, add any other instrumentations & exporters you will need.

dotnet add package --prerelease OpenTelemetry.Instrumentation.GrpcNetClient

Step 2: Enable Grpc.Net.Client Instrumentation at application startup

Grpc.Net.Client instrumentation must be enabled at application startup.

The following example demonstrates adding Grpc.Net.Client instrumentation to a console application. This example also sets up the OpenTelemetry Console exporter and adds instrumentation for HttpClient, which requires adding the packages OpenTelemetry.Exporter.Console and OpenTelemetry.Instrumentation.Http to the application. As Grpc.Net.Client uses HttpClient underneath, it is recommended to enable HttpClient instrumentation as well. This would cause an activity being produced for both a gRPC call and its underlying HTTP call. This behavior can be configured. See Context propagation for how the downstream span is parented.

using OpenTelemetry.Trace;

public class Program
{
    public static void Main(string[] args)
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddGrpcClientInstrumentation()
            .AddHttpClientInstrumentation()
            .AddConsoleExporter()
            .Build();
    }
}

For an ASP.NET Core application, adding instrumentation is typically done in the ConfigureServices of your Startup class. Refer to documentation for OpenTelemetry.Instrumentation.AspNetCore.

Advanced configuration

This instrumentation can be configured to change the default behavior by using GrpcClientInstrumentationOptions.

SuppressDownstreamInstrumentation

SuppressDownstreamInstrumentation does not work with versions 1.6.0 to 1.19.0 of the OpenTelemetry.Instrumentation.Http package.

This option prevents downstream instrumentation from being invoked. Grpc.Net.Client is built on top of HttpClient. When instrumentation for both libraries is enabled, SuppressDownstreamInstrumentation prevents the HttpClient instrumentation from generating an additional activity.

The following example shows how to use SuppressDownstreamInstrumentation.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddGrpcClientInstrumentation(
        opt => opt.SuppressDownstreamInstrumentation = true)
    .AddHttpClientInstrumentation()
    .Build();

Context propagation

Grpc.Net.Client instrumentation propagates context (ActivityContext and Baggage) to downstream services using the configured propagator, so the downstream span is parented to the gRPC client span. When HttpClient instrumentation is also enabled, the downstream span is parented to the HttpClient span with the default propagator, and to the gRPC client span when the propagator is only TraceContextPropagator.

Filter

This instrumentation library provides a Filter option that can be used to filter out activities based on the raw HttpRequestMessage object. The filter function should return true if the telemetry is to be collected, and false or throw an exception if the telemetry is not to be collected.

The following code snippet shows how to use Filter to filter out requests sent to /health.

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddGrpcClientInstrumentation(options =>
        {
            options.Filter = httpRequestMessage =>
            {
                return httpRequestMessage.RequestUri?.AbsolutePath != "/health";
            };
        });

Enrich

This instrumentation library provides EnrichWithHttpRequestMessage and EnrichWithHttpResponseMessage options that can be used to enrich the activity with additional information from the raw HttpRequestMessage and HttpResponseMessage objects respectively. These actions are called only when activity.IsAllDataRequested is true. It contains the activity itself (which can be enriched), the name of the event, and the actual raw object. The following code snippet shows how to add additional tags using these options.

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddGrpcClientInstrumentation(options =>
        {
            options.EnrichWithHttpRequestMessage = (activity, httpRequestMessage) =>
            {
                activity.SetTag("requestVersion", httpRequestMessage.Version);
            };
            options.EnrichWithHttpResponseMessage = (activity, httpResponseMessage) =>
            {
                activity.SetTag("responseVersion", httpResponseMessage.Version);
            };
        });

Processor, is the general extensibility point to add additional properties to any activity. The Enrich option is specific to this instrumentation, and is provided to get access to HttpRequest and HttpResponse.

References

• gRPC for .NET
• OpenTelemetry Project