Mud.HttpUtils.OpenTelemetry 3.0.4

Mud.HttpUtils.OpenTelemetry

概述

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

目标框架

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

关于 net6.0：本包不提供 net6.0 资产。其依赖 OpenTelemetry 1.16.0 已不再提供 net6.0 资产， 最接近的资产是 netstandard2.0，而该资产声明依赖 Microsoft.Extensions.* 10.0.0（官方不支持 net6.0）。net6.0 应用消费本包时由 NuGet 自动回落选择 netstandard2.0 资产，功能完全一致 （本包源码不含任何 TFM 相关的行为分支，net6.0 与 netstandard2.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）

DiagnosticSource / Span 事件（Listener：Mud.HttpUtils.HttpClient）：RequestStarted、RequestStopped、RequestFailed、RetryOccurred、TimeoutOccurred、CircuitBreakerStateChanged、CacheHit、CacheMiss、TokenRefreshed、DownloadStarted、DownloadCompleted、DownloadFailed。

outcome 语义：4xx → client_error 且 Span 设 Ok；5xx / 网络错误 → error（Span Error）；取消 → cancelled，Span 不设 Error。

指标（Metrics）

遥测脱敏与高基数治理（默认开启）

MudHttpObservabilityOptions（静态开关，建议进程启动时设置）：

// 设置示例（进程启动时）
MudHttpObservabilityOptions.RedactUrlInTelemetry = true;
MudHttpObservabilityOptions.RecordFullUrlOnSuccess = false;
MudHttpObservabilityOptions.EmitDiagnosticEvents = true;
MudHttpObservabilityOptions.MetricTagAllowlist = new HashSet<string> { "client_name", "outcome" }; // 收缩维度、降低基数

与健康检查配合

AddMudHttpOpenTelemetry 与 AddMudHttpHealthChecks 可同时使用（AddMudHttpHealthChecks 定义于 Mud.HttpUtils.Client 包，需同时安装 Client 包）：

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 兼容：委托式重载无反射；IConfiguration 绑定依赖 ConfigurationBinder（反射），AOT 场景请使用 Action<MudHttpOpenTelemetryOptions> 委托重载

依赖项

部署 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

作为其他 Mud SDK 的 OTel 基座

自 3.0.3 起，本包暴露了共享装配内核，其他 Mud SDK（如 Mud.Feishu、Mud.Wechat）可基于本包实现 OTel 可观测性，无需各自重复装配剧本。

核心类型

用法示例（下游 SDK 薄壳）

// 下游 SDK 定义自己的 Contribution
var contribution = new MudObservabilityContribution
{
    ProductName = "Mud.Feishu",
    ActivitySourceName = "Mud.Feishu",
    MeterName = "Mud.Feishu",
    DefaultServiceName = "Mud.Feishu.Application",
    DefaultServiceVersion = "1.0.0",
    IncludeMudHttpSources = true,  // 同时采集 Mud.HttpUtils 的源与 Meter
};

// 映射自己的 options → MudObservabilityOptions，然后委托内核装配
var coreOptions = new MudObservabilityOptions
{
    ServiceName = "my-feishu-app",
    OtlpEndpoint = new Uri("http://otel-collector:4317"),
    // ... 其他属性映射
};

services.AddMudObservability(contribution, coreOptions);

双重入口禁令

同一个宿主只应调用一个产品的 OTel 入口。

如果宿主已调用 AddMudHttpOpenTelemetry()，则不可再调用 AddMudObservability() 注册其他产品——内核的重复入口守卫会抛出 InvalidOperationException。

如需同时采集多个产品的源与 Meter，请使用 MudObservabilityContribution.IncludeMudHttpSources = true，或通过 AddMudObservabilitySources() 向既有 builder 追加源。

同一产品重复注册是幂等的：第二次及以后的调用不重复装配，原样返回首次装配的 OpenTelemetryBuilder（即首次注册的配置生效）。这避免了把同一份剧本（源 / Instrumentation / OTLP 导出器）叠加到同一 Provider 上——否则每个 Span 会被导出两次。