Exporters

You are viewing the English version of this page because it has not yet been fully translated. Interested in helping out? See Contributing.

将遥测数据发送到 OpenTelemetry Collector，以确保其被正确导出。在生产环境中使用 Collector 是最佳实践。若要可视化你的遥测数据，可将其导出到后端系统，例如 Jaeger、Zipkin、 Prometheus，或某个特定厂商的后端。

可用的导出器

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

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

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

注意

如果你使用了零代码自动插桩，你可以参考配置指南来了解如何设置导出器。

OTLP

Collector 设置

注意

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

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

在一个空目录下创建名为 collector-config.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：

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

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

Dependencies

If you want to send telemetry data to an OTLP endpoint (like the OpenTelemetry Collector, Jaeger or Prometheus), you can choose between two different protocols to transport your data:

HTTP/protobuf
gRPC

Start by installing the OpenTelemetry.Exporter.OpenTelemetryProtocol package as a dependency for your project:

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

If you’re using ASP.NET Core install the OpenTelemetry.Extensions.Hosting package as well:

dotnet add package OpenTelemetry.Extensions.Hosting

Usage

ASP.NET Core

Configure the exporters in your ASP.NET Core services:

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:

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:

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 package as a dependency for your project:

dotnet add package OpenTelemetry.Exporter.Console

If you’re using ASP.NET Core install the OpenTelemetry.Extensions.Hosting package as well:

dotnet add package OpenTelemetry.Extensions.Hosting

Usage

ASP.NET Core

Configure the exporter in your ASP.NET Core services:

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

Configure the exporter when creating a TracerProvider, MeterProvider or LoggerFactory:

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 原生支持 OTLP，用于接收链路（trace）数据。你可以通过运行一个 Docker 容器来启动 Jaeger，其 UI 默认在端口 16686 上可访问，并在端口 4317 和 4318 上启用 OTLP：

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

使用方法

现在，按照说明设置 OTLP exporters。

Prometheus

要将你的指标（metrics）数据发送到 Prometheus，你可以选择启用 Prometheus 的 OTLP 接收器并且使用 OTLP exporter，或者使用 Prometheus exporter，这是一种 MetricReader，他启动一个 HTTP 服务器，根据请求收集指标并将数据序列化为 Prometheus 文本格式。

后端设置

注意

如果你已经设置了 Prometheus 或兼容 Prometheus 的后端，可以跳过本节，直接为你的应用设置 Prometheus 或者 OTLP exporter 依赖。

你可以按照以下步骤在 Docker 容器中运行 Prometheus，并通过端口 9090 访问：

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

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

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

docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --enable-feature=otlp-write-receive

注意

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

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

Dependencies

Install the exporter package as a dependency for your application:

dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --version 1.12.0-beta.1

If you’re using ASP.NET Core install the OpenTelemetry.Extensions.Hosting package as well:

dotnet add package OpenTelemetry.Extensions.Hosting

Usage

ASP.NET Core

Configure the exporter in your ASP.NET Core services:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics => metrics.AddPrometheusExporter());

You’ll then need to add the endpoint so that Prometheus can scrape your site. You can do this using the IAppBuilder extension like this:

var builder = WebApplication.CreateBuilder(args);

// .. Setup

var app = builder.Build();

app.UseOpenTelemetryPrometheusScrapingEndpoint();

await app.RunAsync();

Non-ASP.NET Core

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, or a combination of OpenTelemetry.Exporter.OpenTelemetryProtocol and OpenTelemetry Collector.

For applications not using ASP.NET Core, you can use the HttpListener version which is available in a different package:

dotnet add package OpenTelemetry.Exporter.Prometheus.HttpListener --version 1.12.0-beta.1

Then this is setup directly on the MeterProviderBuilder:

var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter(MyMeter.Name)
    .AddPrometheusHttpListener(
        options => options.UriPrefixes = new string[] { "http://localhost:9464/" })
    .Build();

Finally, register the Prometheus scraping middleware using the UseOpenTelemetryPrometheusScrapingEndpoint extension method on IApplicationBuilder :

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.UseOpenTelemetryPrometheusScrapingEndpoint();

For more details on configuring the Prometheus exporter, see OpenTelemetry.Exporter.Prometheus.AspNetCore.

Zipkin

后端设置

提示

如果你已经设置了 Zipkin 或兼容 Zipkin 的后端，可以跳过本节并直接为你的应用设置 Zipkin exporter 依赖。

你可以通过执行以下命令，在 Docker 容器中运行 Zipkin：

docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin

Dependencies

To send your trace data to Zipkin, install the exporter package as a dependency for your application:

dotnet add package OpenTelemetry.Exporter.Zipkin

If you’re using ASP.NET Core install the OpenTelemetry.Extensions.Hosting package as well:

dotnet add package OpenTelemetry.Extensions.Hosting

Usage

ASP.NET Core

Configure the exporter in your ASP.NET Core services:

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

Configure the exporter when creating a tracer provider:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    // The rest of your setup code goes here
    .AddZipkinExporter(options =>
    {
        options.Endpoint = new Uri("your-zipkin-uri-here");
    })
    .Build();

Feedback

Was this page helpful?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

Last modified May 22, 2025: [chore] Accessible links 3 (#6051) (f92dd4fb)