导出器

In order to visualize and analyze your telemetry, you will need to export your data to an OpenTelemetry Collector or a backend such as Jaeger, Zipkin, Prometheus or a vendor-specific one.

As part of OpenTelemetry .NET you will find many exporters being available. Among them, the OpenTelemetry Protocol (OTLP) exporters provide the best experience for you as an end-user, since it is a general-purpose telemetry data delivery protocol designed in the scope of the OpenTelemetry project.

To learn more about the OTLP protocol, you can read the OTLP Specification.

Below you will find some introductions on how to set up exporters for OTLP and other common protocols in your code.

控制台导出器

控制台导出器对于开发和调试任务非常有用,并且是设置最简单的导出器。

dotnet add package OpenTelemetry.Exporter.Console
dotnet add package OpenTelemetry.Extensions.Hosting

如果您使用ASP.NET Core,请在您的ASP.NET Core服务中配置导出器:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry().WithTracing(b =>
{
    b.AddConsoleExporter()
    // 您的其余设置代码也在这里
});

否则,当创建跟踪提供者时,请配置导出器:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddConsoleExporter()

    // 其他设置代码,例如设置资源也在这里

    .Build();

OTLP 终端

要将跟踪数据发送到 OTLP 终端(如收集器或 Jaeger),您将希望配置一个发送到终端的 OTLP 导出器。

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting

如果您使用 ASP.NET Core,请在您的 ASP.NET Core 服务中配置导出器:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
  .WithTracing(b =>
  {
    b.AddOtlpExporter()
    // 您的其余设置代码也在这里
  });

默认情况下,这将通过 gRPC 发送跟踪到 http://localhost:4317,若要自定义使用 HTTP 和 protobuf 格式,可以像这样添加选项:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
  .WithTracing(b =>
{
    b
    .AddOtlpExporter(opt =>
    {
        opt.Endpoint = new Uri("your-endpoint-here");
        opt.Protocol = OtlpExportProtocol.HttpProtobuf;
    })
    // 您的其余设置代码也在这里
});

否则,当创建跟踪提供者时,请配置导出器:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddOtlpExporter(opt =>
    {
        opt.Endpoint = new Uri("your-endpoint-here");
        opt.Protocol = OtlpExportProtocol.HttpProtobuf;
    })

    // 其他设置代码,例如设置资源也在这里

    .Build();

在生产环境中,可以使用环境变量设置值,例如头部和终端 URL。

.NET Core 3.1 及更低版本和 gRPC 注意事项

注意:.NET 6 以下版本不受opentelemetry-dotnet官方支持,因此此部分的内容仅供参考,可能无法在库进展过程中正常工作。

如果您不使用 ASP.NET Core gRPC 并且运行在 .NET Core 3.x 上,则需要在应用程序启动时添加以下内容:

AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);

如果您使用的是 .NET 5 或更高版本,则不需要上述代码示例。

Jaeger

要尝试 OTLP 导出器,您可以将 Jaeger 作为 OTLP 终端并在 Docker 容器中进行跟踪可视化运行:

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

Zipkin

如果您使用 Zipkin 来可视化跟踪数据,则需要先设置它。可以使用以下命令在 Docker 容器中运行 Zipkin:

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

然后,安装 Zipkin 导出器包:

dotnet add package OpenTelemetry.Exporter.Zipkin
dotnet add package OpenTelemetry.Extensions.Hosting

如果您使用 ASP.NET Core,请在您的 ASP.NET Core 服务中配置导出器:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenTelemetry()
    .WithTracing(b =>
    {
        b.AddZipkinExporter(o =>
        {
            o.Endpoint = new Uri("your-zipkin-uri-here");
        })
        // 您的其余设置代码也在这里
    });

否则,当创建跟踪提供者时,请配置导出器:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddZipkinExporter(o =>
    {
        o.Endpoint = new Uri("your-zipkin-uri-here");
    })

    // 其他设置代码,例如设置资源也在这里

    .Build();

Prometheus (实验性)

*注意: 这是实验性内容,具体取决于 OpenTelemetry 的规范在发布包之前是否稳定。目前,我们建议使用 OTLP 导出器并使用 OpenTelemetry Collector 将指标发送到 Prometheus*

如果您使用 Prometheus 来可视化指标数据,则需要首先进行设置。以下是使用 docker 容器设置 Prometheus 的步骤:

首先,您需要一个 prometheus.yml 配置文件,用于配置 Prometheus 后端,例如以下内容:

global:
  scrape_interval: 1s
  evaluation_interval: 1s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: [localhost:9090]

然后,运行以下 docker 命令来设置 Prometheus:

docker run \
    -p 9090:9090 \
    -v ${PWD}/prometheus.yml:/etc/prometheus/prometheus.yml \
    prom/prometheus

接下来,安装 Prometheus 导出器:

ASP.NET

dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --version 1.4.0-rc.4
dotnet add package OpenTelemetry.Extensions.Hosting

如果您使用 ASP.NET Core,请在您的 ASP.NET Core 服务中配置导出器:

var builder = WebApplication.CreateBuilder(args);

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

然后,您需要添加终端点,以便 Prometheus 可以抓取您的网站的数据。您可以使用 IAppBuilder 扩展方法来完成此操作,如下所示:

var builder = WebApplication.CreateBuilder(args);

// .. 设置

var app = builder.Build();

app.UseOpenTelemetryPrometheusScrapingEndpoint();

await app.RunAsync();

非 ASP.NET Core

对于不使用 ASP.NET Core 的应用程序,您可以使用 HttpListener 版本,该版本包含在另一个包中:

dotnet add package OpenTelemetry.Exporter.Prometheus.HttpListener --version 1.4.0-rc.4

然后,直接在 MeterProviderBuilder 上进行设置:

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

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

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

可以在此处找到有关配置 Prometheus 导出器的更多详细信息。

下一步

为了确保您能够尽量轻松地获得尽可能多的数据,请安装 仪表库 以生成可观察性数据。

此外,使用 手动注入 丰富您的代码库,可提供定制的可观察性数据。

您还可以查看当前处于 beta 版的 .NET 自动记录仪

最后修改 December 10, 2023: translate (a4350d6e)