Résoudre les problèmes d’observabilité OTel directe

Utilisez ce guide pour vérifier l’ingestion de télémétrie et diagnostiquer les problèmes liés à la télémétrie d’assistant envoyée directement à Agent 365 via OTLP. Cette configuration s’applique uniquement au chemin OTel direct. Si vous utilisez le SDK Agent 365 ou la distribution Microsoft OpenTelemetry, consultez plutôt les guides correspondants. Pour connaître les limites au niveau du protocole, les codes d’erreur et les conditions entraînant un abandon silencieux, consultez Limites et conditions d’abandon.

Vérification de l’ingestion

Un code d’état 200 OK ne constitue pas une preuve de l’ingestion. Certaines conditions d’abandon renvoient un code 200 avec partialSuccess: null et vos données n’apparaissent tout simplement pas (voir Limites et conditions d’abandon). Vérifiez toujours vos premières exécutions :

  1. Vérifier le statut HTTP. 200 → continuer. 4xx → voir Pièges courants.
  2. Analyser partialSuccess. null signifie que l’API a tout accepté. Tout autre résultat signifie qu’au moins certains spans ont été rejetés au niveau du filtre par span.
  3. Patientez ~5 minutes, puis exécutez la requête avancée de Defender ci-dessous.
  4. Aucune ligne ? Utilisez l’arbre de décision sous Aucune donnée dans Defender.

Requête de chasse avancée dans Defender

Recherche canonique (jointure sur l’identité de l’assistant que vous avez envoyée) :

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

Pour la liste complète des surfaces (vues d’activité d’assistant Defender, Centre d’administration Microsoft 365, Microsoft Purview) et ce dont chacune a besoin, consultez Où apparaissent vos données.

Aucune donnée dans Defender

  • partialSuccess.rejectedSpans == totalSpans → toutes vos étendues avaient un mauvais gen_ai.operation.name. Correction : utiliser l’un des invoke_agent, execute_tool, chat, output_messages (c’est chat, non inference).
  • Code 200 avec partialSuccess: null, mais aucune ligne Defender après 5 minutes → aucun utilisateur du locataire client ne possède de licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée (voir Limites et conditions d’abandon, condition d’abandon n° 2). Correction : vérifiez qu’au moins un utilisateur du locataire s’est vu attribuer la licence (et qu’elle n’est pas simplement présente dans le locataire) ; dans le cas contraire, contactez l’équipe d’intégration d’Agent 365.
  • Les spans s’affichent, mais l’arborescence est rompue / certains spans enfants sont orphelins → parentSpanId manquant, traceId différent ou gen_ai.conversation.id non défini sur chaque span. Correctif : consultez Hiérarchie des spans et regroupement des exécutions.

Pièges courants

Problème Cause la plus probable Correction
401 Unauthorized Erreur aud sur le jeton. Utilisez 9b975845-388f-4429-889e-eab1ef63949c (ou api://9b975845-...).
403 Forbidden, rôle/étendue manquant(e) Le jeton ne contient pas Agent365.Observability.OtelWrite. Intégrez votre application Microsoft Entra pour le rôle (S2S) ou l’étendue (déléguée), conformément à Étendues et consentement. Pour S2S, le jeton doit être acquis avec <resource>/.default.
403 Forbidden, incompatibilité d’identité de l’assistant {agentId} dans l’URL ≠ appid / azp du jeton, ou un span porte un gen_ai.agent.id qui ne correspond pas à celui de l’assistant authentifié. La route agentId doit être l’appId de l’application appelante. Pour les identités dérivées du blueprint, il s’agit de l’appId de l’identité de l’assistant, et non de l’appId du blueprint. Assurez-vous que le gen_ai.agent.id de chaque span corresponde.
200 OK mais partialSuccess.rejectedSpans == totalSpans Tous les spans avaient une valeur incorrecte pour gen_ai.operation.name. Utilisez l’une des options suivantes : invoke_agent, execute_tool, chat, output_messages. C’est chat, non inference.
200 OK avec partialSuccess: null mais aucune donnée n’apparaît dans Defender Aucun utilisateur du locataire client n’a de licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée (limites et conditions d’abandon). Vérifiez qu’au moins un utilisateur du locataire s’est vu attribuer une licence Microsoft 365 E7 ou Microsoft Agent 365 (la simple présence de la référence SKU dans le locataire ne suffit pas). Vérifiez à l’aide de la requête KQL dans Vérification de l’ingestion ; si rien n’arrive après 5 minutes, contactez l’équipe Agent 365.
Des spans apparaissent dans CloudAppEvents, mais l’exécution n’apparaît ni dans les vues d’activité des assistants de Defender ni dans le centre d’administration Microsoft 365 L’exécution ne comporte pas de span invoke_agent. Les deux vues reposent sur invoke_agent. Émettez exactement un span invoke_agent à la racine de chaque exécution ; faites de chat / execute_tool / output_messages des spans enfants via parentSpanId.
L’arborescence d’exécution est rompue / les spans d’outil apparaissent comme orphelins parentSpanId manquant ou traceId différent dans les spans enfants. Voir Hiérarchie des spans et regroupement des exécutions. Chaque span non racine définit parentSpanId et partage le traceId de l’exécution.
Les étendues d’outil affichent des valeurs vides pour ChannelName / ConversationId dans les requêtes Canal/conversation non défini(e) sur le span d’outil, et le parent invoke_agent ne figurait pas dans la même requête OTLP. Définissez microsoft.channel.name et gen_ai.conversation.id sur chaque span.
413 Payload Too Large Corps de la requête > 1 Mo. Répartissez les spans sur plusieurs requêtes.
429 Too Many Requests Limite de taux atteinte. Respectez l’en-tête Retry-After: 1 et appliquez une temporisation progressive avec gigue.
L’assistant apparaît non identifié dans les tableaux de bord gen_ai.agent.id est vide ou n’est pas un GUID. Utilisez l’appId Entra de l’assistant. Si l’assistant ne dispose pas d’un enregistrement Entra, voir Sélection des valeurs.

Étapes suivantes

  • Last updated on