Solucionar problemas de observabilidade direta do OTel

Use este guia para verificar a ingestão de telemetria e diagnosticar problemas com a telemetria enviada pelo agente ao Agent 365 diretamente via 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 no nível do protocolo, códigos de erro e condições de descarte silencioso, consulte Limites e condições de descarte.

Verificando a 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 (consulte Limites e condições de descarte). Sempre verifique suas primeiras execuções:

  1. Verifique o status HTTP. 200 → prosseguir. 4xx → ver 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. Aguarde ~5 minutos, depois execute a consulta de busca avançada do Defender abaixo.
  4. Nenhuma linha? Use a árvore de decisão em 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.

Nenhum dado no Defender

  • partialSuccess.rejectedSpans == totalSpans → todos os seus intervalos tinham um gen_ai.operation.name inválido. Correção: use um de 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 que pelo menos um usuário no locatário tem a licença atribuída (não apenas presente no locatário); caso contrário, contate 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 Corrigir
401 Unauthorized Erro aud no token. Usar 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, incompatibilidade de identidade do agente {agentId} na 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 a appId do aplicativo de chamada. 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 de 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 se pelo menos um usuário no locatário tem a licença Microsoft 365 E7 ou Microsoft Agent 365 atribuída (não basta que a SKU esteja presente). 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. Definir microsoft.channel.name e gen_ai.conversation.id em cada span.
413 Payload Too Large Corpo da solicitação > 1 MB. Divida os intervalos entre 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 nenhum registro do Entra, consulte Escolher valores.

Próximas Etapas 

  • Last updated on