OTel 直接可観測性のトラブルシューティング

このガイドを使用して、テレメトリの取り込みを確認し、OTLP 経由でエージェント 365 に直接送信されるエージェント テレメトリに関する問題を診断します。 これは直接OTelパスを対象としています。もし廃止されたAgent 365 Observability SDKやMicrosoft OpenTelemetry Distroを使っているなら、そちらのガイドを参照してください。 ワイヤ レベルの制限、エラー コード、サイレント ドロップ条件については、「 制限とドロップ条件」を参照してください。

インジェストの確認

200のOKは摂取の証明にはなりません。 一部のドロップ条件は、回答の results がスパンが却下されたことを示しているにもかかわらず200を返すこともあります。 常に最初の実行を確認します。

  1. HTTP の状態を確認します。 200 → 続行。 4xx → 一般的な落とし穴を参照してください。
  2. resultsを検査します。 各スパンごとに、該当する目的地のステータスが sentであることを確認しましょう。 rejectedまたはnot_routedのステータスには理由が含まれます。
  3. partialSuccessを解析します。 このフィールドは一部のスパンごとのフィルタリング失敗を報告しますが、 0 の値があってもスパンがルーティングされたことを保証するわけではありません。
  4. ~5分待ってから、次のセクションでDefenderのアドバンスドハンティングクエリを実行してください。
  5. 行がありませんか? Defender にデータがない の下にある決定ツリーを使用してください。

Defender の高度なハンティング クエリ

正規の検索 (送信したエージェント ID を基に結合):

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）と、各表示先で必要なものについては、Agent 365 の可観測性データの表示先を参照してください。

Defenderにデータがありません

  • partialSuccess.rejectedSpans == totalSpans → すべてのスパンで不正な gen_ai.operation.name がありました。 解決策:invoke_agent、execute_tool、chat、output_messages(inferenceではなくchat)を使うことです。
  • results は、理由 rejected によりテナントが現在対象外であることを tenant_not_licensed で示します。 解決策:テナント内の少なくとも1人のユーザーがMicrosoft 365 E7またはMicrosoft Agent 365のライセンスを割り当てているか確認し、そのテナントの適格性を確認してください。
  • スパンは表示されますが、run ツリーが壊れているか、一部の子要素が孤立しています → parentSpanId が欠落している、traceId が異なっている、または gen_ai.conversation.id がすべてのスパンに設定されていません。 修正:スパン階層を確認し、グループ化を実行します。

よくある落とし穴

症状: 最も可能性の高い原因 修正
401 Unauthorized トークンの aud が正しくありません。 9b975845-388f-4429-889e-eab1ef63949c (またはapi://9b975845-...) を使用します。
403 Forbidden にロール、スコープ、または登録がありません S2Sルートでは、エージェント インスタンスは Agent 365 に登録されておらず、トークンにも Agent365.Observability.OtelWrite app role が含まれていません。 委任ルートでは、トークンは委任されたスコープを持ちません。 ブループリント由来のエージェントインスタンスの場合は、エージェント365の登録が完了したことを確認してください。 再試すには「失敗した登録を再試行する」をご覧ください。 その他の S2S ID については、Microsoft Entra アプリをアプリのロールにオンボードしてください。 委任通話の場合は、アプリを委任スコープにオンボードします。 スコープと同意を参照してください。 S2Sの場合は、 <resource>/.defaultでトークンを取得してください。
403 Forbidden、エージェント ID の不一致 URL 内の {agentId} がトークンの appid または azp と一致しない、またはスパンが認証済みエージェントと一致しない gen_ai.agent.id を持つ。 ルート agentId は、呼び出し元アプリの appId である必要があります。 ブループリントから派生した ID の場合、それはブループリントの appId ではなく、エージェント ID の appId です。 すべてのスパンの gen_ai.agent.id が一致していることを確認します。
200 OK だがしかし partialSuccess.rejectedSpans == totalSpans すべてのスパンに不正な gen_ai.operation.name がありました。 invoke_agent、execute_tool、chat、output_messagesのいずれかを使用します。 chatではなく、inferenceです。
200 OK resultsにはrejectedと理由tenant_not_licensedが表示されている テナントは現在、観測対象外です。 テナント内の少なくとも1人のユーザーがMicrosoft 365 E7またはMicrosoft Agent 365のライセンスを割り当てているか確認してください(SKUが存在しているだけでは不十分です)。その後、オプションのテナント適格性チェックを使います。
CloudAppEvents にはスパンが表示されていますが、Defender のエージェントアクティビティ ビューと Microsoft 365 管理センターには実行履歴が表示されていません 実行には invoke_agent span が含まれていません。 両方のサーフェスは invoke_agent を基準にしています。 各 run のルートに invoke_agent span を1つだけ正確に出力し、output_messages を介して parentSpanId、chat、execute_tool をその子要素にします。
実行ツリーが壊れている、またはツール スパンが孤立して表示される 子要素のスパンに parentSpanId が欠落しているか、traceId が異なります。 スパン階層と実行グループを参照してください。 ルート以外のすべてのスパンは parentSpanId を設定し、実行の traceIdを共有します。
ツールスパンはクエリ内で空の ChannelName や ConversationId として表示される ツールスパンにチャンネルや会話が設定されておらず、親 invoke_agent も同じOTLPリクエストに含まれていませんでした。 すべてのスパンで 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 登録がない場合は、「 値の選択」を参照してください。

テナント利用資格の事前確認

オンボーディングされたサードパーティのS2S統合は、統合を有効にする前にオプションの テナント適格エンドポイント を利用可能で、テレメトリを送信できます。 もしあなたの統合がこのエンドポイントを使用している場合、以下のガイダンスがその応答を解釈するのに役立ちます。

症状: 最も可能性の高い原因 修正
Eligibility は enabled: false とともに 200 OK を返します 借主は現在、適格要件を満たしていません。 テレメトリは送らないでください。 テナントが 前提条件を満たしているか確認し、ステータスが変わったら再度確認してください。
適格性が 403 Forbidden を返します トークンにAgent365.Observability.OtelWriteが欠けているか、URLのトークンtid{tenantId}と一致しない場合があります。 アプリ ロールの割り当て、テナントの同意、またはテナントの不一致を修正してください。
適格性が 429 Too Many Requests を返します 発信者は申請資格の上限を超えました。 返答の Retry-After 価値を尊重し、バックオフとジッターで再挑戦しましょう。
適格性がボディのない 503 Service Unavailable を返します 適格性は判定できませんでした。 Retry-After: 30 を尊重して、再試行してください。 失われた遺体を enabled: falseと解釈しないでください。

次のステップ

  • 最終更新: