用途:为 C#/.NET 的 Microsoft 365 Agents SDK 应用添加、配置、验证和排查 OpenTelemetry 可观测性,适用于 AgentApplication 与 ActivityHandler 两类应用,两者 SDK 遥测信号相同。核心原则是最小完整改动,先在现有托管与遥测架构上扩展,不新建冲突的 Provider,可观测性须在 builder.Build() 与请求处理前注册。
主要能力:同时订阅 AgentsTelemetry.SourceName 与 AgentsTelemetry.Meter,因为 SDK 本身不直接依赖 OpenTelemetry,而是通过 System.Diagnostics 发布;配置链路、指标与日志三类信号并导出 OTLP;为应用设置稳定且独立的 service.name(不能使用 Microsoft.Agents.Core);支持本地 Aspire Dashboard 验证。
使用方式:先检查 *.csproj、Program.cs、已有 AddOpenTelemetry/AddOtlpExporter 等注册及 appsettings 中 OTEL 设置,再合并而非替换。按需安装包,如 dotnet add package OpenTelemetry.Extensions.Hosting、OpenTelemetry.Exporter.OpenTelemetryProtocol、OpenTelemetry.Instrumentation.AspNetCore、OpenTelemetry.Instrumentation.Http、OpenTelemetry.Instrumentation.Runtime;不要默认加控制台导出器,未要求不加 Azure Monitor。建议放在项目本地扩展类中配置,注册须早于 agent 注册。OTLP 采集器地址、认证头与连接串用环境变量或密钥存储,如 OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_HEADERS、OTEL_TRACES_SAMPLER 等。本地 Aspire Dashboard 可运行附带脚本,访问 http://localhost:18888,OTLP/gRPC 端口 4317、OTLP/HTTP 端口 4318,仅限本地开发。
限制与注意:默认不得采集消息文本、提示、响应、令牌、授权头、Cookie、密钥、附件内容、用户与对话标识等;指标属性须低基数,避免每用户、每会话、每消息或异常消息维度;不得把 AlwaysOnSampler 设为生产默认;遥测不得吞掉异常或把失败变为成功;Aspire 匿名模式仅限本地且端口绑定回环。指标导出有周期,缺失时先等待刷新再排查。SDK 具体信号清单见技能内参考文档。