# Exporters Send telemetry to the [OpenTelemetry Collector](/docs/collector/) to make sure it's exported correctly. Using the Collector in production environments is a best practice. To visualize your telemetry, export it to a backend such as [Jaeger](https://jaegertracing.io/), [Zipkin](https://zipkin.io/), [Prometheus](https://prometheus.io/), or a [vendor-specific](/ecosystem/vendors/) backend. ## Available exporters The registry contains a [list of exporters for .NET][reg]. Among exporters, [OpenTelemetry Protocol (OTLP)][OTLP] exporters are designed with the OpenTelemetry data model in mind, emitting OTel data without any loss of information. Furthermore, many tools that operate on telemetry data support OTLP (such as [Prometheus][], [Jaeger][], and most [vendors][]), providing you with a high degree of flexibility when you need it. To learn more about OTLP, see [OTLP Specification][OTLP]. [Jaeger]: /blog/2022/jaeger-native-otlp/ [OTLP]: /docs/specs/otlp/ [Prometheus]: https://prometheus.io/docs/prometheus/2.55/feature_flags/#otlp-receiver [reg]: [vendors]: /ecosystem/vendors/ This page covers the main OpenTelemetry .NET exporters and how to set them up. > [!NOTE] > > If you use [zero-code instrumentation](), > you can learn how to set up exporters by following the > [Configuration Guide](). ## OTLP ### Collector Setup > [!NOTE] > > If you have a OTLP collector or backend already set up, you can skip this > section and [setup the OTLP exporter dependencies](#otlp-dependencies) for > your application. To try out and verify your OTLP exporters, you can run the collector in a docker container that writes telemetry directly to the console. In an empty directory, create a file called `collector-config.yaml` with the following content: ```yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: debug: verbosity: detailed service: pipelines: traces: receivers: [otlp] exporters: [debug] metrics: receivers: [otlp] exporters: [debug] logs: receivers: [otlp] exporters: [debug] ``` Now run the collector in a docker container: ```shell docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector ``` This collector is now able to accept telemetry via OTLP. Later you may want to [configure the collector](/docs/collector/configuration) to send your telemetry to your observability backend. {{__hugo_ctx/}} ## Dependencies {#otlp-dependencies} If you want to send telemetry data to an OTLP endpoint (like the [OpenTelemetry Collector](#collector-setup), [Jaeger](#jaeger) or [Prometheus](#prometheus)), you can choose between two different protocols to transport your data: - HTTP/protobuf - gRPC Start by installing the [`OpenTelemetry.Exporter.OpenTelemetryProtocol`](https://www.nuget.org/packages/OpenTelemetry.Exporter.OpenTelemetryProtocol/) package as a dependency for your project: ```sh dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol ``` If you're using ASP.NET Core install the [`OpenTelemetry.Extensions.Hosting`](https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting) package as well: ```sh dotnet add package OpenTelemetry.Extensions.Hosting ``` ## Usage ### ASP.NET Core Configure the exporters in your ASP.NET Core services: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .WithTracing(tracing => tracing // The rest of your setup code goes here .AddOtlpExporter()) .WithMetrics(metrics => metrics // The rest of your setup code goes here .AddOtlpExporter()); builder.Logging.AddOpenTelemetry(logging => { // The rest of your setup code goes here logging.AddOtlpExporter(); }); ``` This will, by default, send telemetry using gRPC to , to customize this to use HTTP and the protobuf format, you can add options like this: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .WithTracing(tracing => tracing // The rest of your setup code goes here .AddOtlpExporter(options => { options.Endpoint = new Uri("your-endpoint-here/v1/traces"); options.Protocol = OtlpExportProtocol.HttpProtobuf; })) .WithMetrics(metrics => metrics // The rest of your setup code goes here .AddOtlpExporter(options => { options.Endpoint = new Uri("your-endpoint-here/v1/metrics"); options.Protocol = OtlpExportProtocol.HttpProtobuf; })); builder.Logging.AddOpenTelemetry(logging => { // The rest of your setup code goes here logging.AddOtlpExporter(options => { options.Endpoint = new Uri("your-endpoint-here/v1/logs"); options.Protocol = OtlpExportProtocol.HttpProtobuf; }); }); ``` ### Non-ASP.NET Core Configure the exporter when creating a `TracerProvider`, `MeterProvider` or `LoggerFactory`: ```csharp var tracerProvider = Sdk.CreateTracerProviderBuilder() // Other setup code, like setting a resource goes here too .AddOtlpExporter(options => { options.Endpoint = new Uri("your-endpoint-here/v1/traces"); options.Protocol = OtlpExportProtocol.HttpProtobuf; }) .Build(); var meterProvider = Sdk.CreateMeterProviderBuilder() // Other setup code, like setting a resource goes here too .AddOtlpExporter(options => { options.Endpoint = new Uri("your-endpoint-here/v1/metrics"); options.Protocol = OtlpExportProtocol.HttpProtobuf; }) .Build(); var loggerFactory = LoggerFactory.Create(builder => { builder.AddOpenTelemetry(logging => { logging.AddOtlpExporter(options => { options.Endpoint = new Uri("your-endpoint-here/v1/logs"); options.Protocol = OtlpExportProtocol.HttpProtobuf; }) }); }); ``` Use environment variables to set values like headers and an endpoint URL for production. ## Console ## Dependencies The console exporter is useful for development and debugging tasks, and is the simplest to set up. Start by installing the [`OpenTelemetry.Exporter.Console`](https://www.nuget.org/packages/OpenTelemetry.Exporter.Console/) package as a dependency for your project: ```sh dotnet add package OpenTelemetry.Exporter.Console ``` If you're using ASP.NET Core install the [`OpenTelemetry.Extensions.Hosting`](https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting) package as well: ```sh dotnet add package OpenTelemetry.Extensions.Hosting ``` ## Usage {#console-usage} ### ASP.NET Core {#console-usage-asp-net-core} Configure the exporter in your ASP.NET Core services: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .WithTracing(tracing => tracing // The rest of your setup code goes here .AddConsoleExporter() ) .WithMetrics(metrics => metrics // The rest of your setup code goes here .AddConsoleExporter() ); builder.Logging.AddOpenTelemetry(logging => { // The rest of your setup code goes here logging.AddConsoleExporter(); }); ``` ### Non-ASP.NET Core {#console-usage-non-asp-net-core} Configure the exporter when creating a `TracerProvider`, `MeterProvider` or `LoggerFactory`: ```csharp var tracerProvider = Sdk.CreateTracerProviderBuilder() // The rest of your setup code goes here .AddConsoleExporter() .Build(); var meterProvider = Sdk.CreateMeterProviderBuilder() // The rest of your setup code goes here .AddConsoleExporter() .Build(); var loggerFactory = LoggerFactory.Create(builder => { builder.AddOpenTelemetry(logging => { logging.AddConsoleExporter(); }); }); ``` ## Jaeger ### Backend Setup {#jaeger-backend-setup} [Jaeger](https://www.jaegertracing.io/) natively supports OTLP to receive trace data. You can run Jaeger in a docker container with the UI accessible on port 16686 and OTLP enabled on ports 4317 and 4318: ```shell docker run --rm \ -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ -p 16686:16686 \ -p 4317:4317 \ -p 4318:4318 \ -p 9411:9411 \ jaegertracing/all-in-one:latest ``` ### Usage {#jaeger-usage} Now following the instruction to setup the [OTLP exporters](#otlp-dependencies). {{__hugo_ctx/}} ## Prometheus To send your metric data to [Prometheus](https://prometheus.io/), you can either [enable Prometheus' OTLP Receiver](https://prometheus.io/docs/guides/opentelemetry/#enable-the-otlp-receiver) and use the [OTLP exporter](#otlp) or you can use the Prometheus exporter, a `MetricReader` that starts an HTTP server that collects metrics and serialize to Prometheus text format on request. ### Backend Setup {#prometheus-setup} > [!NOTE] > > If you have Prometheus or a Prometheus-compatible backend already set up, you > can skip this section and setup the [Prometheus](#prometheus-dependencies) or > [OTLP](#otlp-dependencies) exporter dependencies for your application. You can run [Prometheus](https://prometheus.io) in a docker container, accessible on port `9090` by following these instructions: Create a file called `prometheus.yml` with the following content: ```yaml scrape_configs: - job_name: dice-service scrape_interval: 5s static_configs: - targets: [host.docker.internal:9464] ``` Run Prometheus in a docker container with the UI accessible on port `9090`: ```shell docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --web.enable-otlp-receiver ``` > [!NOTE] > > When using Prometheus' OTLP Receiver, make sure that you set the OTLP endpoint > for metrics in your application to `http://localhost:9090/api/v1/otlp`. > > Not all docker environments support `host.docker.internal`. In some cases you > may need to replace `host.docker.internal` with `localhost` or the IP address > of your machine. {{__hugo_ctx/}} The following sections provide detailed, .NET-specific instructions for configuring the Prometheus exporter. There are two approaches for exporting metrics to Prometheus: 1. **Using OTLP Exporter (Push)**: Push metrics to Prometheus using the OTLP protocol. This requires [Prometheus' OTLP Receiver](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver) to be enabled. This is the recommended approach for production environments as it supports exemplars and is stable. 2. **Using Prometheus Exporter (Pull/Scrape)**: Expose a scraping endpoint in your application that Prometheus can scrape. This is the traditional Prometheus approach. #### Using OTLP Exporter (Push) {#prometheus-otlp} This approach uses the OTLP exporter to push metrics directly to Prometheus' OTLP receiver endpoint. This is recommended for production environments because it supports exemplars and uses the stable OTLP protocol. ##### Dependencies {#prometheus-otlp-dependencies} Install the [`OpenTelemetry.Exporter.OpenTelemetryProtocol`](https://www.nuget.org/packages/OpenTelemetry.Exporter.OpenTelemetryProtocol/) package as a dependency for your project: ```sh dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol ``` If you're using ASP.NET Core install the [`OpenTelemetry.Extensions.Hosting`](https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting) package as well: ```sh dotnet add package OpenTelemetry.Extensions.Hosting ``` ##### Usage {#prometheus-otlp-usage} ###### ASP.NET Core {#prometheus-otlp-asp-net-core-usage} Configure the OTLP exporter to send metrics to Prometheus OTLP receiver: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .WithMetrics(metrics => metrics // The rest of your setup code goes here .AddOtlpExporter(options => { options.Endpoint = new Uri("http://localhost:9090/api/v1/otlp/v1/metrics"); options.Protocol = OtlpExportProtocol.HttpProtobuf; })); ``` ###### Non-ASP.NET Core {#prometheus-otlp-non-asp-net-core-usage} Configure the exporter when creating a `MeterProvider`: ```csharp var meterProvider = Sdk.CreateMeterProviderBuilder() // Other setup code, like setting a resource goes here too .AddOtlpExporter(options => { options.Endpoint = new Uri("http://localhost:9090/api/v1/otlp/v1/metrics"); options.Protocol = OtlpExportProtocol.HttpProtobuf; }) .Build(); ``` #### Using Prometheus Exporter (Pull/Scrape) {#prometheus-exporter} This approach exposes a metrics endpoint in your application (e.g., `/metrics`) that Prometheus scrapes at regular intervals. ##### Dependencies {#prometheus-dependencies} Install the [exporter package](https://www.nuget.org/packages/OpenTelemetry.Exporter.Prometheus.AspNetCore) as a dependency for your application: ```shell dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --version 1.15.1-beta.1 ``` If you're using ASP.NET Core install the [`OpenTelemetry.Extensions.Hosting`](https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting) package as well: ```sh dotnet add package OpenTelemetry.Extensions.Hosting ``` ##### Usage {#prometheus-exporter-usage} ###### ASP.NET Core {#prometheus-exporter-asp-net-core-usage} Configure the exporter in your ASP.NET Core services: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .WithMetrics(metrics => metrics.AddPrometheusExporter()); ``` You'll then need to register the Prometheus scraping middleware so that Prometheus can scrape your application. Use the `UseOpenTelemetryPrometheusScrapingEndpoint` extension method on `IApplicationBuilder`: ```csharp var builder = WebApplication.CreateBuilder(args); // ... Setup var app = builder.Build(); app.UseOpenTelemetryPrometheusScrapingEndpoint(); await app.RunAsync(); ``` By default, this exposes the metrics endpoint at `/metrics`. You can customize the endpoint path or use a predicate function for more advanced configuration: ```csharp app.UseOpenTelemetryPrometheusScrapingEndpoint( context => context.Request.Path == "/internal/metrics" && context.Connection.LocalPort == 5067); ``` ###### Non-ASP.NET Core {#prometheus-exporter-non-asp-net-core-usage} > [!WARNING] > > This component is intended for dev inner-loop, there is no plan to make it > production ready. Production environments should use > [`OpenTelemetry.Exporter.Prometheus.AspNetCore`](#prometheus-exporter-asp-net-core-usage), > or a combination of > [`OpenTelemetry.Exporter.OpenTelemetryProtocol`](#aspnet-core) and > [OpenTelemetry Collector](/docs/collector). For applications not using ASP.NET Core, you can use the `HttpListener` version which is available in a [different package](https://www.nuget.org/packages/OpenTelemetry.Exporter.Prometheus.HttpListener): ```shell dotnet add package OpenTelemetry.Exporter.Prometheus.HttpListener --version 1.15.1-beta.1 ``` Then this is setup directly on the `MeterProviderBuilder`: ```csharp var meterProvider = Sdk.CreateMeterProviderBuilder() .AddMeter(MyMeter.Name) .AddPrometheusHttpListener( options => options.UriPrefixes = new string[] { "http://localhost:9464/" }) .Build(); ``` ##### Prometheus Configuration (Scrape) When using the Prometheus exporter (pull/scrape approach), you need to configure Prometheus to scrape your application. Add the following to your `prometheus.yml`: ```yaml scrape_configs: - job_name: 'your-app-name' scrape_interval: 5s static_configs: - targets: ['localhost:5000'] # Your application's host:port ``` For more details on configuring the Prometheus exporter, see [OpenTelemetry.Exporter.Prometheus.AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.Prometheus.AspNetCore/README.md). ## Zipkin ### Backend Setup {#zipkin-setup} > [!NOTE] > > If you have Zipkin or a Zipkin-compatible backend already set up, you can skip > this section and setup the > [Zipkin exporter dependencies](#zipkin-dependencies) for your application. You can run [Zipkin](https://zipkin.io/) on in a Docker container by executing the following command: ```shell docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin ``` {{__hugo_ctx/}} ## Dependencies {#zipkin-dependencies} To send your trace data to [Zipkin](https://zipkin.io/), install the [exporter package](https://www.nuget.org/packages/OpenTelemetry.Exporter.Zipkin) as a dependency for your application: ```shell dotnet add package OpenTelemetry.Exporter.Zipkin ``` If you're using ASP.NET Core install the [`OpenTelemetry.Extensions.Hosting`](https://www.nuget.org/packages/OpenTelemetry.Extensions.Hosting) package as well: ```sh dotnet add package OpenTelemetry.Extensions.Hosting ``` ## Usage {#zipkin-usage} ### ASP.NET Core {#zipkin-asp-net-core-usage} Configure the exporter in your ASP.NET Core services: ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .WithTracing(tracing => tracing // The rest of your setup code goes here .AddZipkinExporter(options => { options.Endpoint = new Uri("your-zipkin-uri-here"); })); ``` ### Non-ASP.NET Core {#zipkin-non-asp-net-core-usage} Configure the exporter when creating a tracer provider: ```csharp var tracerProvider = Sdk.CreateTracerProviderBuilder() // The rest of your setup code goes here .AddZipkinExporter(options => { options.Endpoint = new Uri("your-zipkin-uri-here"); }) .Build(); ```