Risolvere i problemi di osservabilità diretta di OTel

Usare questa guida per verificare l'inserimento dei dati di telemetria e diagnosticare i problemi relativi alla telemetria dell'agente inviati direttamente all'agente 365 tramite OTLP. Si applica solo al direct OTel path: se utilizzi l'Agent 365 SDK o Microsoft OpenTelemetry Distro, consulta invece le relative guide. Per i limiti a livello di collegamento, i codici di errore e le condizioni di rilascio invisibile all'utente, vedere Limiti e condizioni di rilascio.

Verifica dell'acquisizione

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

  1. Controllare lo stato HTTP. 200 → continua. 4xx → vedere Problemi comuni.
  2. Esegui il parsing partialSuccess. null significa che l'API ha accettato tutto. Qualsiasi altro valore significa che almeno alcuni segmenti sono stati scartati dal filtro applicato a ciascun segmento.
  3. Attendi ~5 minuti, quindi esegui la query di ricerca avanzata di Defender riportata di seguito.
  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 interfacce (visualizzazioni dell'attività dell'agente di Defender, interfaccia di amministrazione di Microsoft 365, Microsoft Purview) e dei requisiti di ciascuna, vedi Dove vengono visualizzati i dati.

Nessun dato in Defender

  • partialSuccess.rejectedSpans == totalSpans → tutti i tuoi span presentavano un gen_ai.operation.name errato. Correzione: usare uno di 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: verificare che almeno un utente nel tenant abbia la licenza assegnata (non solo presente nel tenant); in caso contrario, contattare il team di onboarding di 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. Correggere: rivedere gerarchia degli span e raggruppamento dei run.

Insidie comuni

Sintomo Causa più probabile Correzione
401 Unauthorized Errore aud nel token. Usare 9b975845-388f-4429-889e-eab1ef63949c (o 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 riporta un gen_ai.agent.id che non corrisponde all'agente autenticato. La route agentId 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. Usare uno di invoke_agent, execute_tool, chat, output_messages. È chat, non inference.
200 OK con partialSuccess: null ma non viene visualizzato 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 rimozione). Verificare che almeno un utente nel tenant abbia una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata (lo SKU presente non è sufficiente). 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. Impostare microsoft.channel.name e gen_ai.conversation.id su ogni intervallo.
413 Payload Too Large Corpo della richiesta > 1 MB. Suddividere l'intervallo tra più richieste.
429 Too Many Requests Limite di velocità raggiunto. Rispetta Retry-After: 1 e disattivalo con jitter.
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 dispone di una registrazione in Entra, vedi Scelta dei valori.

Passaggi successivi

  • Last updated on