Mud.Wechat.OpenTelemetry
1.0.0
dotnet add package Mud.Wechat.OpenTelemetry --version 1.0.0
NuGet\Install-Package Mud.Wechat.OpenTelemetry -Version 1.0.0
<PackageReference Include="Mud.Wechat.OpenTelemetry" Version="1.0.0" />
<PackageVersion Include="Mud.Wechat.OpenTelemetry" Version="1.0.0" />
<PackageReference Include="Mud.Wechat.OpenTelemetry" />
paket add Mud.Wechat.OpenTelemetry --version 1.0.0
#r "nuget: Mud.Wechat.OpenTelemetry, 1.0.0"
#:package Mud.Wechat.OpenTelemetry@1.0.0
#addin nuget:?package=Mud.Wechat.OpenTelemetry&version=1.0.0
#tool nuget:?package=Mud.Wechat.OpenTelemetry&version=1.0.0
Mud.Wechat.OpenTelemetry
Mud.Wechat 全产品线共用的 OpenTelemetry 一键装配包:一次调用即注册追踪与指标采集,自动挂上微信 SDK 的 ActivitySource(单根源)、各产品线 Meter 与 Mud.HttpUtils 的 HTTP 可观测性源,默认导出至本地 OTLP gRPC 端点。
定位要点:本包不是 ActivitySource / Meter 的定义者——源定义在 Src/Core/Mud.Wechat.Abstractions/Observability/WechatActivitySource.cs(Name = "Mud.Wechat",标签 wechat.product / wechat.app_key / outcome / error.type / wechat.correlation_id,产品线取值 work / officialaccount / miniprogram / openplatform / pay)与 Core/Metrics/MeterExtensions.cs(RecordDuration 直方图扩展)。本包只做「贡献描述 + 选项映射 + 注册期校验」,装配本身委托上游共享内核 MudObservabilityBootstrap.AddMudObservability(Mud.HttpUtils.OpenTelemetry)。
内容
DI 入口(
WechatOpenTelemetryExtensions):两个重载,均返回OpenTelemetryBuilder便于继续追加配置——AddWechatOpenTelemetry(Action<WechatOpenTelemetryOptions>?):代码配置;AddWechatOpenTelemetry(IConfiguration, string sectionPath = "WechatOpenTelemetry", Action<WechatOpenTelemetryOptions>?):配置绑定走Configure<T>(o => section.Bind(o))源生成路径(AOTIL2026/IL3050净零),附加委托在绑定后执行、可覆盖。
产品贡献描述(
internal CreateContribution):ProductName = "Mud.Wechat"、单根源WechatActivitySource.Name、产品线 Meter 通配"Mud.Wechat*"(覆盖现有与未来全部产品线)、DefaultServiceName = "Mud.Wechat.Application"、DefaultServiceVersion = WechatActivitySource.Version、IncludeMudHttpSources ← IncludeMudHttpUtils。配置面(
WechatOpenTelemetryOptions,19 个公开属性,节WechatOpenTelemetry):属性 默认值 EnableTracing/EnableMetricstrue/trueEnableLogging(OTLP 日志导出)falseIncludeMudHttpUtilstrueEnableHttpClientInstrumentation/EnableAspNetCoreInstrumentationtrue/trueOtlpEndpointhttp://localhost:4317(设null则不配导出器,自行追加)OtlpExportProtocolGrpc(内网仅 4318 时改HttpProtobuf)OtlpHeadersnullUseShortExporterTimeoutfalse(true时导出超时压到 5s,便于开发调试)ExportBatchSize/ExportIntervalMillisecondsnull(SDK 默认 512 / 5000ms,仅 >0 生效)ServiceName"Mud.Wechat.Application"ServiceVersionWechatActivitySource.Version(与根Directory.Build.props的<Version>同步)DeploymentEnvironment"production"SamplingRatio1.0(ParentBasedSampler(TraceIdRatioBasedSampler),生产建议 0.1~0.3)ConfigureTracing/ConfigureMetrics/ConfigureLoggingnull(在本包默认配置之后执行,可追加/覆盖)选项映射(
internal WechatOpenTelemetryOptionsMapper.ToCore):逐属性映射到内核MudObservabilityOptions,是每个公开配置属性唯一真实消费点(audit-config-keys.ps1门禁;文件必须留在本工程目录内);IncludeMudHttpUtils不经映射、走CreateContribution。注册期校验:
SamplingRatio越界先行抛ArgumentOutOfRangeException;其余非法值(空白ServiceName/ServiceVersion/DeploymentEnvironment、相对 URIOtlpEndpoint)由Validate()拦截并抛OptionsValidationException——扩展方法显式调用校验(预构建实例经OptionsWrapper注册,DI 的IValidateOptions通道不会被 options 管道触发),非法配置启动期即失败而非静默。
用法
// Program.cs:一键开启(追踪 + 指标默认开,日志导出默认关)
builder.Services.AddWechatOpenTelemetry(builder.Configuration); // 绑定节 WechatOpenTelemetry
// 或代码配置,返回值可继续追加 SDK 原生配置
builder.Services.AddWechatOpenTelemetry(o =>
{
o.OtlpEndpoint = new Uri("http://otel-collector:4317");
o.ServiceName = "my-wechat-app";
o.SamplingRatio = 0.1;
});
依赖
- ProjectReference 仅
Mud.Wechat.Abstractions(Core:WechatActivitySource/MeterExtensions) Mud.HttpUtils.OpenTelemetry3.0.9(共享装配内核;本包不直接引用Mud.HttpUtils,MudHttpActivitySource/MudHttpMeter由内核内部注册;全仓Mud.HttpUtils*同版本,守卫 G1 锁定)OpenTelemetry/.Extensions.Hosting/.Exporter.OpenTelemetryProtocol/.Instrumentation.Http/.Instrumentation.AspNetCore均 1.16.0FrameworkReference Microsoft.AspNetCore.App(net6.0+;netstandard2.0 不引用)- TFM:不覆写,继承根
Directory.Build.props四档netstandard2.0;net6.0;net8.0;net10.0。
说明
- 单一入口禁令(必须遵守):调用本包后不得再调
AddMudHttpOpenTelemetry()——两条完整管道叠加会让 Resourceservice.name被覆盖、同一 Span 被两个 OTLP 导出器重复上报;内核按产品名拒绝不同产品重复注册。仅用微信 SDK 的宿主调本方法即可,Mud.HttpUtils 的源与指标已由IncludeMudHttpUtils覆盖。 - netstandard2.0 下 ASP.NET Core Instrumentation 由共享内核(
#if NETSTANDARD2_0分支)强制置false;net6.0 下 OTel 1.16.0 及其 M.E.* 传递依赖回落 netstandard2.0 资产(与 Redis 包同款提示性警告,SuppressTfmSupportBuildWarnings已处理)。 - 低 TFM 定版对齐根 props(netstandard2.0/net6.0 下
Microsoft.Extensions.*钉 10.0.9,消MSB3277)。 - 安全边界:本包只注册源与导出管线,不采集报文内容;凭据脱敏仍由各产品线日志层负责(标签设计均为非秘密维度,如
wechat.app_key)。 - 测试(
Tests/Mud.Wechat.OpenTelemetry.Tests):WechatWildcardMeterTests(通配 Meter 契约)、WechatOpenTelemetrySharedKernelTests(Mapper_ShouldMapEveryPublicOptionProperty逐属性映射、重复入口/幂等)、WechatOpenTelemetryOptionsValidationTests(越界拦截)、WechatOpenTelemetryExtensionsTests(DI 面)。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Options (>= 10.0.12)
- Mud.HttpUtils.OpenTelemetry (>= 3.0.9)
- Mud.Wechat.Abstractions (>= 1.0.0)
- OpenTelemetry (>= 1.16.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.16.0)
- OpenTelemetry.Extensions.Hosting (>= 1.16.0)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.16.0)
- OpenTelemetry.Instrumentation.Http (>= 1.16.0)
- System.Text.Json (>= 10.0.12)
-
net10.0
- Mud.HttpUtils.OpenTelemetry (>= 3.0.9)
- Mud.Wechat.Abstractions (>= 1.0.0)
- OpenTelemetry (>= 1.16.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.16.0)
- OpenTelemetry.Extensions.Hosting (>= 1.16.0)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.16.0)
- OpenTelemetry.Instrumentation.Http (>= 1.16.0)
-
net6.0
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Options (>= 10.0.12)
- Mud.HttpUtils.OpenTelemetry (>= 3.0.9)
- Mud.Wechat.Abstractions (>= 1.0.0)
- OpenTelemetry (>= 1.16.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.16.0)
- OpenTelemetry.Extensions.Hosting (>= 1.16.0)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.16.0)
- OpenTelemetry.Instrumentation.Http (>= 1.16.0)
-
net8.0
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Options (>= 10.0.12)
- Mud.HttpUtils.OpenTelemetry (>= 3.0.9)
- Mud.Wechat.Abstractions (>= 1.0.0)
- OpenTelemetry (>= 1.16.0)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.16.0)
- OpenTelemetry.Extensions.Hosting (>= 1.16.0)
- OpenTelemetry.Instrumentation.AspNetCore (>= 1.16.0)
- OpenTelemetry.Instrumentation.Http (>= 1.16.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.0.0 | 114 | 10/29/2026 |