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. Ele é direcionado para o caminho OTel direto – se você estiver usando o obsoleto Agent 365 Observability SDK ou a distro Microsoft OpenTelemetry, veja 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.

Verificar a ingestão

Um 200 OK não é prova de ingestão. Algumas condições de descarte retornam 200, embora o results da resposta mostre que os spans foram rejeitados. Sempre verifique suas primeiras execuções:

  1. Verifique o status HTTP. 200 → prosseguir. 4xx → ver armadilhas comuns.
  2. Inspecionar results. Para cada intervalo, confirme que o destino aplicável esteja com o status de sent. Um status de rejected ou not_routed inclui um motivo.
  3. partialSuccessAnalisar . Este campo relata algumas falhas de filtragem por intervalo, mas um valor de 0 não garante que o intervalo tenha sido roteado.
  4. Espere ~5 minutos, então execute a consulta de caça avançada do Defender na seção seguinte.
  5. 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 ver a lista completa de interfaces (exibições de atividade do agente no Defender, centro de administração do Microsoft 365, Microsoft Purview) e o que cada uma requer, consulte Onde os dados de observabilidade do Agent 365 aparecem.

Nenhum dado no Defender

  • partialSuccess.rejectedSpans == totalSpans → todos os seus spans tinham um gen_ai.operation.name ruim. Correção: use um dos invoke_agent, execute_tool, chat, output_messages (é chat, não inference).
  • results mostra rejected com o motivo tenant_not_licensed → o locatário não está elegível no momento. Correção: confirme que pelo menos um usuário do tenant tem uma licença Microsoft 365 E7 ou Microsoft Agent 365 atribuída, e então verifique a elegibilidade do locatário.
  • Os spans aparecem, mas a árvore de execução está quebrada ou alguns elementos filhos ficam órfãos → falta parentSpanId, traceId é diferente ou gen_ai.conversation.id não está definido em todos os spans. 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 faltando, escopo ou cadastro Na rota S2S, a instância do agente não está registrada no Agent 365 e o token não carrega a Agent365.Observability.OtelWrite função de app. Na rota delegada, o token não carrega o escopo delegado. Para uma instância de agente derivada do blueprint, confirme que o registro do Agente 365 foi concluído. Para tentar novamente, veja Tentar novamente um cadastro com falha. Para outras identidades S2S, cadastre seu aplicativo Microsoft Entra na função de aplicativo. Para chamadas delegadas, integre o aplicativo ao escopo delegado. Veja Escopos de permissão e consentimento. Para S2S, adquira o token com <resource>/.default.
403 Forbidden, incompatibilidade de identidade do agente {agentId} na URL ≠ appid ou 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 span corresponde.
200 OK mas partialSuccess.rejectedSpans == totalSpans Todos os spans 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 results mostrando rejected e motivo tenant_not_licensed O locatário não está elegível para observabilidade no momento. Confirme se pelo menos um usuário do tenant tem uma licença Microsoft 365 E7 ou Microsoft Agent 365 atribuída (a presença do SKU não é suficiente), então use a verificação opcional de elegibilidade do locatário.
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 A execução não tem invoke_agent extensão. Ambas as superfícies são desligadas invoke_agent. Emita exatamente um span invoke_agent na raiz de cada run; torne chat, execute_tool e output_messages filhos dele por meio de parentSpanId.
A árvore de execução está corrompida ou os spans da ferramenta aparecem como órfãos parentSpanId ausente ou traceId diferente nos spans filho. Consulte hierarquia span e agrupamento de execução. Cada span não raiz define parentSpanId e compartilha o traceId da execução.
Os spans da ferramenta aparecem vazios como ChannelName ou ConversationId nas consultas Canal ou conversa não foram definidos no span da ferramenta, e o pai invoke_agent não estava na mesma requisiçã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. Honra Retry-After: 1 e se afasta com tremulação.
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.

Verificação preliminar de elegibilidade do locatário

Integrações S2S de terceiros incorporadas podem usar o endpoint opcional de elegibilidade para inquilinos antes de habilitar uma integração ou enviar telemetria. Se sua integração usar esse endpoint, as orientações a seguir podem ajudar você a interpretar suas respostas.

Sintoma Causa mais provável Corrigir
Retornos de elegibilidade 200 OK com enabled: false O inquilino atualmente não atende aos requisitos de elegibilidade. Não envie telemetria. Verifique se o inquilino atende aos pré-requisitos e verifique novamente após suas mudanças de status.
Retornos de elegibilidade 403 Forbidden O token não tem Agent365.Observability.OtelWrite, ou o token tid não corresponde {tenantId} na URL. Corrija a atribuição de função do app, consentimento do inquilino ou incompatibilidade entre inquilino.
Retornos de elegibilidade 429 Too Many Requests O interlocutor ultrapassou o limite de elegibilidade exigido. Respeite o valor da Retry-After resposta e tente novamente com recuo e tremor.
A verificação de elegibilidade retorna uma resposta sem corpo 503 Service Unavailable A elegibilidade não pôde ser determinada. Respeite Retry-After: 30 e tente novamente. Não interprete o corpo ausente como enabled: false.

Próximas Etapas 

  • Última atualização em