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

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

取り込みの確認

200 OK は、取り込みが行われたことの証拠ではありません。 一部のドロップ条件では、 partialSuccess: null で 200 が返され、データは表示されません ( 制限とドロップ条件を参照)。 常に最初の実行を確認します。

  1. HTTP の状態を確認します。 200 → 続行。 4xx → 一般的な落とし穴を参照してください。
  2. partialSuccessを解析します。 null は、API がすべてを受け入れたことを意味します。 それ以外の場合は、スパンごとのフィルターで少なくとも一部のスパンが削除されたことを意味します。
  3. 約5分待って、その後、以下の Defender の高度なハンティング クエリを実行します。
  4. 行がありませんか? 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) と各サーフェスに必要なものについては、「データが表示される場所>」を参照してください。

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）。 修正: テナント内の少なくとも 1 人のユーザーにライセンスが割り当てられている (テナントに存在するだけでなく) か確認します。それ以外の場合は、エージェント 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、エージェント 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 と partialSuccess: null があるが、Defender にデータが表示されない 顧客テナント内のどのユーザーにも、Microsoft 365 E7 または Microsoft Agent 365 ライセンスが割り当てられていません（制限およびドロップ条件）。 テナント内の少なくとも 1 人のユーザーに Microsoft 365 E7 または Microsoft Agent 365 ライセンスが割り当てられていることを確認します (存在する SKU では不十分です)。 インジェストの検証で KQL を使用して確認します。5 分後に何も着陸しない場合は、エージェント 365 チームにお問い合わせください。
CloudAppEvents にはスパンが表示されていますが、Defender のエージェントアクティビティ ビューと Microsoft 365 管理センターには実行履歴が表示されていません 実行には invoke_agent span が含まれていません。 両方のサーフェスは invoke_agent を基準にしています。 各ランのルートに、invoke_agent スパンを 1 つだけ生成し、 parentSpanId を使用して、chat / execute_tool / output_messages の子を作成します。
実行ツリーが壊れている / ツール スパンが孤立して表示される 子要素のスパンに 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 登録がない場合は、「 値の選択」を参照してください。

次のステップ

  • Last updated on