Mud.HttpUtils.OpenTelemetry 2.0.2

Mud.HttpUtils.OpenTelemetry

概述

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

目标框架

• netstandard2.0
• net6.0
• net8.0
• net10.0

安装

<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

OtlpExportProtocol 枚举：本包自定义了 OtlpExportProtocol（Grpc = 0、HttpProtobuf = 1），用于覆盖 OpenTelemetry SDK 的同名类型。可通过 options.OtlpExportProtocol 指定导出协议。

批量导出配置范围：ExportBatchSize / ExportIntervalMilliseconds 仅作用于 Tracing（Activity）的 BatchExportProcessorOptions，不影响 Metrics / Logs 的导出节奏。

EnableHttpClientInstrumentation：同时控制 Tracing 与 Metrics 两侧的 .NET HttpClient 关联（AddHttpClientInstrumentation），不仅关联 ActivitySource。

AddMudHttpOpenTelemetry 的两个重载均返回 OpenTelemetryBuilder，可继续链式追加配置；IConfiguration 重载的 sectionPath 参数默认值为 "MudHttpOpenTelemetry"，可自定义绑定节点路径。

从 IConfiguration 绑定

除代码配置外，还支持从 appsettings.json 绑定选项：

builder.Services.AddMudHttpOpenTelemetry(builder.Configuration);

对应 appsettings.json：

{
  "MudHttpOpenTelemetry": {
    "ServiceName": "my-service",
    "ServiceVersion": "1.0.0",
    "DeploymentEnvironment": "production",
    "SamplingRatio": 0.1,
    "EnableTracing": true,
    "EnableMetrics": true,
    "EnableLogging": false,
    "EnableHttpClientInstrumentation": true,
    "EnableAspNetCoreInstrumentation": true,
    "OtlpEndpoint": "http://otel-collector:4317",
    "OtlpExportProtocol": "Grpc",
    "ExportBatchSize": 256,
    "ExportIntervalMilliseconds": 5000,
    "OtlpHeaders": {
      "Authorization": "Bearer my-token"
    }
  }
}

也可同时使用配置绑定和代码配置：AddMudHttpOpenTelemetry(builder.Configuration, configure: options => { ... })，代码配置在配置绑定之后执行，可覆盖绑定值。

热更新限制：OpenTelemetry 配置在应用启动时一次性读取，不支持 IOptionsMonitor 热更新。这是因为 OpenTelemetry SDK 的 TracerProvider/MeterProvider 在构建后不可变。修改 appsettings.json 中的 MudHttpOpenTelemetry 节后需重启应用才能生效。如需运行时可变配置，请使用 AddMudHttpOpenTelemetry(Action<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