Send Data with the OpenTelemetry .NET SDK

Use the OpenTelemetry .NET SDK to instrument .NET applications in a standard, vendor-agnostic, and future-proof way and send telemetry data to Honeycomb. In this guide, we will walk you through instrumenting with OpenTelemetry for .NET, which will include adding automatic instrumentation to your application.

Before You Begin

Before you can set up automatic instrumentation for your .NET application, you will need to do a few things.

Prepare Your Development Environment

To complete the required steps, you will need:

A working .NET environment
An application written in .NET

Get Your Honeycomb API Key

To send data to Honeycomb, you’ll need to sign up for a free Honeycomb account and create a Honeycomb Ingest API Key. To get started, you can create a key that you expect to swap out when you deploy to production. Name it something helpful, perhaps noting that it’s a getting started key. Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later!

For setup, make sure you check the “Can create datasets” checkbox so that your data will show up in Honeycomb. Later, when you replace this key with a permanent one, you can uncheck that box.

If you want to use an API key you previously stored in a secure location, you can also look up details for Honeycomb API Keys any time in your Environment Settings, and use them to retrieve keys from your storage location.

Add Automatic Instrumentation

Automatic instrumentation is enabled by adding instrumentation packages. Add custom, or manual, instrumentation using the OpenTelemetry API.

Acquire Dependencies

Install the OpenTelemetry .NET packages. For example, with the .NET CLI, use:

dotnet add package OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http

Initialize

Initialize the TracerProvider during application setup.

services.AddOpenTelemetry().WithTracing(builder => builder
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddOtlpExporter());

Configure

Use environment variables to configure the OpenTelemetry SDK:

export OTEL_SERVICE_NAME="your-service-name"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.honeycomb.io:443" # US instance
#export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.eu1.honeycomb.io:443" # EU instance
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<your-api-key>"

Variable	Description
`OTEL_SERVICE_NAME`	Service name. When you send data, Honeycomb creates a dataset in which to store your data and uses this as the name. Can be any string.
`OTEL_EXPORTER_OTLP_PROTOCOL`	The data format that the SDK uses to send telemetry to Honeycomb. For more on data format configuration options, read Choosing between gRPC and HTTP.
`OTEL_EXPORTER_OTLP_ENDPOINT`	Honeycomb endpoint to which you want to send your data.
`OTEL_EXPORTER_OTLP_HEADERS`	Adds your Honeycomb API Key to the exported telemetry headers for authorization. Learn how to find your Honeycomb API Key.

Run

Run your application. You will see the incoming requests and outgoing HTTP calls generate traces.

dotnet run

In Honeycomb’s UI, you should now see your application’s incoming requests and outgoing HTTP calls generate traces.

Add Custom Instrumentation

Automatic instrumentation is the easiest way to get started with instrumenting your code. To get additional insight into your system, you should also add custom, or manual, instrumentation where appropriate. Follow the instructions below to add custom instrumentation to your code. To learn more about custom, or manual, instrumentation, visit the comprehensive set of topics covered by Manual Instrumentation for .NET in OpenTelemetry’s documentation, including the System.Diagnostics API and the OpenTelemetry Shim.

Add Attributes to Spans

Adding attributes to a currently executing span in a trace can be useful. For example, you may have an application or service that handles users and you want to associate the user with the span when querying your dataset in Honeycomb. To do this, get the current span from the context and set an attribute with the user ID:

using OpenTelemetry.Trace;

//...

var currentSpan = Tracer.CurrentSpan;
currentSpan.SetAttribute("user.id", User.GetUserId())

This configuration will add a user.id attribute to the current span, so you can use the field in WHERE, GROUP BY, or ORDER clauses in the Honeycomb query builder.

Acquire a Tracer

To create spans, you need to acquire a Tracer.

using OpenTelemetry.Trace;

//...

var tracer = TracerProvider.Default.GetTracer("tracer.name.here");

Then, inject the Tracer instance with ASP.NET Core dependency injection or manage its lifecycle manually. When you create a Tracer, OpenTelemetry requires you to give it a name as a string. This string is the only required parameter. When traces are sent to Honeycomb, the name of the Tracer is turned into the library.name field, which can be used to show all spans created from a particular tracer. In general, pick a name that matches the appropriate scope for your traces. If you have one tracer for each service, then use the service name. If you have multiple tracers that live in different “layers” of your application, then use the name that corresponds to that “layer”. The library.name field is also used with traces created from instrumentation libraries.

Create New Spans

To get the full picture of what is happening, you can leverage manual instrumentation to create custom spans that describe what is happening in your application. To do this, grab your tracer instance and use it to create a span:

using OpenTelemetry.Trace;

//...

using var span = TracerProvider.Default.GetTracer("my-service").StartActiveSpan("expensive-query")
// ... do cool stuff

Add Multi-Span Attributes

Sometimes you want to add the same attribute to many spans within the same trace. This attribute may include variables calculated during your program, or other useful values for correlation or debugging purposes. To add this attribute to multiple spans, leverage the OpenTelemetry concept of baggage. Baggage allows you to add a key with a value as an attribute to every subsequent child span of the current application context.

Install the OpenTelemetry.Extensions package with the .NET CLI:
dotnet add package OpenTelemetry.Extensions --prerelease

When configuring the OpenTelemetry SDK tracer provider, add the BaggageActivityProcessor:

services.AddOpenTelemetry().WithTracing(builder => builder
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(serviceName))
    .AddBaggageActivityProcessor()
    .AddOtlpExporter(option =>
    {
        option.Endpoint = new Uri("https://api.honeycomb.io"); // US instance
        //option.Endpoint = new Uri("https://api.eu1.honeycomb.io"); // EU instance
        option.Headers = $"x-honeycomb-team={honeycombApiKey}";
    }));

Add a baggage entry for the current trace and replace key and value with your desired key-value pair:
Baggage.Current.SetBaggage("key", "value");
Any Baggage attributes that you set in your application will be attached to outgoing network requests as a header. If your service communicates to a third party API, do NOT put sensitive information in the Baggage attributes.

Sampling

You can configure the OpenTelemetry SDK to sample the data it generates. Honeycomb weights sampled data based on sample rate, so you must set a resource attribute containing the sample rate. Use a TraceIdRatioBased sampler, with a ratio expressed as 1/N. Then, also create a resource attribute called SampleRate with the value of N. This allows Honeycomb to reweigh scalar values, like counts, so that they are accurate even with sampled data. In the example below, our goal is to keep approximately half (1/2) of the data volume. The resource attribute contains the denominator (2), while the OpenTelemetry sampler argument contains the decimal value (0.5).

services.AddOpenTelemetry().WithTracing((builder) => builder
    .SetResourceBuilder(ResourceBuilder.CreateDefault()
        .AddService(serviceName)
        // IMPORTANT: add a SampleRate of 2 as a resource attribute
        .AddAttributes(new[] { new KeyValuePair<string, object>("SampleRate", 2) })
    )
    .SetSampler(new TraceIdRatioBasedSampler(0.5)) // sampler
    .AddAspNetCoreInstrumentation()
    .AddHttpClientInstrumentation()
    .AddOtlpExporter(option =>
    {
        option.Endpoint = new Uri("https://api.honeycomb.io"); // US instance
        //option.Endpoint = new Uri("https://api.eu1.honeycomb.io"); // EU instance
        option.Headers = $"x-honeycomb-team={honeycombApiKey}";
    }));

Choosing between gRPC and HTTP

Most OpenTelemetry SDKs have an option to export telemetry as OTLP either over gRPC or HTTP/protobuf, with some also offering HTTP/JSON. If you are trying to choose between gRPC and HTTP, keep in mind:

Some SDKs default to using gRPC, and it may be easiest to start with the default option.
Some firewall policies are not set up to handle gRPC and require using HTTP.
gRPC may improve performance, but its long-lived connections may cause problems with load balancing, especially when using Refinery.

gRPC default export uses port 4317, whereas HTTP default export uses port 4318.

Endpoint URLs for OTLP/HTTP

When using the OTEL_EXPORTER_OTLP_ENDPOINT environment variable with an SDK and an HTTP exporter, the final path of the endpoint is modified by the SDK to represent the specific signal being sent. For example, when exporting trace data, the endpoint is updated to append v1/traces. When exporting metrics data, the endpoint is updated to append v1/metrics. So, if you were to set the OTEL_EXPORTER_OTLP_ENDPOINT to https://api.honeycomb.io, traces would be sent to https://api.honeycomb.io/v1/traces and metrics would be sent to https://api.honeycomb.io/v1/metrics. The same modification is not necessary for gRPC.

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io # US instance
#export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.eu1.honeycomb.io # EU instance

If the desired outcome is to send data to a different endpoint depending on the signal, use OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT instead of the more generic OTEL_EXPORTER_OTLP_ENDPOINT. When using a signal-specific environment variable, these paths must be appended manually. Set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT for traces, appending the endpoint with v1/traces, and OTEL_EXPORTER_OTLP_METRICS_ENDPOINT for metrics, appending the endpoint with v1/metrics. Send both traces and metrics to Honeycomb using this method by setting the following variables:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.honeycomb.io/v1/traces # US instance
#export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.eu1.honeycomb.io/v1/traces # EU instance

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.honeycomb.io/v1/metrics # US instance
#export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.eu1.honeycomb.io/v1/metrics # EU instance

More details about endpoints and signals can be found in the OpenTelemetry Specification.

URL Query String Parameter Value Redaction

The Instrumentation.AspNetCore-1.8.1 and Instrumentation.Http-1.8.1 instrumentation packages redact query string parameter values by default. For example, a query string parameter of key=value would be added as a span attribute with a name of url.query and a value of key=Redacted. You can disable this redaction by setting the environment variable OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION to true.

Troubleshooting

To explore common issues when sending data, visit Common Issues with Sending Data in Honeycomb.

Send Data with AI

Instrument Applications

Instrument Infrastructure

CI/CD Observability

Manage Pipelines

Shape Data

Control Data Volume

Use Cases

Send Data with the OpenTelemetry .NET SDK

Before You Begin

Prepare Your Development Environment

Get Your Honeycomb API Key

Add Automatic Instrumentation

Acquire Dependencies

Initialize

Configure

Run

Add Custom Instrumentation

Add Attributes to Spans

Acquire a Tracer

Create New Spans

Add Multi-Span Attributes

Sampling

Choosing between gRPC and HTTP

Endpoint URLs for OTLP/HTTP

URL Query String Parameter Value Redaction

Troubleshooting

​Before You Begin

​Prepare Your Development Environment

​Get Your Honeycomb API Key

​Add Automatic Instrumentation

​Acquire Dependencies

​Initialize

​Configure

​Run

​Add Custom Instrumentation

​Add Attributes to Spans

​Acquire a Tracer

​Create New Spans

​Add Multi-Span Attributes

​Sampling

​Choosing between gRPC and HTTP

​Endpoint URLs for OTLP/HTTP

​URL Query String Parameter Value Redaction

​Troubleshooting

Before You Begin

Prepare Your Development Environment

Get Your Honeycomb API Key

Add Automatic Instrumentation

Acquire Dependencies

Initialize

Configure

Run

Add Custom Instrumentation

Add Attributes to Spans

Acquire a Tracer

Create New Spans

Add Multi-Span Attributes

Sampling

Choosing between gRPC and HTTP

Endpoint URLs for OTLP/HTTP

URL Query String Parameter Value Redaction

Troubleshooting