8.0 KiB

Raw Blame History

OTLP Exporter for OpenTelemetry .NET

The OTLP (OpenTelemetry Protocol) exporter implementation.

Prerequisite

An endpoint capable of accepting OTLP, like OpenTelemetry Collector or similar.

Installation

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Enable Trace Exporter

This exporter provides AddOtlpExporter() extension method on TracerProviderBuilder to enable exporting of traces. The following snippet adds the Exporter with default configuration.

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // rest of config not shown here.
    .AddOtlpExporter()
    .Build();

See the TestOtlpExporter.cs for runnable example.

Enable Metric Exporter

This exporter provides AddOtlpExporter() extension method on MeterProviderBuilder to enable exporting of metrics. The following snippet adds the Exporter with default configuration.

var meterProvider = Sdk.CreateMeterProviderBuilder()
    // rest of config not shown here.
    .AddOtlpExporter()
    .Build();

See the TestMetrics.cs for runnable example.

Enable Log Exporter

This package currently only supports exporting traces and metrics. Support for exporting logs is provided by installing the OpenTelemetry.Exporter.OpenTelemetryProtocol.Logs package.

Once the OTLP log exporter is stable, it'll be folded into this package. Check this milestone for tracking.

Configuration

You can configure the OtlpExporter through OtlpExporterOptions and environment variables. The OtlpExporterOptions type setters take precedence over the environment variables.

This can be achieved by providing an Action<OtlpExporterOptions> delegate to the AddOtlpExporter() method.

TODO: Show metrics specific configuration (i.e MetricReaderOptions).

OtlpExporterOptions

ExportProcessorType: Whether the exporter should use Batch or Simple exporting processor. The default is Batch.
BatchExportProcessorOptions: Configuration options for the batch exporter. Only used if ExportProcessorType is set to Batch.
Protocol: OTLP transport protocol. Supported values: OtlpExportProtocol.Grpc and OtlpExportProtocol.HttpProtobuf. The default is OtlpExportProtocol.Grpc.
Endpoint: Target to which the exporter is going to send traces or metrics. The endpoint must be a valid Uri with scheme (http or https) and host, and MAY contain a port and path. The default is "localhost:4317" for OtlpExportProtocol.Grpc and "localhost:4318" for OtlpExportProtocol.HttpProtobuf.
Headers: Optional headers for the connection.
HttpClientFactory: A factory function called to create the HttpClient instance that will be used at runtime to transmit telemetry over HTTP when the HttpProtobuf protocol is configured. See Configure HttpClient for more details.
TimeoutMilliseconds : Max waiting time for the backend to process a batch.

See the TestOtlpExporter.cs for an example of how to use the exporter.

Environment Variables

The following environment variables can be used to override the default values of the OtlpExporterOptions (following the OpenTelemetry specification).

Environment variable	`OtlpExporterOptions` property
`OTEL_EXPORTER_OTLP_ENDPOINT`	`Endpoint`
`OTEL_EXPORTER_OTLP_HEADERS`	`Headers`
`OTEL_EXPORTER_OTLP_TIMEOUT`	`TimeoutMilliseconds`
`OTEL_EXPORTER_OTLP_PROTOCOL`	`Protocol` (`grpc` or `http/protobuf`)

The following environment variables can be used to override the default values of the PeriodicExportingMetricReaderOptions (following the OpenTelemetry specification.

Environment variable	`PeriodicExportingMetricReaderOptions` property
`OTEL_METRIC_EXPORT_INTERVAL`	`ExportIntervalMilliseconds`
`OTEL_METRIC_EXPORT_TIMEOUT`	`ExportTimeoutMilliseconds`

The following environment variables can be used to override the default values of the attribute limits (following the OpenTelemetry specification).

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT
OTEL_ATTRIBUTE_COUNT_LIMIT

The following environment variables can be used to override the default values of the span limits (following the OpenTelemetry specification).

OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
OTEL_SPAN_EVENT_COUNT_LIMIT
OTEL_SPAN_LINK_COUNT_LIMIT
OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT
OTEL_LINK_ATTRIBUTE_COUNT_LIMIT

Configure HttpClient

The HttpClientFactory option is provided on OtlpExporterOptions for users who want to configure the HttpClient used by the OtlpTraceExporter and/or OtlpMetricExporter when HttpProtobuf protocol is used. Simply replace the function with your own implementation if you want to customize the generated HttpClient:

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddOtlpExporter(o =>
        {
            o.Protocol = OtlpExportProtocol.HttpProtobuf;
            o.HttpClientFactory = () =>
            {
                HttpClient client = new HttpClient();
                client.DefaultRequestHeaders.Add("X-MyCustomHeader", "value");
                return client;
            };
        }));

For users using IHttpClientFactory you may also customize the named "OtlpTraceExporter" and/or "OtlpMetricExporter" HttpClient using the built-in AddHttpClient extension:

services.AddHttpClient(
    "OtlpTraceExporter",
    configureClient: (client) =>
        client.DefaultRequestHeaders.Add("X-MyCustomHeader", "value"));

Note: The single instance returned by HttpClientFactory is reused by all export requests.

Troubleshooting

This component uses an EventSource with the name "OpenTelemetry-Exporter-OpenTelemetryProtocol" for its internal logging. Please refer to SDK troubleshooting for instructions on seeing these internal logs.

8.0 KiB Raw Blame History