# Exporters

LLMS index: [llms.txt](/llms.txt)

---


将遥测数据发送到 [OpenTelemetry Collector](/docs/collector/)，以确保其被正确导出。
在生产环境中使用 Collector 是最佳实践。若要可视化你的遥测数据，可将其导出到后端系统，例如
[Jaeger](https://jaegertracing.io/)、[Zipkin](https://zipkin.io/)、
[Prometheus](https://prometheus.io/)，或某个[特定厂商的](/ecosystem/vendors/)后端。



## 可用的导出器 {#available-exporters}

镜像仓库中包含一份 [.NET 可用导出器的列表][reg]。





在所有导出器中，[OpenTelemetry 协议 (OTLP)][OTLP] 导出器是以 OpenTelemetry 数据模型为基础设计的，
能够无信息丢失地输出 OTel 数据。此外，许多处理遥测数据的工具都支持 OTLP
（例如 [Prometheus][]、[Jaeger][] 和大多数[厂商][vendors]），在你需要时为你提供高度的灵活性。
若要了解更多关于 OTLP 的信息，请参阅 [OTLP 规范][OTLP]。

[Jaeger]: /blog/2022/jaeger-native-otlp/
[OTLP]: /docs/specs/otlp/
[Prometheus]: https://prometheus.io/docs/prometheus/2.55/feature_flags/#otlp-receiver
[reg]: </ecosystem/registry/?component=exporter&language=dotnet>
[vendors]: /ecosystem/vendors/



本页面介绍了主要的 OpenTelemetry .NET 导出器以及如何进行配置。





<div class="alert alert-primary" role="alert"><div class="h4 alert-heading" role="heading">注意</div>



如果你使用了[零代码自动插桩](</docs/zero-code/dotnet>)，
你可以参考[配置指南](</docs/zero-code/dotnet/configuration/>)来了解如何设置导出器。

</div>






## OTLP

### Collector 设置 {#collector-setup}

<div class="alert alert-primary" role="alert"><div class="h4 alert-heading" role="heading">注意</div>



如果你已经配置好 OTLP Collector 或后端，可以跳过此部分，
直接[设置应用的 OTLP 导出器依赖](#otlp-dependencies)。

</div>


为测试和验证你的 OTLP 导出器，你可以运行一个 Docker 容器形式的 Collector，将遥测数据直接输出到控制台。

在一个空目录下创建名为 `collector-config.yaml` 的文件，并添加以下内容：

```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]
```

然后运行以下命令，在 Docker 容器中启动 Collector：

```shell
docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector
```

现在，这个 Collector 已能通过 OTLP 接收遥测数据。
之后你可能需要配置 Collector，将遥测数据发送到你的可观测性后端。


{{__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 <http://localhost:4317>, 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

### 后端设置 {#jaeger-backend-setup}

[Jaeger](https://www.jaegertracing.io/) 原生支持 OTLP，用于接收链路数据。
你可以通过运行一个 Docker 容器来启动 Jaeger，其 UI 默认在端口 16686 上可访问，并在端口 4317 和 4318 上启用 OTLP：

```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
```

### 使用方法 {#jaeger-usage}

现在，按照说明设置 [OTLP 导出器](#otlp-dependencies)。
{{__hugo_ctx/}}



## Prometheus

要将你的指标数据发送到 [Prometheus](https://prometheus.io/)，
你可以选择[启用 Prometheus 的 OTLP 接收器](https://prometheus.io/docs/guides/opentelemetry/#enable-the-otlp-receiver)并且使用
[OTLP 导出器](#otlp)，或者使用 Prometheus 导出器，这是一种 `MetricReader`，
他启动一个 HTTP 服务器，根据请求收集指标并将数据序列化为 Prometheus 文本格式。

### 后端设置 {#prometheus-setup}

<div class="alert alert-primary" role="alert"><div class="h4 alert-heading" role="heading">注意</div>



如果你已经设置了 Prometheus 或兼容 Prometheus 的后端，可以跳过本节，直接为你的应用设置
[Prometheus](#prometheus-dependencies) 或者 [OTLP](#otlp-dependencies) 导出器依赖。

</div>


你可以按照以下步骤在 Docker 容器中运行 [Prometheus](https://prometheus.io)，并通过端口 9090 访问：

创建一个名为 `prometheus.yml` 的文件，并将以下内容写入文件：

```yaml
scrape_configs:
  - job_name: dice-service
    scrape_interval: 5s
    static_configs:
      - targets: [host.docker.internal:9464]
```

使用以下命令在 Docker 容器中运行 Prometheus，UI 可通过端口 `9090` 访问：

```shell
docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --web.enable-otlp-receiver
```

<div class="alert alert-primary" role="alert"><div class="h4 alert-heading" role="heading">注意</div>



当使用 Prometheus 的 OTLP 接收器时，确保在应用中设置 OTLP 端点为
`http://localhost:9090/api/v1/otlp`。

并非所有的 Docker 环境都支持 `host.docker.internal`。在某些情况下，你可能需要将
`host.docker.internal` 替换为 `localhost` 或你机器的 IP 地址。

</div>

{{__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();
```

<div class="alert alert-primary" role="alert"><div class="h4 alert-heading" role="heading">Note</div>



Make sure Prometheus is started with the OTLP receiver enabled:

```sh
./prometheus --web.enable-otlp-receiver
```

Or when using Docker:

```sh
docker run -p 9090:9090 prom/prometheus --web.enable-otlp-receiver
```

</div>


#### 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.

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">Warning</div>



This exporter is still under development and doesn't support exemplars. For
production environments, consider using the
[OTLP exporter approach](#prometheus-otlp) instead.

</div>


##### 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.2-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.2-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

### 后端设置 {#zipkin-setup}

<div class="alert alert-primary" role="alert"><div class="h4 alert-heading" role="heading">提示</div>



如果你已经设置了 Zipkin 或兼容 Zipkin 的后端，可以跳过本节并直接为你的应用设置
[Zipkin 导出器依赖](#zipkin-dependencies)。

</div>


你可以通过执行以下命令，在 Docker 容器中运行 [Zipkin](https://zipkin.io/)：

```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();
```