Solución de problemas de observabilidad directa de OTel

Utilice esta guía para verificar la ingesta de telemetría y diagnosticar problemas con la telemetría del agente enviada a Agent 365 directamente a través de OTLP. Se limita a la ruta directa de OTel; si usas el obsoleto Agent 365 Observability SDK o la Microsoft OpenTelemetry Distro, consulta esas guías en su lugar. Para conocer los límites de nivel de conexión, los códigos de error y las condiciones de eliminación silenciosa, consulte Límites y condiciones de eliminación.

Comprobación de la ingesta

Un 200 OK no es prueba de ingestión. Algunas condiciones de descarte devuelven 200 aunque la results de la respuesta muestra que los spans fueron rechazados. Compruebe siempre las primeras ejecuciones:

  1. Compruebe el estado HTTP. 200 → continuar. 4xx → ver problemas comunes.
  2. Inspeccione results. Para cada tramo, confirme que el destino aplicable tiene un estado de sent. Un estado de rejected o not_routed incluye una razón.
  3. partialSuccessAnalizar . Este campo indica algunos fallos de filtrado por tramo, pero un valor de 0 no garantiza que el tramo se haya enrutado.
  4. Espera ~5 minutos y luego ejecuta la consulta de caza avanzada de Defender en la siguiente sección.
  5. ¿No hay fila? Use el árbol de decisión debajo de No data in Defender.

Consulta de búsqueda avanzada de Defender

Búsqueda canónica (unión a la identidad del agente que envió):

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

Para la lista completa de superficies (vistas de actividad de agentes de Defender, Centro de administración de Microsoft 365, Microsoft Purview) y lo que cada una necesita, consulta Dónde aparecen los datos de observabilidad del Agente 365.

No hay datos en Defender

  • partialSuccess.rejectedSpans == totalSpans → todas tus trazas tenían un gen_ai.operation.name incorrecto. Solución: usar uno de invoke_agent, execute_tool, chat, output_messages (es chat, no inference).
  • results muestra rejected con el motivo tenant_not_licensed → el inquilino actualmente no cumple los requisitos. Solución: confirma que al menos un usuario del tenant tiene asignada una licencia Microsoft 365 E7 o Microsoft Agent 365, y luego revisa la elegibilidad del tenant.
  • Aparecen tramos, pero el árbol de la pista está roto o algunos niños quedan huérfanos → falta parentSpanId, diferentes traceIdo gen_ai.conversation.id no colocados en cada tramo. Corrección: revise la jerarquía de intervalos y ejecute la agrupación.

Dificultades habituales

Síntoma Causa más probable Corregir
401 Unauthorized Error en aud del token. Use 9b975845-388f-4429-889e-eab1ef63949c (o api://9b975845-...).
403 Forbidden, falta de rol, alcance o inscripción En la ruta S2S, la instancia del agente no está registrada con el Agente 365 y el token no lleva el Agent365.Observability.OtelWrite rol de app. En la ruta delegada, el token no lleva el alcance delegado. Para una instancia de agente derivada de plantillas, confirma que el registro de Agent 365 se ha completado. Para volver a intentarlo, consulta Reintentar un registro con errores. Para otras identidades S2S, incorpora tu aplicación de Microsoft Entra en el rol de aplicación. Para llamadas delegadas, incorpora la aplicación en el ámbito delegado. Consulta Ámbitos y consentimiento. Para S2S, adquiere el token con <resource>/.default.
403 Forbidden, la identidad del agente no coincide {agentId} en la URL ≠ appid o azp del token, o un span lleva un gen_ai.agent.id que no coincide con el agente autenticado. La ruta agentId debe ser el appId de la aplicación que llama. En el caso de las identidades derivadas del plano técnico, es el appId de identidad del agente, no el appId del plano técnico. Asegúrese de que cada gen_ai.agent.id span coincida.
200 OK pero partialSuccess.rejectedSpans == totalSpans Todos los segmentos estaban mal en gen_ai.operation.name. Use una de las propiedades invoke_agent, execute_tool, chat, output_messages. Es chat, no inference.
200 OK con results mostrando rejected y motivo tenant_not_licensed El arrendatario no cumple actualmente los requisitos para la observabilidad. Confirma que al menos un usuario del tenant tiene asignada una licencia Microsoft 365 E7 o Microsoft Agent 365 (que el SKU esté presente no es suficiente), y luego usa la comprobación opcional de elegibilidad del inquilino.
Los tramos aparecen en CloudAppEvents, pero no aparece la ejecución en las vistas de actividad del agente de Defender y en el Centro de administración de Microsoft 365 La secuencia no tiene ningún invoke_agent tramo. Ambas superficies desactivan invoke_agentla tecla . Genere exactamente un span invoke_agent en la raíz de cada ejecución; haga que chat, execute_tool y output_messages sean elementos hijo de este a través de parentSpanId.
El árbol de ejecución está dañado o los segmentos de herramienta han quedado huérfanos Faltan parentSpanId o difieren traceId en intervalos secundarios. Consulte Jerarquía de intervalos y agrupación de ejecución. Cada span no raíz establece parentSpanId y comparte el traceId de la ejecución.
Los segmentos de herramientas muestran ChannelName o ConversationId vacíos en consultas El canal o la conversación no están configurados en la herramienta span, y el padre invoke_agent no estaba en la misma solicitud OTLP. Establezca microsoft.channel.name y gen_ai.conversation.id en cada intervalo.
413 Payload Too Large Cuerpo de la solicitud > de 1 MB. Divida los intervalos entre varias solicitudes.
429 Too Many Requests Se alcanzó el límite de velocidad. Honor Retry-After: 1 y regreso con vibración.
El agente aparece no identificado en los paneles gen_ai.agent.id está vacío o no es un GUID. Use el appId de Entra del agente. Si el agente no tiene registro de Entra, vea Selección de valores.

Comprobación previa de la elegibilidad del arrendatario

Las integraciones S2S de terceros incorporadas pueden usar el endpoint opcional de elegibilidad para inquilinos antes de habilitar una integración o enviar telemetría. Si tu integración utiliza este endpoint, las siguientes indicaciones pueden ayudarte a interpretar sus respuestas.

Síntoma Causa más probable Corregir
Devoluciones de elegibilidad 200 OK con enabled: false El inquilino actualmente no cumple los requisitos de elegibilidad. No envíes telemetría. Verifica que el inquilino cumpla los requisitos previos y vuelve a comprobar cuando cambie su estado.
Declaraciones de elegibilidad 403 Forbidden Al token le falta Agent365.Observability.OtelWrite, o el token tid no coincide con {tenantId} en la URL. Corregir la asignación de rol de la app, el consentimiento del inquilino o la descoordinación del inquilino.
Declaraciones de elegibilidad 429 Too Many Requests El llamante superó el límite de elegibilidad solicitado. Honra el valor de Retry-After la respuesta e intenta de nuevo con retroceso y nerviosismo.
La comprobación de elegibilidad devuelve una respuesta sin cuerpo 503 Service Unavailable No se pudo determinar la elegibilidad. Respeta Retry-After: 30 y vuelve a intentarlo. No interpretes el cuerpo que falta como enabled: false.

Pasos siguientes

  • Last updated on