Integrating OpenTelemetry with .NET applications

Edit online

You can use the Instana OTLP Exporter package for integrating OpenTelemetry with Instana in .NET and .NET Framework applications. This exporter provides seamless integration between OpenTelemetry instrumentation and Instana native tracing capabilities. It automatically correlates OpenTelemetry traces with Instana traces for unified distributed tracing across your applications. It is designed to work with Instana AutoTracing, enabling you to combine OpenTelemetry instrumentation with Instana automatic tracing capabilities.

Alternatively, you can configure the standard OTLP exporter to send data directly to the Instana agent, as described on the OpenTelemetry page. However, the Instana OTLP Exporter is the preferred method for .NET and .NET Framework applications as it ensures proper trace correlation.

Overview
Supported platforms
Installing the exporter
Configuring the exporter

Overview

Edit online

The Instana OTLP Exporter is a specialized OpenTelemetry exporter that provides seamless integration between OpenTelemetry instrumentation and Instana. It provides the following capabilities:

Automatic trace correlation: Correlates OpenTelemetry traces with Instana traces
Flexible protocol support: Supports both gRPC and HTTP-Protobuf protocols
Configurable export modes: Allows selection between simple or batch export processing
Environment variable configuration: Supports configuration through environment variables
Custom headers support: Enables adding custom headers to OTLP export requests
Batch processing options: Supports configuration of batch size, queue size, and scheduling delays for optimal performance

The Instana OTLP Exporter provides the following benefits:

Unified tracing: OpenTelemetry spans are automatically correlated with Instana traces, providing a complete view of your distributed system
Seamless integration: Works with existing OpenTelemetry instrumentation without requiring code changes
Full visibility: All trace data is visible in the Instana UI with proper correlation across services
Flexible deployment: Supports multiple protocols and configuration options to fit your infrastructure

For more information about OpenTelemetry integration, see the OpenTelemetry documentation.

Supported platforms

Edit online

The Instana OTLP Exporter supports the following .NET platforms:


Platform	Support status
.NET Framework 4.6.2 and later	GA
.NET Standard 2.0	GA
.NET 5.0 and later	GA

Note: On .NET Framework and .NET Standard, only the HTTP-Protobuf protocol is supported. The gRPC protocol is available on .NET 5.0 and later.

Installing the exporter

Edit online

You can install the Instana OTLP Exporter NuGet package in one of the following ways:

Install in your .NET project:

dotnet add package Instana.OpenTelemetry.Otlp.Exporter

Add the package to your project file:

<PackageReference Include="Instana.OpenTelemetry.Otlp.Exporter" Version="<latest-version>" />

Configuring the exporter

Edit online

To configure the Instana OTLP Exporter in your application, add it to your OpenTelemetry TracerProvider configuration:

Basic configuration

Edit online

using OpenTelemetry;
using OpenTelemetry.Trace;
using Instana.OpenTelemetry.Otlp.Exporter;

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyApplication")
    .AddInstanaOtlpExporter()
    .Build();

Configuration with options

Edit online

using OpenTelemetry;
using OpenTelemetry.Trace;
using Instana.OpenTelemetry.Otlp.Exporter;

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyApplication")
    .AddInstanaOtlpExporter(options =>
    {
        options.Endpoint = new Uri("http://instana-agent:4317");
        options.Protocol = InstanaOtlpProtocol.Grpc;
    })
    .Build();

The InstanaOtlpExportOptions class provides the following configuration properties:


Property	Type	Default	Description
`Endpoint`	`Uri`	`http://localhost:4317` (.NET 5+) `http://localhost:4318/v1/traces` (.NET Framework or .NET Standard)	The OTLP endpoint URL. Replace `localhost` with your Instana agent URL. If not set, the environment variable or the default value is used.
`Protocol`	`InstanaOtlpProtocol`	`Grpc` (.NET 5+) `HttpProtobuf` (.NET Framework or .NET Standard)	The protocol to use: `Grpc` or `HttpProtobuf`. If not set, the environment variable or the default value is used.
`Headers`	`IDictionary<string, string>`	Empty dictionary	Custom headers to include in export requests.
`TimeoutMilliseconds`	`int`	`10000`	The timeout for export requests in milliseconds.
`ExportProcessorType`	`InstanaExportProcessorType`	`Batch`	The export processor type: `Simple` or `Batch`.
`MaxQueueSize`	`int`	`2048`	Maximum queue size for batch processing.
`MaxExportBatchSize`	`int`	`512`	Maximum batch size for batch processing.
`ScheduledDelayMilliseconds`	`int`	`5000`	Delay between batch exports in milliseconds.

Note: When you configure the Endpoint property, replace localhost with the hostname or IP address of your Instana agent. For example, use http://instana-agent:4317 for .NET 5+ with gRPC, or http://instana-agent:4318/v1/traces for .NET Framework or .NET Standard with HTTP-Protobuf.

Protocol options

The InstanaOtlpProtocol enum provides the following values:

Grpc: Use gRPC protocol (available on .NET 5.0 and later)
HttpProtobuf: Use HTTP with Protobuf encoding (available on all platforms)

Note: On .NET Framework and .NET Standard, the exporter automatically uses HttpProtobuf even if Grpc is specified.

Export processor types

The InstanaExportProcessorType enum provides the following values:

Simple: Exports spans immediately as they are completed
Batch: Batches spans and exports them periodically (suggested for production)

Configuration through environment variables

Edit online

The Instana OTLP Exporter supports configuration through environment variables:


Environment variable	Description	Example
INSTANA_EXPORTER_OTLP_ENDPOINT	The OTLP endpoint URL	`http://instana-agent:4317`
INSTANA_EXPORTER_OTLP_PROTOCOL	The protocol to use: `grpc` or `http/protobuf`	`grpc`

Note: Environment variables are applied only if the corresponding option is not explicitly set in code. Explicitly configured options take precedence over environment variables.

Example: Using environment variables

Set the environment variables before starting your application:

Windows (PowerShell):

$env:INSTANA_EXPORTER_OTLP_ENDPOINT = "http://instana-agent:4317"
$env:INSTANA_EXPORTER_OTLP_PROTOCOL = "grpc"

Linux/macOS:

export INSTANA_EXPORTER_OTLP_ENDPOINT=http://instana-agent:4317
export INSTANA_EXPORTER_OTLP_PROTOCOL=grpc

Configure the exporter without explicit options:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyApplication")
    .AddInstanaOtlpExporter()
    .Build();