Fehlerbehebung für direkte OTel-Observability

Verwenden Sie dieses Handbuch, um die Telemetrieaufnahme zu überprüfen und Probleme mit Agent-Telemetrie zu diagnostizieren, die direkt über OTLP an Agent 365 gesendet werden. Es ist auf den direkten OTel-Pfad beschränkt – wenn du das Agent 365 SDK oder die Microsoft OpenTelemetrie-Distribution verwendest, sieh dir stattdessen diese Anleitungen an. Informationen zu Grenzwerten auf Übertragungsebene, Fehlercodes und Bedingungen für stillschweigendes Verwerfen finden Sie unter Grenzen und Bedingungen für das Verwerfen.

Überprüfen der Aufnahme

Ein 200 OK ist kein Beweis für die Erfassung. Einige Bedingungen für das Verwerfen geben 200 zurück, obwohl die results in der Antwort zeigen, dass die Spans abgelehnt wurden. Überprüfen Sie immer ihre ersten Ausführungen:

  1. Http-Status überprüfen. 200 → fortfahren. 4xx → siehe häufige Fallstricke.
  2. Prüfen Sie results. Für jede Spanne wird bestätigt, dass das relevante Ziel den Status von senthat. Ein Status von rejected oder not_routed enthält einen Grund.
  3. Analysieren Sie partialSuccess. Dieses Feld meldet einige Fehlschläge bei der Filterung pro Span, aber ein Wert von 0 garantiert nicht, dass der Span weitergeleitet wurde.
  4. Warte ~5 Minuten und führe dann die Defender-Abfrage für fortgeschrittene Jagd im folgenden Abschnitt durch.
  5. Keine Zeile? Verwenden Sie den Entscheidungsbaum unter Keine Daten in Defender.

Erweiterte Hunting-Abfrage von Defender

Die kanonische Suche (Verknüpfung über die von Ihnen gesendete Agent-Identität):

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

Die vollständige Liste der Bereiche (Ansichten zur Defender-Agentenaktivität, Microsoft 365 Admin Center, Microsoft Purview) sowie die jeweiligen Anforderungen finden Sie unter Wo Agent 365-Beobachtbarkeitsdaten angezeigt werden.

Keine Daten in Defender

  • partialSuccess.rejectedSpans == totalSpans → alle Ihre Spans wiesen einen fehlerhaften gen_ai.operation.name auf. Lösung: Verwenden Sie eine von invoke_agent, execute_tool, chat, output_messages (es ist chat, nicht inference).
  • results Zeigt rejected mit Begründung tenant_not_licensed , → der Mieter derzeit nicht berechtigt ist. Lösung: Stellen Sie sicher, dass mindestens einem Benutzer im Mandanten eine Microsoft 365 E7- oder Microsoft Agent 365-Lizenz zugewiesen ist, und prüfen Sie dann die Eignung des Mandanten.
  • Spannweiten erscheinen, aber der Laufbaum ist kaputt oder einige Kinder werden verwaist → fehlen parentSpanId, anders traceIdoder gen_ai.conversation.id nicht auf jeder Spannweite gesetzt. Problembehebung: Überprüfen Sie die Span-Hierarchie und Ausführungsgruppierung.

Häufige Fallstricke

Symptom Wahrscheinlichste Ursache Beheben
401 Unauthorized Ungültige aud beim Token. Verwenden 9b975845-388f-4429-889e-eab1ef63949c (oder api://9b975845-...).
403 Forbidden, fehlende Rolle oder fehlender Geltungsbereich Das Token enthält Agent365.Observability.OtelWrite nicht. Registrieren Sie Ihre Microsoft Entra-App gemäß Bereiche und Einwilligung für die Rolle (S2S) bzw. den Bereich (delegiert). Für S2S muss das Token mit <resource>/.default abgerufen werden.
403 Forbidden, Nichtübereinstimmung der Agent-Identität {agentId} in URL ≠ appid oder azp des Tokens, oder ein Span trägt ein gen_ai.agent.id, das nicht mit dem authentifizierten Agenten übereinstimmt. Die Route agentId muss die App-ID der aufrufenden App sein. Bei von Blueprint abgeleiteten Identitäten ist dies die appId der Agent-Identität, nicht die appId des Blueprints. Stellen Sie sicher, dass das die gen_ai.agent.id jedes Span übereinstimmt.
200 OK Aber partialSuccess.rejectedSpans == totalSpans Alle Spans wiesen einen fehlerhaften gen_ai.operation.name auf. Verwenden Sie eines von invoke_agent, execute_tool, chat, output_messages. Es ist chat, nicht inference.
200 OK mit results, Anzeige von rejected und Grund tenant_not_licensed Der Mandant ist derzeit nicht für Observability berechtigt. Bestätigen Sie, dass mindestens ein Nutzer im Tenant eine Microsoft 365 E7- oder Microsoft Agent 365-Lizenz zugewiesen hat (die vorhandene SKU reicht nicht aus), und nutzen Sie dann die optionale Mieterberechtigungs-Prüfung.
Spans werden in CloudAppEvents angezeigt, aber die Ausführung fehlt in den Defender-Ansichten zur Agent-Aktivität und im Microsoft 365 Admin Center. Die Ausführung hat keinen invoke_agent-Span. Beide Oberflächen basieren auf invoke_agent. Geben Sie auf der Stammebene jedes Durchlaufs genau ein invoke_agent-Span aus; machen Sie chat, execute_tool und output_messages über parentSpanId zu dessen untergeordneten Elementen.
Der Laufbaum ist kaputt oder Werkzeugspannweiten erscheinen verwaist parentSpanId fehlt oder traceId weicht bei untergeordneten Spans ab. Siehe Span-Hierarchie und Run-Gruppierung. Jeder Span, der kein Stammelement ist, legt parentSpanId fest und teilt sich die traceId der Ausführung.
Tool-Spans weisen in Abfragen leere ChannelName oder ConversationId auf. Kanal oder Unterhaltung war für den Tool-Span nicht festgelegt, und der übergeordnete invoke_agent befand sich nicht in derselben OTLP-Anforderung. Legen Sie microsoft.channel.name und gen_ai.conversation.id für jede Spanne fest.
413 Payload Too Large Anfragetextkörper > 1 MB. Teilen Sie die Spans auf mehrere Anforderungen auf.
429 Too Many Requests Ratenlimit erreicht. Beachten Sie Retry-After: 1, und führen Sie einen Backoff mit Jitter durch.
Agent wird in Dashboards nicht identifiziert gen_ai.agent.id ist leer oder ist keine GUID. Verwenden Sie die Entra-AppId des Agents. Wenn der Agent keine Entra-Registrierung hat, siehe Werte auswählen.

Vorflugberechtigung für Mieter

Integrierte Drittanbieter-S2S-Integrationen können den optionalen Mieterberechtigungsendpunkt nutzen, bevor eine Integration aktiviert oder Telemetrie gesendet wird. Wenn Ihre Integration diesen Endpunkt verwendet, kann Ihnen die folgende Anleitung helfen, die Antworten zu interpretieren.

Symptom Wahrscheinlichste Ursache Beheben
Die Berechtigung gibt 200 OK mit enabled: false zurück. Der Mieter erfüllt derzeit nicht die Anspruchsvoraussetzungen für die Berechtigung. Senden Sie keine Telemetrie. Überprüfen Sie, ob der Mieter die Voraussetzungen erfüllt, und überprüfen Sie es erneut, nachdem sich sein Status geändert hat.
Die Berechtigung gibt 403 Forbidden zurück. Dem Token fehlt Agent365.Observability.OtelWrite, oder das Token tid stimmt nicht mit {tenantId} in der URL überein. Korrigieren Sie die App-Rollenzuweisung, die Mandantenzustimmung oder den Mandantenkonflikt.
Die Berechtigung gibt 429 Too Many Requests zurück. Der Anrufer hat die Berechtigungsbeantragungsgrenze überschritten. Beachten Sie den Retry-After-Wert der Antwort und versuchen Sie es mit Backoff und Jitter erneut.
Die Berechtigung gibt 503 Service Unavailable ohne Textkörper zurück. Die Berechtigung konnte nicht festgestellt werden. Beachten Sie Retry-After: 30, und versuchen Sie es erneut. Interpretiere die fehlende Leiche nicht als enabled: false.

Nächste Schritte

  • Last updated on