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

Utilisez ce guide pour vérifier l’ingestion de télémétrie et diagnostiquer les problèmes liés aux données de télémétrie envoyées par l’agent directement à Agent 365 via OTLP. Cela concerne uniquement le chemin OTel direct ; si vous utilisez le SDK Agent 365 ou le Microsoft OpenTelemetry Distro, consultez plutôt ces guides. Pour connaître les limites au niveau du câble, les codes d’erreur et les conditions de suppression silencieuse, consultez Limites et conditions de suppression.

Vérification de l’ingestion

Un code 200 OK n’est pas une preuve d’ingestion. Certaines conditions de suppression retournent 200 avec partialSuccess: null et vos données n’apparaissent pas simplement (voir Limites et conditions de suppression). Vérifiez toujours vos premiers lancements :

  1. Vérifiez l’état HTTP. 200 → poursuivre. 4xx → voir les pièges courants.
  2. Analyser partialSuccess. null signifie que l’API a tout accepté. Dans tous les autres cas, cela signifie qu’au moins certains segments ont été rejetés lors du filtrage par segment.
  3. Wait environ 5 minutes, puis exécutez la requête Defender advanced-hunting ci-dessous.
  4. Aucune ligne ? Utilisez l’arbre de décision sous Aucune donnée dans Defender.

requête de recherche avancée Defender

Recherche canonique (jointure sur l’identité de l’agent 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 obtenir la liste complète des surfaces (vues d’activité de l’agent Defender, Microsoft 365 admin center, Microsoft Purview) et ce dont chacun a besoin, consultez Partout où vos données s’affichent.

Aucune donnée dans Defender

  • partialSuccess.rejectedSpans == totalSpans → toutes vos étendues avaient un mauvais gen_ai.operation.name. Correction : utilisez l’un de invoke_agent, execute_tool, chat, output_messages (c’est chat, pas inference).
  • 200 avec partialSuccess: null mais aucune ligne Defender après 5 min → aucun utilisateur dans le locataire du client n’a de licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée (Limites et conditions de suppression, condition de suppression 2). Correctif : vérifiez qu’au moins un utilisateur dans le locataire a la licence attribuée (et non simplement présente dans le locataire) ; sinon, 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. Correction : passez en revue la hiérarchie des spans et le regroupement des runs.

Pièges courants

Symptôme Cause la plus probable Réparer
401 Unauthorized Erreur aud sur le jeton. Utiliser 9b975845-388f-4429-889e-eab1ef63949c (ou api://9b975845-...).
403 Forbidden, rôle manquant / portée Le jeton ne contient pas Agent365.Observability.OtelWrite. Intégrez votre application Microsoft Entra pour le rôle (S2S) ou l’autorisation (déléguée), conformément à Autorisations et consentement. Pour S2S, le jeton doit être acquis avec <resource>/.default.
403 Forbidden, incompatibilité d’identité de l’agent {agentId} dans l’URL ≠ appid / azp du jeton, ou un span porte un gen_ai.agent.id qui ne correspond pas à celui de l’agent authentifié. L’itinéraire agentId doit être l’appId de l’application appelante. Pour les identités dérivées du blueprint, c’est-à-dire l’appId d’identité de l’agent, et non l’appId de blueprint. Assurez-vous que chaque span correspond à gen_ai.agent.id.
200 OK Mais partialSuccess.rejectedSpans == totalSpans Tous les spans contenaient un gen_ai.operation.name incorrect. Utilisez l’un des invoke_agent, , execute_toolchat, output_messages. C’est chat, pas inference.
200 OK avec partialSuccess: null, mais aucune donnée n’apparaît dans Defender Aucun utilisateur du locataire client ne dispose d’une licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée (Limites et conditions de suppression). Vérifiez qu'au moins un utilisateur du locataire a une licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée (la référence SKU présente n'est pas suffisante). Vérifiez avec KQL lors de la vérification de l’ingestion ; si rien ne atterrit après 5 minutes, contactez l’équipe agent 365.
Des segments apparaissent dans CloudAppEvents, mais l’exécution est absente des vues d’activité de l’agent de Defender et du centre d’administration Microsoft 365 Le segment ne comporte pas de invoke_agent span. Les deux surfaces dépendent de invoke_agent. Émettez exactement une balise invoke_agent à la racine de chaque exécution ; faites de chat / execute_tool / output_messages les enfants de celle-ci via parentSpanId.
L’arborescence d’exécution est rompue/ les étendues d’outils apparaissent orphelines parentSpanId manquant ou traceId différent dans les spans enfants. Voir Hiérarchie des segments et groupement des segments. Chaque span non racine définit parentSpanId et partage le traceId de l’exécution.
Les segments d’outil apparaissent vides ChannelName / ConversationId dans les requêtes Le canal ou la conversation n’est pas renseigné sur le span de l’outil, et le parent invoke_agent n’était pas inclus dans la même requête OTLP. Définissez microsoft.channel.name et gen_ai.conversation.id sur chaque étendue.
413 Payload Too Large Corps de la requête > 1 Mo. Répartissez les intervalles sur plusieurs requêtes.
429 Too Many Requests Limite de débit atteinte. Honorez Retry-After: 1 et reculez avec gigue.
L’agent apparaît non identifié dans les tableaux de bord gen_ai.agent.id est vide ou n’est pas un GUID. Utilisez l’id d’application Entra de l’agent. Si l’agent n’a pas d’enregistrement Entra, consultez Choix des valeurs.

Étapes suivantes

  • Last updated on