Exporters

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

可用导出器

注册表包含一个 .NET 导出器列表。

在导出器中，OpenTelemetry Protocol (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，以便将其遥测数据发送到您的可观察性后端。

依赖项

如果您想将遥测数据发送到 OTLP 端点（例如 OpenTelemetry Collector、Jaeger 或 Prometheus），您可以在两种不同的协议之间进行选择来传输数据

HTTP/Protobuf
gRPC

首先，将 OpenTelemetry.Exporter.OpenTelemetryProtocol 包作为您项目的依赖项进行安装

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

如果您使用的是 ASP.NET Core，请同时安装 OpenTelemetry.Extensions.Hosting 包

dotnet add package OpenTelemetry.Extensions.Hosting

用法

ASP.NET Core

在您的 ASP.NET Core 服务中配置导出器

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

默认情况下，这将通过 gRPC 以 https://:4317 发送遥测数据。要自定义使用 HTTP 和 protobuf 格式，您可以像这样添加选项

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;
    });
});

非 ASP.NET Core

在创建 TracerProvider、MeterProvider 或 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;
        })
    });
});

使用环境变量来设置生产环境中的标头和端点 URL 等值。

控制台

依赖项

控制台导出器对于开发和调试任务非常有用，并且是最容易设置的。首先，将 OpenTelemetry.Exporter.Console 包作为您项目的依赖项进行安装

dotnet add package OpenTelemetry.Exporter.Console

如果您使用的是 ASP.NET Core，请同时安装 OpenTelemetry.Extensions.Hosting 包

dotnet add package OpenTelemetry.Extensions.Hosting

用法

ASP.NET Core

在您的 ASP.NET Core 服务中配置导出器

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

非 ASP.NET Core

在创建 TracerProvider、MeterProvider 或 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 来接收跟踪数据。您可以在 Docker 容器中运行 Jaeger，UI 可通过端口 16686 访问，OTLP 可通过端口 4317 和 4318 访问。

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 导出器。

Prometheus

要将您的指标数据发送到 Prometheus，您可以启用 Prometheus 的 OTLP Receiver 并使用 OTLP 导出器，或者您可以使用 Prometheus 导出器，这是一个 MetricReader，它会启动一个 HTTP 服务器，在请求时收集指标并将其序列化为 Prometheus 文本格式。

后端设置

注意

如果您已经设置了 Prometheus 或与 Prometheus 兼容的后端，可以跳过此部分，并为您的应用程序设置 Prometheus 或 OTLP 导出器依赖项。

您可以按照以下说明，在 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 Receiver 时，请确保在您的应用程序中将指标的 OTLP 端点设置为 https://:9090/api/v1/otlp。

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

依赖项

将导出器包作为您应用程序的依赖项进行安装

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

如果您使用的是 ASP.NET Core，请同时安装 OpenTelemetry.Extensions.Hosting 包

dotnet add package OpenTelemetry.Extensions.Hosting

用法

ASP.NET Core

在您的 ASP.NET Core 服务中配置导出器

var builder = WebApplication.CreateBuilder(args);

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

然后您需要添加端点，以便 Prometheus 可以抓取您的站点。您可以使用 IAppBuilder 扩展来完成此操作，如下所示

var builder = WebApplication.CreateBuilder(args);

// .. Setup

var app = builder.Build();

app.UseOpenTelemetryPrometheusScrapingEndpoint();

await app.RunAsync();

非 ASP.NET Core

警告

此组件适用于开发内部循环，没有计划使其生产就绪。生产环境应使用 OpenTelemetry.Exporter.Prometheus.AspNetCore，或结合使用 OpenTelemetry.Exporter.OpenTelemetryProtocol 和 OpenTelemetry Collector。

对于不使用 ASP.NET Core 的应用程序，您可以使用 HttpListener 版本，该版本可在不同的包中找到

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

然后直接在 MeterProviderBuilder 上进行设置

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

最后，使用 IApplicationBuilder 上的 UseOpenTelemetryPrometheusScrapingEndpoint 扩展方法注册 Prometheus 抓取中间件

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

有关配置 Prometheus 导出器的更多详细信息，请参阅 OpenTelemetry.Exporter.Prometheus.AspNetCore。

Zipkin

后端设置

注意

如果您已经设置了 Zipkin 或与 Zipkin 兼容的后端，可以跳过此部分，并为您的应用程序设置 Zipkin 导出器依赖项。

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

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

依赖项

要将您的跟踪数据发送到 Zipkin，请将导出器包作为您应用程序的依赖项进行安装

dotnet add package OpenTelemetry.Exporter.Zipkin

如果您使用的是 ASP.NET Core，请同时安装 OpenTelemetry.Extensions.Hosting 包

dotnet add package OpenTelemetry.Extensions.Hosting

用法

ASP.NET Core

在您的 ASP.NET Core 服务中配置导出器

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");
        }));

非 ASP.NET Core

创建跟踪提供程序时配置导出器

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

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！

最后修改于 2025 年 10 月 13 日：[dep] Upgrade markdownlint and fix lint errors and drift status (#8078) (f49ec57e)