Resolver problemas de observabilidade OTel direta

Use este guia para verificar a ingestão de telemetria e diagnosticar problemas com a telemetria do agente enviada diretamente ao Agent 365 através do OTLP. Este guia é destinado ao caminho OTel direto - caso utilize o SDK de Agent 365 ou o Microsoft OpenTelemetry Distro, consulte os guias correspondentes. Para limites ao nível da transmissão, códigos de erro e condições de remoção silenciosa, consulte Limites e condições de remoção.

Verificar a ingestão

Um 200 OK não é prova de ingestão. Algumas condições de remoção devolvem 200 com partialSuccess: null e os seus dados simplesmente não aparecem (ver Limites e condições de remoção). Verifique sempre as suas primeiras execuções:

  1. Verifique o estado HTTP. 200 → continuar. 4xx → ver Armadilhas comuns.
  2. Analise partialSuccess. null significa que a API aceitou tudo. Qualquer outro resultado significa que pelo menos alguns spans foram removidos pelo filtro por span.
  3. Aguarde aproximadamente 5 minutos, e, em seguida, execute a consulta de procura avançada do Defender abaixo.
  4. Nenhuma linha? Use a árvore de decisão em Sem dados no Defender.

Consulta de procura avançada do Defender

A procura canónica (com junção baseada na identidade do agente enviada):

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 a lista completa de superfícies (vistas de atividade do agente Defender, centro de administração do Microsoft 365, Microsoft Purview) e os requisitos de cada uma, veja Onde aparecem os seus dados.

Sem dados no Defender

  • partialSuccess.rejectedSpans == totalSpans → todos os seus spans tinham um gen_ai.operation.name incorreto. Correção: utilize um de invoke_agent, execute_tool, chat, output_messages (é chat, não inference).
  • 200 com partialSuccess: null mas sem a linha do Defender, após 5 minutos → nenhum utilizador no inquilino do cliente tem uma licença do Microsoft 365 E7 ou Microsoft Agent 365 atribuída (Limites e condições de remoção, condição de remoção 2). Correção: confirme que pelo menos um utilizador no inquilino tem a licença atribuída (não apenas presente no inquilino); caso contrário, contacte a equipa de inclusão do Agent 365.
  • Os spans aparecem, mas a árvore de execução está interrompida / alguns elementos subordinados estão órfãos → falta parentSpanId, traceId diferente, ou gen_ai.conversation.id não definido em todos os spans. Correção: rever Hierarquia de spans e agrupamento de execuções.

Armadilhas comuns

Sintoma Causa mais provável Correção
401 Unauthorized aud incorreto no token. Utilize 9b975845-388f-4429-889e-eab1ef63949c (ou api://9b975845-...).
403 Forbidden, função/âmbito em falta O token não contém Agent365.Observability.OtelWrite. Integre a sua aplicação Microsoft Entra na função (S2S) ou âmbito (delegado) conforme os Âmbitos e consentimento. Para S2S, o token deve ser adquirido com <resource>/.default.
403 Forbidden, incompatibilidade de identidade do agente {agentId} no URL ≠ appid / azp do token, ou um span contém um gen_ai.agent.id que não corresponde ao agente autenticado. A rota agentId deve ser o appId da aplicação de chamada. Para identidades derivadas do blueprint, trata-se do appId da identidade do agente, não do appId do blueprint. Certifique-se de que o gen_ai.agent.id de cada span corresponde.
200 OK mas partialSuccess.rejectedSpans == totalSpans Todos os spans tinham um gen_ai.operation.name incorreto. Utilize um dos invoke_agent, execute_tool, chat, output_messages. É chat, não inference.
200 OK com partialSuccess: null mas nenhum dado aparece no Defender Nenhum utilizador no inquilino do cliente tem uma licença do Microsoft 365 E7 ou Microsoft Agent 365 atribuída (Limites e condições de remoção). Confirme que pelo menos um utilizador no inquilino tem uma licença do Microsoft 365 E7 ou Microsoft Agent 365 atribuída (a presença do SKU não é suficiente). Verifique com o KQL em Verificação da ingestão; se nada for registado após 5 minutos, contacte a equipa do Agent 365.
Spans aparecem em CloudAppEvents, mas a execução está em falta das vistas de atividade de agentes do Defender e do centro de administração do Microsoft 365 A execução não tem span invoke_agent. Ambas as superfícies desligam invoke_agent. Emite exatamente um span invoke_agent na raiz de cada execução; torna chat / execute_tool / output_messages elementos subordinados através de parentSpanId.
A árvore de execução está interrompida/os spans das ferramentas aparecem órfãos Falta o parentSpanId ou os spans de elemento subordinado têm um traceId diferente. Consulte Hierarquia de spans e agrupamento de execuções. Cada span não raiz define parentSpanId e partilha o traceId da execução.
Spans de ferramenta mostram ChannelName / ConversationId vazios nas consultas Canal/conversa não definido no span de ferramenta, e o elemento principal invoke_agent não estava no mesmo pedido OTLP. Defina microsoft.channel.name e gen_ai.conversation.id em cada span.
413 Payload Too Large Corpo do pedido > 1 MB. Divida os spans entre vários pedidos.
429 Too Many Requests Limite de taxa excedido. Respeite Retry-After: 1 e recue com jitter.
O agente aparece como não identificado nos dashboards gen_ai.agent.id está vazio ou não é um GUID. Utilize o appId do Entra do agente. Se o agente não tiver registo no Entra, consulte Selecionar valores.

Passos seguintes

  • Last updated on