Mud.HttpUtils.OpenTelemetry 2.0.0-rc5

Mud.HttpUtils.OpenTelemetry

概述

Mud.HttpUtils.OpenTelemetry 是 Mud.HttpUtils 的 OpenTelemetry 适配包，提供 一键开启 Mud.HttpUtils 内置的分布式追踪（Tracing）与指标（Metrics）采集能力，并自动关联 .NET HttpClient 与 ASP.NET Core 的内置 Instrumentation。

目标框架

• net8.0
• net10.0

由于 OpenTelemetry SDK 1.10.0 的传递依赖（Microsoft.Extensions.* 9.0.0）已不再支持 net6.0，本包仅面向 net8.0+。如需在 net6.0 中使用，请直接引用 OpenTelemetry.* 包并按本包源码自行配置。

安装

<PackageReference Include="Mud.HttpUtils.OpenTelemetry" Version="x.x.x" />

快速开始

1. ASP.NET Core 主机

var builder = WebApplication.CreateBuilder(args);

// 注册 Mud.HttpUtils 客户端（详见 Mud.HttpUtils.Client 文档）
builder.Services.AddMudHttpClient("myApi", c =>
{
    c.BaseAddress = new Uri("https://api.example.com");
});

// 一键开启 Mud.HttpUtils 的 OpenTelemetry 追踪与指标
builder.Services.AddMudHttpOpenTelemetry(options =>
{
    options.OtlpEndpoint = new Uri("http://otel-collector:4317");
});

var app = builder.Build();
app.Run();

2. 控制台应用

var services = new ServiceCollection();
services.AddLogging();
services.AddMudHttpClient("myApi", c => c.BaseAddress = new Uri("https://api.example.com"));
services.AddMudHttpOpenTelemetry();

using var provider = services.BuildServiceProvider();
// 使用 IHttpClientFactory 或 IEnhancedHttpClientFactory 发起请求

配置选项

MudHttpOpenTelemetryOptions

高级配置示例

builder.Services.AddMudHttpOpenTelemetry(options =>
{
    options.OtlpEndpoint = new Uri("http://otel-collector:4318");
    options.OtlpExportProtocol = OtlpExportProtocol.HttpProtobuf;
    options.EnableAspNetCoreInstrumentation = false;

    // 追加自定义 ActivitySource
    options.ConfigureTracing = tp => tp.AddSource("MyApp.Business");

    // 追加 Prometheus 导出器（需额外引用 OpenTelemetry.Exporter.Prometheus.AspNetCore）
    options.ConfigureMetrics = mp => mp.AddPrometheusExporter();
});

自动采集的内容

追踪（Tracing）

指标（Metrics）

与健康检查配合

AddMudHttpOpenTelemetry 与 AddMudHttpHealthChecks 可同时使用：

builder.Services.AddMudHttpClient("myApi", c => c.BaseAddress = new Uri("https://api.example.com"));
builder.Services.AddMudHttpHealthChecks();
builder.Services.AddMudHttpOpenTelemetry();

设计原则

• 零侵入：用户代码无需任何改动，仅在 DI 注册时调用一次扩展方法
• 可观测性零开销：无监听器时 ActivitySource.StartActivity 返回 null，Counter.Add 直接短路
• 默认即生产可用：默认开启 Tracing + Metrics + OTLP gRPC 导出至本地 4317
• 可扩展：通过 ConfigureTracing / ConfigureMetrics 委托追加自定义配置
• AOT 兼容：所有 API 均为静态类型与委托，无反射

依赖项

部署 OTLP 收集器

最简 Jaeger 部署（接收 OTLP gRPC 4317）：

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:1.62

启动应用后访问 http://localhost:16686 查看 Mud.HttpUtils 出站请求 span。

Prometheus + Grafana 抓取 Mud.HttpUtils.HttpClient Meter：

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
exporters:
  prometheus:
    endpoint: 0.0.0.0:8889
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]
    traces:
      receivers: [otlp]
      exporters: [otlp]  # 转发至 Jaeger