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. Il est orienté vers le chemin OTel direct – si vous utilisez l’Agent 365 Observability SDK (obsolète) ou la distribution OpenTelemetry de Microsoft, 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érifier l’ingestion

Un 200 OK n’est pas une preuve d’ingestion. Certaines conditions de rejet renvoient un code 200, même si le champ results de la réponse indique que les spans ont été rejetés. Vérifiez toujours vos premiers lancements :

  1. Vérifiez l’état HTTP. 200 → poursuivre. 4xx → voir les pièges courants.
  2. Inspectez results. Pour chaque travée, confirmez que la destination concernée a un statut de sent. Un statut de rejected ou not_routed inclut une raison.
  3. Analyser partialSuccess. Ce champ signale certains échecs de filtrage au niveau des spans, mais une valeur de 0 ne garantit pas que le span a été acheminé.
  4. Attendez ~5 minutes, puis lancez la requête de chasse avancée Defender dans la section suivante.
  5. 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’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’agent Defender, Microsoft 365 admin center, Microsoft Purview) et ce dont chacune a besoin, voir Où apparaissent les données d’observabilité de l’Agent 365.

Aucune donnée dans Defender

  • partialSuccess.rejectedSpans == totalSpans → tous vos spans avaient un mauvais gen_ai.operation.name. Correction : utiliser l’un des invoke_agent, execute_tool, chat, output_messages (c’est chat, non inference).
  • results indique rejected avec la raison tenant_not_licensed → le tenant n’est actuellement pas éligible. Correction : confirmez qu'au moins un utilisateur du locataire a une licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée, puis vérifiez l'éligibilité du locataire.
  • Des spans apparaissent, mais l’arbre des runs est cassé ou certains 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 aud incorrect sur le jeton. Utiliser 9b975845-388f-4429-889e-eab1ef63949c (ou api://9b975845-...).
403 Forbidden, rôle, champ d’application ou enregistrement manquant Sur la route S2S, l’instance de l’agent n’est pas enregistrée auprès de l’Agent 365 et le jeton ne porte pas le Agent365.Observability.OtelWrite rôle d’application. Sur l’itinéraire délégué, le token ne porte pas le scope délégué. Pour une instance d’agent dérivée du blueprint, confirmez que l’enregistrement de l’Agent 365 est terminé. Pour réessayer, voir Réessayer un enregistrement ayant échoué. Pour d’autres identités S2S, inscrivez votre application Microsoft Entra au rôle d’application. Pour les appels délégués, intégrez l’application à la portée déléguée. Voir Champs d’application et consentement. Pour S2S, acquérez le jeton avec <resource>/.default.
403 Forbidden, incompatibilité d’identité de l’assistant {agentId} dans l’URL ≠ appid ou azp du jeton, ou un span contient un gen_ai.agent.id qui ne correspond pas à l’assistant authentifié. L’itinéraire 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 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 results affichant rejected et la raison tenant_not_licensed Le locataire n’est actuellement pas éligible à l’observabilité. Confirmez qu'au moins un utilisateur du locataire a une licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée (la présence du SKU ne suffit pas), puis utilisez la vérification optionnelle d'éligibilité du locataire.
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 run ; faites de chat, execute_tool et output_messages ses enfants via parentSpanId.
L’arborescence d’exécution est rompue ou 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 spans d’outil affichent des valeurs vides pour ChannelName ou ConversationId dans les requêtes Le canal ou la conversation n’est pas défini dans 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 é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. Respectez l’en-tête Retry-After: 1 et appliquez une temporisation progressive 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’appId Entra de l’assistant. Si l’agent n’a pas d’enregistrement Entra, consultez Choix des valeurs.

Vérification préalable de l’éligibilité du locataire

Les intégrations S2S tierces intégrées peuvent utiliser le point d’éligibilité optionnel du locataire avant d’activer une intégration ou d’envoyer la télémétrie. Si votre intégration utilise ce point de terminaison, les instructions suivantes peuvent vous aider à interpréter ses réponses.

Symptôme Cause la plus probable Réparer
L’éligibilité renvoie 200 OK avec enabled: false Le locataire ne remplit pas actuellement les critères d’éligibilité. N’envoyez pas de télémétrie. Vérifiez que le locataire remplit les prérequis, puis vérifiez à nouveau après que son statut change.
Résultats d’éligibilité 403 Forbidden Le jeton ne contient pas Agent365.Observability.OtelWrite, ou le jeton tid ne correspond pas à {tenantId} dans l’URL. Corrigez l’attribution du rôle d’application, le consentement du locataire ou la non-correspondance du locataire.
Résultats d’éligibilité 429 Too Many Requests L’appelant a dépassé la limite d’éligibilité demandée. Respectez la valeur de Retry-After la réponse et réessayez avec du recul et du tremblement.
L’éligibilité renvoie un code 503 Service Unavailable sans corps de réponse L’éligibilité n’a pas pu être déterminée. Respectez Retry-After: 30 et réessayez. N’interprétez pas le corps manquant comme enabled: false.

Étapes suivantes

  • Dernière mise à jour :