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 anulación devuelven 200 aunque la results de la respuesta muestra que los elementos fueron rechazados. Compruebe siempre sus 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. Analice partialSuccess 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

La 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 → todos sus tramos 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.
  • Los tramos aparecen, pero el árbol de ejecución está roto o algunos secundarios están huérfanos → falta parentSpanId, traceId es diferente o gen_ai.conversation.id no está establecido en cada tramo. Solución: revise Jerarquía de intervalos y agrupación de ejecució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 planos técnicos, confirme que el registro de Agent 365 se ha completado. Para volver a intentarlo, consulta Reintentar un registro con errores. Para otras identidades S2S, incorpore su aplicación de Microsoft Entra en el rol de aplicación. Para llamadas delegadas, incorpore 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. Para las identidades derivadas de plantillas, este es el appId de la identidad del agente, no el appId de la plantilla. Asegúrese de que cada gen_ai.agent.id span coincida.
200 OK pero partialSuccess.rejectedSpans == totalSpans Todos los tramos tenían un gen_ai.operation.name incorrecto. 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 ejecución no tiene ningún tramo invoke_agent. Ambas superficies desactivan la clave invoke_agent. 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á roto o los tramos de herramientas aparecen huérfanos Faltan parentSpanId o difieren traceId en tramos secundarios. Consulte Jerarquía de intervalos y agrupación de ejecución. Cada tramo no raíz establece parentSpanId y comparte el traceId de la ejecución.
Los tramos de herramientas muestran ChannelName o ConversationId en las consultas Canal o conversación no establecido en el tramo de herramientas y el elemento primario invoke_agent no estaba en la misma solicitud de OTLP. Establezca microsoft.channel.name y gen_ai.conversation.id en cada intervalo.
413 Payload Too Large Cuerpo de la solicitud > 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.
Elegibilidad devuelve 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 aplicación, el consentimiento del inquilino o la descoordinación del inquilino.
Elegibilidad devuelve 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 elegibilidad devuelve una respuesta sin cuerpo 503 Service Unavailable No se pudo determinar la elegibilidad. Respeta Retry-After: 30 y vuelve a intentarlo. No interprete el cuerpo que falta como enabled: false.

Pasos siguientes

  • Se actualizó por última vez el