Mud.Feishu.OpenTelemetry 3.0.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 标签
• ✅ 配置验证 - 内置 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;
});

配合 ASP.NET Core 启动验证

AddFeishuOpenTelemetry 已自动注册 IValidateOptions<FeishuOpenTelemetryOptions>（校验 SamplingRatio 范围、ServiceName / ServiceVersion / DeploymentEnvironment 非空、OtlpEndpoint 为绝对 URI），并在注册时即时校验 SamplingRatio（越界直接抛出 ArgumentOutOfRangeException）。

如需在应用启动阶段 fail-fast，可追加 ValidateOnStart：

builder.Services.AddFeishuOpenTelemetry(builder.Configuration);

// 扩展已自动注册 IValidateOptions<FeishuOpenTelemetryOptions>，
// 启用 ValidateOnStart 后，配置无效将在应用启动时失败并给出错误信息
builder.Services.AddOptions<FeishuOpenTelemetryOptions>()
    .ValidateOnStart();

var app = builder.Build();

app.Run();

依赖项

框架支持

• .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 全链路可观测性！