排查直接 OTel 可观测性的问题

使用本指南验证遥测引入和诊断通过 OTLP 直接发送到 Agent 365 的代理遥测问题。 它的范围限定为 direct OTel 路径 - 如果使用 Agent 365 SDK 或 Microsoft OpenTelemetry Distro，请参阅这些指南。 有关线路级限制、错误代码和静默丢弃条件，请参阅 限制和丢弃条件。

验证引入

200 OK 并不能证明已摄取成功。 某些丢弃条件会返回 200partialSuccess: null，而你的数据根本不会显示（请参阅 限制和丢弃条件）。 始终验证第一次运行：

  1. 检查 HTTP 状态。 200 → 继续。 4xx → 参见 常见陷阱。
  2. 解析partialSuccess。 null 表示 API 接受所有内容。 其他任何内容都意味着在每范围筛选器上删除了至少一些范围。
  3. 等待约 5 分钟，然后运行下面的 Defender 高级搜寻查询。
  4. 没有行？ 使用Defender 中无数据下的决策树。

Defender高级搜寻查询

规范查找（基于你发送的代理身份标识进行联接）：

let agentIdToFind = "YOUR-AGENT-APP-ID-HERE";
CloudAppEvents
| where Timestamp > ago(1d)
| where ActionType in ("InvokeAgent", "InferenceCall", "ExecuteToolBySDK", "ExecuteToolByGateway", "ExecuteToolByMCPServer")
| extend resData = parse_json(tostring(RawEventData))
| extend AgentId = resData.AgentId
| extend TargetAgentId = resData.TargetAgentId
| extend AlternateId = resData.PlatformTargetAgentId
| where AgentId == agentIdToFind or TargetAgentId == agentIdToFind or AlternateId == agentIdToFind
| project Timestamp, ActionType, resData
| order by Timestamp desc

有关界面的完整列表（Defender 代理活动视图、Microsoft 365 管理中心、Microsoft Purview）以及每个界面所需的条件，请参阅数据显示的位置。

Defender中没有数据

  • partialSuccess.rejectedSpans == totalSpans → 所有 span 都有一个有问题的 gen_ai.operation.name。 修复：请使用以下其中之一：invoke_agent、execute_tool、chat、output_messages（是 chat，不是 inference）。
  • 返回 200 且带有 partialSuccess: null，但 5 分钟后没有 Defender 行 → 客户租户中没有任何用户被分配 Microsoft 365 E7 或 Microsoft Agent 365 许可证（限制和删除条件，删除条件 2）。 修复：确认租户中至少有一名用户已被分配该许可证（而不只是该许可证存在于租户中）；否则，请联系 Agent 365 入门支持团队。
  • 跨度会显示出来，但运行树结构已损坏／某些子节点被孤立 → 缺少 parentSpanId、traceId 不同，或并非每个跨度都设置了 gen_ai.conversation.id。 修复： 查看 Span 层次结构并运行分组。

常见陷阱

症状 最有可能的原因 修复
401 Unauthorized 令牌处的 aud 错误。 使用 9b975845-388f-4429-889e-eab1ef63949c （或 api://9b975845-...）。
403 Forbidden，缺少角色 / 范围 令牌不包含 Agent365.Observability.OtelWrite。 根据范围和同意，将 Microsoft Entra 应用配置为角色（S2S）或范围（委派）。 对于 S2S，必须使用 <resource>/.default 获取令牌。
403 Forbidden，代理标识不匹配 {agentId} 在 URL 中的值 ≠ 令牌的 appid / azp，或者某个 span 带有与已认证代理不匹配的 gen_ai.agent.id。 路由 agentId 必须是调用应用的 appId 。 对于源自蓝图的标识，那是代理标识的 appId，而不是蓝图的 appId。 确保每个 span 的 gen_ai.agent.id 都匹配。
200 OK 但 partialSuccess.rejectedSpans == totalSpans 所有 span 都有一个错误的 gen_ai.operation.name。 使用 invoke_agent、execute_tool、chat、output_messages 中的一项。 是chat，不是inference。
200 OK 使用 partialSuccess: null，但 Defender 中未显示任何数据 客户租户中没有任何用户被分配 Microsoft 365 E7 或 Microsoft Agent 365 许可证（限制和删除条件）。 确认租户中至少有一个用户已被分配 Microsoft 365 E7 或 Microsoft Agent 365 许可证（仅有 SKU 并不够）。 使用 Verifying ingestion 中的 KQL 进行验证；如果 5 分钟后仍没有数据写入，请联系 Agent 365 团队。
跨度显示在 CloudAppEvents 中，但在 Defender 代理活动视图和 Microsoft 365 管理中心中缺少该运行记录 运行没有 invoke_agent 范围。 两个图面都关闭 invoke_agent。 在每次运行的根节点处恰好发出一个invoke_agent span；通过parentSpanId将chat / execute_tool / output_messages设为其子节点。
运行树已损坏/工具范围显示为孤立 子 span 上缺少 parentSpanId 或存在不同的 traceId。 请参阅Span 层次结构和运行分组。 每个非根跨度都会设置 parentSpanId 并共享该 run 的 traceId。
工具范围在查询中显示为空ChannelName / ConversationId 工具 span 上未设置通道/会话，且父级 invoke_agent 不在同一个 OTLP 请求中。 在每个 span 上设置 microsoft.channel.name 和 gen_ai.conversation.id。
413 Payload Too Large 请求正文 > 1 MB。 将跨度拆分到多个请求中。
429 Too Many Requests 已达到速率限制。 遵循 Retry-After: 1 并采用抖动退避。
代理在仪表板中显示为身份不明 gen_ai.agent.id 为空或不是 GUID。 使用代理的 Entra appId。 如果代理没有 Entra 注册，请参阅 选取值。

后续步骤

  • Last updated on