Risolvere i problemi di osservabilità OTel diretta

Usa questa guida per verificare l'inserimento della telemetria e diagnosticare problemi con la telemetria dell'agente inviata direttamente ad Agent 365 tramite OTLP. Questa guida è dedicata al percorso OTel diretto: se utilizzi l'SDK Agent 365 o Microsoft OpenTelemetry Distro, fai riferimento a quelle guide. Per i limiti a livello di connessione, i codici errore e le condizioni di eliminazione silenziosa, vedi Limiti e condizioni di eliminazione.

Verificare l'inserimento

Un 200 OK non è la prova dell'avvenuta acquisizione. Alcune condizioni di eliminazione restituiscono 200 con partialSuccess: null e i tuoi dati semplicemente non appaiono (vedi Limiti e condizioni di eliminazione). Verificare sempre le prime esecuzioni:

  1. Controlla lo stato HTTP. 200 → continua. 4xx → vedi Problemi comuni.
  2. Esegui il parsing partialSuccess. null significa che l'API ha accettato tutto. Qualsiasi altro valore indica che almeno alcuni span sono stati scartati dal filtro per span.
  3. Attendi circa 5 minuti, poi esegui la query di ricerca avanzata di Defender qui sotto.
  4. Nessuna riga? Usi l'albero decisionale in Nessun dato in Defender.

Query di ricerca avanzata di Defender

Ricerca canonica (aggiunta all'identità dell'agente inviata):

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

Per l'elenco completo delle superfici (viste di attività dell'agente Defender, interfaccia di amministrazione di Microsoft 365, Microsoft Purview) e cosa serve ciascuna, vedi Dove compaiono i tuoi dati.

Nessun dato in Defender

  • partialSuccess.rejectedSpans == totalSpans → tutti i tuoi span presentavano un gen_ai.operation.name errato. Correzione: usa uno tra invoke_agent, execute_tool, chat, output_messages (è chat, non inference).
  • 200 con partialSuccess: null ma nessuna riga di Defender dopo 5 min → nessun utente nel tenant del cliente ha una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata (Limiti e condizioni di esclusione, condizione di esclusione 2). Correzione: conferma che almeno un utente nel tenant abbia la licenza assegnata (non solo presente nel tenant); altrimenti contatta il team di onboarding dell'Agent 365.
  • Gli span vengono visualizzati, ma l'albero di esecuzione è danneggiato/alcuni nodi figli sono orfani → parentSpanId mancante, traceId è diverso oppure gen_ai.conversation.id non è impostato su ogni span. Correzione: rivedi Gerarchia degli span e raggruppamento delle esecuzioni.

Errori comuni

Sintomo Causa più probabile Correzione
401 Unauthorized aud errato nel token. Usa 9b975845-388f-4429-889e-eab1ef63949c (oppure api://9b975845-...).
403 Forbidden, ruolo/ambito mancante Il token non contiene Agent365.Observability.OtelWrite. Integra l'app Microsoft Entra per il ruolo (S2S) o l'ambito (delegato) secondo Ambiti e consenso. Per S2S, il token deve essere acquisito con <resource>/.default.
403 Forbidden, mancata corrispondenza dell'identità dell'agente {agentId} nell'URL ≠ appid / azp del token oppure uno span contiene un gen_ai.agent.id che non corrisponde all'agente autenticato. Il agentId del percorso deve essere l'appId dell'app chiamante. Per le identità derivate da blueprint, si tratta dell'appId dell'identità dell'agente, non dell'appId del blueprint. Assicurati che gen_ai.agent.id di ogni span corrisponda.
200 OK ma partialSuccess.rejectedSpans == totalSpans Tutti gli tuoi span presentavano un gen_ai.operation.name errato. Utilizza uno tra invoke_agent, execute_tool, chat, output_messages. È chat, non inference.
200 OK con partialSuccess: null ma non appare alcun dato in Defender Nessun utente nel tenant del cliente ha una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata (Limiti e condizioni di eliminazione). Verifica che almeno un utente nel tenant abbia una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata (la presenza dello SKU non basta). Verifica tramite la query KQL in Verifica dell'acquisizione; se non arriva nulla entro 5 minuti, contatta il team Agent 365.
Gli intervalli vengono visualizzati in CloudAppEvents, ma l'esecuzione non è presente nelle visualizzazioni delle attività dell'agente Defender e dall'interfaccia di amministrazione di Microsoft 365 L'esecuzione non ha un intervallo invoke_agent. Entrambe le superfici dipendono da invoke_agent. Emettere esattamente uno span invoke_agent alla radice di ogni esecuzione; rendi chat / execute_tool / output_messages figli tramite parentSpanId.
L'albero di esecuzione è danneggiato/i segmenti dello strumento appaiono scollegati parentSpanId mancante o diverso traceId per gli intervalli figlio. Vedi Gerarchia degli span e raggruppamento delle esecuzioni. Ogni span non radice imposta parentSpanId e condivide traceId dell'esecuzione.
Gli intervalli degli strumenti mostrano ChannelName / ConversationId vuoto nelle query Canale/conversazione non impostata sull'intervallo di strumenti e l'elemento padre invoke_agent non era nella stessa richiesta OTLP. Imposta microsoft.channel.name e gen_ai.conversation.id su ogni span.
413 Payload Too Large Corpo della richiesta > 1 MB. Suddividere l'intervallo tra più richieste.
429 Too Many Requests Limite di flusso in entrata raggiunto. Rispetta Retry-After: 1 e disattivalo con jitter.
L'agente appare non identificato nelle dashboard gen_ai.agent.id è vuoto o non è un GUID Usa l'appId di Entra dell'agente. Se l'agente non ha una registrazione Entra, vedi Selezione dei valori.

Passaggi successivi

  • Last updated on