Mud.Feishu.OpenTelemetry 3.1.0

Mud.Feishu.OpenTelemetry

Mud.Feishu OpenTelemetry 适配包，一键开启飞书 SDK 的分布式追踪与指标采集。

项目简介

Mud.Feishu.OpenTelemetry 是 MudFeishu SDK 的可观测性扩展，通过一行代码自动注册飞书 SDK 的 ActivitySource 和 Meter，实现分布式追踪（Tracing）、指标采集（Metrics）和日志导出（Logging）。基于 OpenTelemetry .NET SDK 构建，支持 OTLP gRPC 导出，可与 Jaeger、Tempo、Prometheus、Grafana 等主流可观测性平台无缝集成。

特性

• ✅ 一键启用 - 一行代码完成飞书 SDK 全链路可观测性配置
• ✅ 自动注册 - 自动注册 Mud.Feishu 和 Mud.HttpUtils 的 ActivitySource 和 Meter
• ✅ 追踪（Tracing） - 飞书事件处理、Webhook、WebSocket、HTTP 出站请求全链路追踪
• ✅ 指标（Metrics） - Token 缓存、事件处理、HTTP 请求、WebSocket 连接等指标采集
• ✅ 日志导出 - 可选的 OTLP 日志导出
• ✅ 采样策略 - 支持 ParentBased + TraceIdRatioBased 采样
• ✅ 资源标签 - 自动添加 service.name、service.version、deployment.environment 标签
• ✅ 配置验证 - 注册期 fail-fast（非法配置抛 OptionsValidationException），并注册 IValidateOptions 供宿主接线 ValidateOnStart
• ✅ 单一入口保护 - 由上游共享内核按产品名拒绝异产品重复注册，避免双管道重复上报
• ✅ 灵活扩展 - 提供自定义配置委托，可追加/覆盖默认配置
• ✅ 多框架支持 - 支持 .NET Standard 2.0、.NET 6.0、.NET 8.0、.NET 10.0
• ✅ 原生 AOT 支持 - net8.0+ 一等公民支持 Native AOT 发布，指标与追踪源自动注册零反射

安装

dotnet add package Mud.Feishu.OpenTelemetry

快速开始

方式一：代码配置（推荐）

using Mud.Feishu.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);

// 一键开启飞书 SDK 的 OpenTelemetry 追踪与指标采集
builder.Services.AddFeishuOpenTelemetry(options =>
{
    options.OtlpEndpoint = new Uri("http://otel-collector:4317");
    options.ServiceName = "my-feishu-app";
    options.SamplingRatio = 0.1; // 生产环境建议 0.1~0.3
});

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

方式二：从配置文件绑定

{
  "FeishuOpenTelemetry": {
    "ServiceName": "my-feishu-app",
    "ServiceVersion": "1.0.0",
    "DeploymentEnvironment": "production",
    "SamplingRatio": 0.1,
    "OtlpEndpoint": "http://otel-collector:4317",
    "EnableTracing": true,
    "EnableMetrics": true,
    "EnableLogging": false,
    "IncludeMudHttpUtils": true,
    "EnableHttpClientInstrumentation": true,
    "EnableAspNetCoreInstrumentation": true
  }
}

builder.Services.AddFeishuOpenTelemetry(builder.Configuration);

自动注册的可观测性源

ActivitySource（追踪）

Meter（指标）

采集的指标列表

Mud.Feishu Meter（FeishuMetrics）采集的飞书指标：

HTTP 请求与 Token 刷新指标由 Mud.HttpUtils 自动采集（Mud.HttpUtils.HttpClient Meter）， 包括 mud.http.requests、mud.http.request.duration、mud.token.refresh、mud.token.refresh.duration。

配置选项

高级用法

自定义导出器

builder.Services.AddFeishuOpenTelemetry(options =>
{
    // 不使用默认 OTLP 导出，自定义配置
    options.OtlpEndpoint = null;
    options.SamplingRatio = 1.0;

    // 自定义追踪配置：追加 Console 导出器
    options.ConfigureTracing = tp => tp.AddConsoleExporter();

    // 自定义指标配置：追加 Prometheus 导出器
    options.ConfigureMetrics = mp => mp.AddPrometheusExporter();
});

仅启用飞书指标（不含 HTTP 追踪）

builder.Services.AddFeishuOpenTelemetry(options =>
{
    options.EnableTracing = false;
    options.IncludeMudHttpUtils = false;
    options.EnableHttpClientInstrumentation = false;
    options.EnableAspNetCoreInstrumentation = false;
});

配置校验与启动 fail-fast

AddFeishuOpenTelemetry 在注册期即显式执行完整校验（SamplingRatio 范围、ServiceName / ServiceVersion / DeploymentEnvironment 非空、OtlpEndpoint 为绝对 URI、ExportBatchSize / ExportIntervalMilliseconds 非负）：

• SamplingRatio 越界 → 抛 ArgumentOutOfRangeException（ParamName = "SamplingRatio"）；
• 其余不合法 → 抛 OptionsValidationException（OptionsType = typeof(FeishuOpenTelemetryOptions)）。

即无需额外配置即可获得启动期 fail-fast。扩展同时仍会注册 IValidateOptions<FeishuOpenTelemetryOptions> 与 IOptions<FeishuOpenTelemetryOptions>， 供宿主自行接线（如 AddOptions<FeishuOpenTelemetryOptions>().ValidateOnStart()）。

单一入口约束

本包内部经上游共享装配内核完成装配（Resource / Sampler / 源与 Meter / Instrumentation / OTLP 导出器）， 内核按产品名拒绝「不同产品重复注册」。请勿与 AddMudHttpOpenTelemetry() 同时调用：

// ✅ 只调一个：飞书宿主的 Mud.HttpUtils 源与指标已由 IncludeMudHttpUtils（默认 true）覆盖
builder.Services.AddFeishuOpenTelemetry(builder.Configuration);

// ❌ 禁止：两条完整管道叠加 ⇒ Resource service.name 被覆盖、同一 Span 被两个 OTLP 导出器重复上报
// builder.Services.AddMudHttpOpenTelemetry(builder.Configuration);

同时调用会在注册期抛 InvalidOperationException（fail-fast）；同一产品重复调用则幂等短路。

依赖项

框架支持

• .NET Standard 2.0
• .NET 6.0
• .NET 8.0
• .NET 10.0

相关项目

• Mud.Feishu.Abstractions - 事件处理抽象层（提供 ActivitySource 和 Meter 定义）
• Mud.Feishu - 核心 HTTP API 客户端库
• Mud.Feishu.WebSocket - WebSocket 实时事件订阅
• Mud.Feishu.Webhook - Webhook HTTP 回调事件处理

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

Mud.Feishu.OpenTelemetry - 一键开启飞书 SDK 全链路可观测性！