疑難排解直接 OTel 可觀察性

使用本指南驗證遙測資料擷取狀態，並診斷透過 OTLP 直接傳送至 Agent 365 之 Agent 遙測資料的相關問題。 本文僅涵蓋直接 OTel 路徑。如果您使用的是 Agent 365 SDK 或 Microsoft OpenTelemetry Distro，請改參閱這些指南。 如需傳輸層級限制、錯誤代碼及靜默捨棄狀況的詳細資訊，請參閱限制與捨棄狀況。

驗證擷取

200 OK 不代表已完成擷取。 部分捨棄狀況會傳回 200，並顯示 partialSuccess: null，但您的資料就是不會出現 (請參閱限制與捨棄狀況)。 務必先驗證您最初執行的結果：

  1. 檢查 HTTP 狀態。 200 → 繼續進行。 4xx → 請參閱常見錯誤。
  2. 剖析 partialSuccess。 null 表示 API 已接受所有內容。 其他任何值都代表至少有部分 span 在個別 span 篩選中遭到捨棄。
  3. 等候約 5 分鐘，然後執行下方的 Defender 進階搜捕查詢。
  4. 沒有資料列？ 請使用 Defender 中沒有資料一節中的決策樹。

Defender 進階搜捕查詢

標準查詢方式 (依您所傳送的 Agent 身分識別聯結)：

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 Agent 活動檢視、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 導入團隊。
  • Span 已出現，但執行樹狀結構損毀，部分子系變成孤項 → 缺少 parentSpanId、traceId 不一致，或並非每個 span 都設有 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，Agent 身分識別不相符 URL 中的 {agentId} ≠ 權杖的 appid / azp，或某個 span 帶有與已驗證 Agent 不符的 gen_ai.agent.id。 路由中的 agentId 必須是呼叫應用程式的 appId。 針對從藍圖衍生的身分識別，該值應為 Agent 身分識別的 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 並不足夠)。 請使用驗證擷取中的 KQL 進行驗證；如果 5 分鐘後仍無資料，請聯絡 Agent 365 團隊。
CloudAppEvents 中出現 span，但 Defender Agent 活動檢視和 Microsoft 365 系統管理中心中都缺少該執行記錄 該執行記錄沒有 invoke_agent span。 這兩個介面都是以 invoke_agent 為索引依據。 在每次執行的根層級發出剛好一個 invoke_agent span，並透過 parentSpanId 讓 chat / execute_tool / output_messages 成為其子系。
執行樹狀結構損毀／工具 span 看似孤項 子系 span 缺少 parentSpanId，或 traceId 不一致。 請參閱 Span 階層與執行分組。 每個非根層級的 span 都要設定 parentSpanId，並共用該次執行的 traceId。
查詢中工具 span 的 ChannelName / ConversationId 顯示為空白 工具 span 未設定通道／交談，且父項 invoke_agent 未包含在相同的 OTLP 要求中。 請在每個 span 上設定 microsoft.channel.name 和 gen_ai.conversation.id。
413 Payload Too Large 要求主體 > 1 MB。 將 span 分散到多個要求中。
429 Too Many Requests 已達到速率限制。 請遵循 Retry-After: 1，並使用隨機延遲進行退避。
儀表板中 Agent 顯示為未識別 gen_ai.agent.id 為空白，或不是 GUID。 請使用該 Agent 的 Entra appId。 若 Agent 沒有 Entra 註冊，請參閱 選擇值。

後續步驟

  • Last updated on