直接 OTel 可观测性故障排除

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

验证引入

“200 正常”不能证明已经引入。 某些删除条件会为 partialSuccess: null 返回 200，您的数据根本不会显示（参阅限制和删除条件）。 始终验证第一次运行：

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

常见陷阱

症状 最有可能的原因 修复
401 Unauthorized 令牌上的 aud 错误。 使用 9b975845-388f-4429-889e-eab1ef63949c （或 api://9b975845-...）。
403 Forbidden，缺少角色/范围 令牌不包含 Agent365.Observability.OtelWrite。 根据范围和同意，将 Microsoft Entra 应用加入角色 (S2S) 或范围（委派）。 对于 S2S，必须使用 <resource>/.default 获取令牌。
403 Forbidden，代理标识不匹配 URL 中的 {agentId} ≠ 令牌的 appid / azp，或者跨度携带与已经过身份验证的智能体不匹配的 gen_ai.agent.id。 路由 agentId 必须是调用应用的 appId 。 对于蓝图派生的身份，是智能体身份 appId，不是蓝图 appId。 确保每个 span 的 gen_ai.agent.id 都匹配。
200 OK 但 partialSuccess.rejectedSpans == totalSpans 所有跨度都有有问题的 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 跨度；通过 parentSpanId 将 chat / execute_tool / output_messages 设为其子节点。
运行树损坏/工具跨度显示为孤立 子跨度上缺少 parentSpanId 或存在不同的 traceId。 请参阅Span 层次结构和运行分组。 每个非根跨度都会设置 parentSpanId 并共享运行的 traceId。
工具跨度在查询中显示空 ChannelName / ConversationId 工具跨度上未设置渠道/对话，父 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