Solucionar problemas de observabilidade direta do OTel

Use este guia para verificar a ingestão de telemetria e diagnosticar problemas com a telemetria do agente enviada diretamente ao Agent 365 sobre OTLP. Isso se aplica ao caminho direto do OTel - se você estiver usando o SDK do Agent 365 ou o Microsoft OpenTelemetry Distro, consulte esses guias. Para limites em nível de transmissão, códigos de erro e condições de descarte silencioso, veja Limites e condições do descarte.

Verificação da ingestão

Um código 200 OK não é prova de ingestão. Algumas condições de descarte retornam 200 com partialSuccess: null e seus dados simplesmente não aparecem (veja Limites e condições de descarte). Sempre verifique suas primeiras execuções:

  1. Verificar o status de HTTP. 200 → continuar. 4xx → veja Armadilhas comuns.
  2. Analisar partialSuccess. null significa que a API aceitou tudo Qualquer outra coisa significa que pelo menos alguns intervalos foram descartados no filtro por intervalo.
  3. Espere ~5 minutos, então execute a consulta avançada de busca do Defender abaixo.
  4. Nenhuma linha? Use a árvore de decisão na seção Sem dados no Defender.

Consulta de pesquisa avançada do Defender

A pesquisa canônica (ingressando na identidade do agente que você enviou):

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 obter a lista completa de superfícies (exibições de atividade do agente no Defender, centro de administração do Microsoft 365 e Microsoft Purview) e o que é necessário para cada um, consulte Onde seus dados aparecem.

Sem dados no Defender

  • partialSuccess.rejectedSpans == totalSpans → todos os seus intervalos tinham um gen_ai.operation.name inválido. Correção: utilize um dos invoke_agent, execute_tool, chat, output_messages (é chat, não inference).
  • 200 com partialSuccess: null mas nenhuma linha do Defender após 5 min → nenhum usuário no locatário do cliente tem uma licença do Microsoft 365 E7 ou do Microsoft Agent 365 atribuída (Limites e condições de descarte, condição de descarte 2). Correção: confirme se pelo menos um usuário do locatário tem a licença atribuída (não apenas presente no locatário); caso contrário, entre em contato com a equipe de integração do Agent 365.
  • Os intervalos aparecem, mas a árvore de execução está corrompida/alguns filhos órfãos → ausentes parentSpanId, diferentes traceIdou gen_ai.conversation.id não definidas em cada intervalo. Correção: examine a hierarquia de intervalo e o agrupamento de execução.

Armadilhas comuns

Sintoma Causa mais provável Correção
401 Unauthorized Erro aud no token. Use 9b975845-388f-4429-889e-eab1ef63949c (ou api://9b975845-...).
403 Forbidden, função/escopo ausente O token não contém Agent365.Observability.OtelWrite. Integre seu aplicativo Microsoft Entra à função (S2S) ou ao escopo (delegado), conforme Escopos e consentimento. Para S2S, o token deve ser adquirido com <resource>/.default.
403 Forbidden, não correspondência de identidade do agente {agentId} na URL ≠ appid / azp do token, ou um intervalo contém um gen_ai.agent.id que não corresponde ao agente autenticado. A rota agentId deve ser o appId do aplicativo chamador. Para identidades derivadas de blueprint, trata-se do appId da identidade do agente, não do appId do blueprint. Verifique se o gen_ai.agent.id de cada intervalo é correspondente.
200 OK mas partialSuccess.rejectedSpans == totalSpans Todos os intervalos tinham um gen_ai.operation.name inválido. Use 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 usuário no locatário do cliente tem uma licença do Microsoft 365 E7 ou do Microsoft Agent 365 atribuída (Limites e condições de descarte). Confirme que pelo menos um usuário no locatário tem uma licença do Microsoft 365 E7 ou do Microsoft Agent 365 atribuída (a presença do SKU não é suficiente). Verifique usando a consulta KQL em Verificando a ingestão; se nenhum dado for recebido após 5 min, entre em contato com a equipe do Agent 365.
Intervalos aparecem em CloudAppEvents, mas a execução não aparece nas exibições de atividade do agente no Defender nem no centro de administração do Microsoft 365 Não há um intervalo invoke_agent na execução. Ambas as superfícies usam invoke_agent. Emita exatamente um intervalo invoke_agent na raiz de cada execução; defina chat / execute_tool / output_messages como filhos dele por meio de parentSpanId.
A árvore de execução está corrompida/ os intervalos de ferramentas parecem órfãos parentSpanId ausente ou traceId diferente nos intervalos filho. Consulte Hierarquia de intervalo e agrupamento de execução. Cada span não raiz define parentSpanId e compartilha o traceId da execução.
Intervalos de ferramentas são exibidos vazios ChannelName / ConversationId em consultas Canal/conversa não definido no intervalo de ferramentas e o invoke_agent pai não estava na mesma solicitação OTLP. Defina microsoft.channel.name e gen_ai.conversation.id em cada intervalo.
413 Payload Too Large Corpo da solicitação > 1 MB. Divida os intervalos em várias solicitações.
429 Too Many Requests Limite de taxa atingido. Respeite o valor Retry-After: 1 e use uma estratégia de backoff com jitter.
O agente aparece não identificado nos painéis gen_ai.agent.id está vazio ou não é um GUID. Use o appId do Entra do agente. Se o agente não tiver registro no Entra, consulte Selecionando valores.

Próximas etapas

  • Last updated on