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. Questa guida è dedicata al percorso OTel diretto: se utilizzi l'SDK Agent 365 Osservabilità deprecato o Microsoft OpenTelemetry Distro, fai riferimento a quelle 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.

Verificare l'acquisizione

Un 200 OK non è prova di ingestione. Alcune condizioni di eliminazione restituiscono 200 anche se i tag results della risposta mostrano che gli span sono stati rifiutati. Verificare sempre le prime esecuzioni:

  1. Controllare lo stato HTTP. 200 → continua. 4xx → vedere Problemi comuni.
  2. Esamina i results. Per ogni intervallo, verificare che la destinazione applicabile abbia lo stato sent. Uno stato di rejected o not_routed include una ragione.
  3. Esegui il parsing partialSuccess. Questo campo indica alcuni errori di filtraggio per span, ma un valore di 0 non garantisce che lo span sia stato instradato.
  4. Aspetta ~5 minuti, poi esegui la query di ricerca avanzata di Defender nella sezione successiva.
  5. 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 dell'attività degli agenti Defender, interfaccia di amministrazione di Microsoft 365, Microsoft Purview) e cosa serve ciascuna, vedi Dove compaiono i dati di osservabilità dell'Agent 365.

Nessun dato in Defender

  • partialSuccess.rejectedSpans == totalSpans → tutti i tuoi span presentavano un gen_ai.operation.name errato. Correzione: usa uno di invoke_agent, execute_tool, chat, output_messages (è chat, non inference).
  • results Dimostra rejected con motivo tenant_not_licensed → l'inquilino non è attualmente idoneo. Correzione: verifica che almeno un utente nel tenant disponga di una licenza Microsoft 365 E7 o Microsoft Agent 365 assegnata, quindi verifica l'idoneità del tenant.
  • Gli span vengono visualizzati, ma l'albero di esecuzione è danneggiato oppure 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 o registrazione mancanti Sulla rotta S2S, l'istanza dell'agente non è registrata con Agent 365 e il token non ha il ruolo di app Agent365.Observability.OtelWrite. Sul percorso delegato, il token non porta l'ambito delegato. Per un'istanza di agente derivata dal blueprint, conferma che la registrazione dell'Agente 365 sia completata. Per riprovare, vedi Riprovare una registrazione non riuscita. Per altre identità S2S, abilita la tua app Microsoft Entra per il ruolo app. Per le chiamate delegate, configura l'app nell'ambito delegato. Vedi Ambiti e consenso. Per S2S, acquisire il token con <resource>/.default.
403 Forbidden, mancata corrispondenza dell'identità dell'agente {agentId} nell'URL ≠ appid o azp del token, oppure uno span presenta 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 progetto, si tratta dell'appId dell'identità dell'agente, non dell'appId del progetto. 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 results che mostra rejected e il motivo tenant_not_licensed L'inquilino attualmente non è idoneo all'osservabilità. Conferma che almeno un utente nel tenant abbia assegnata una licenza Microsoft 365 E7 o Microsoft Agent 365 (la presenza dello SKU non è sufficiente), quindi usa il controllo facoltativo dell'idoneità del tenant.
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 e output_messages figli tramite parentSpanId.
L'albero di esecuzione è danneggiato oppure 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 o ConversationId vuoto nelle query Il canale o la conversazione non sono impostati sull'intervallo dello strumento, e il genitore 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.

Requisiti di idoneità per l'inquilino preflight

Le integrazioni S2S di terze parti integrate possono utilizzare l'endpoint opzionale di idoneità al tenant prima di abilitare un'integrazione o inviare telemetria. Se la tua integrazione utilizza questo endpoint, le seguenti indicazioni possono aiutarti a interpretarne le risposte.

Sintomo Causa più probabile Correzione
Resi di idoneità 200 OK con enabled: false L'inquilino attualmente non soddisfa i requisiti di idoneità. Non inviare telemetria. Verifica che l'inquilino soddisfi i prerequisiti e ricontrolla dopo che il suo stato cambia.
Resi di idoneità 403 Forbidden Nel token manca Agent365.Observability.OtelWrite, oppure il token tid non corrisponde a {tenantId} nell'URL. Correggi l'assegnazione del ruolo dell'app, il consenso del tenant o la mancata corrispondenza del tenant.
Resi di idoneità 429 Too Many Requests Il chiamante ha superato il limite di idoneità richiesto. Rispetta il valore Retry-After della risposta e riprova con backoff e jitter.
La verifica di idoneità restituisce una risposta 503 Service Unavailable senza corpo Non si poteva determinare l'idoneità. Rispetta Retry-After: 30 e riprova. Non considerare il corpo mancante come enabled: false.

Passaggi successivi

  • Ultimo aggiornamento: