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. È orientato al percorso OTel diretto - se stai usando l'SDK obsoleto Agent 365 Observability o la Microsoft OpenTelemetry Distro, consulta quelle guide invece. 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 scarto 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. Controllare results. Per ogni intervallo, verificare che la destinazione applicabile abbia lo stato sent. Uno stato di rejected o not_routed include una ragione.
  3. partialSuccessAnalizzare . 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 intervalli vengono visualizzati, ma l'albero di esecuzione è danneggiato oppure alcuni figli sono orfani → manca parentSpanId, traceId è diverso oppure gen_ai.conversation.id non è impostato in ogni intervallo. 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 route 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 blueprint, si tratta dell'appId dell'identità dell'agente, non dell'appId del blueprint. Assicurati che gen_ai.agent.id corrisponda in ogni span.
200 OK ma partialSuccess.rejectedSpans == totalSpans Tutti gli span presentavano un problema con gen_ai.operation.name. 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 dal interfaccia di amministrazione di Microsoft 365 L'esecuzione non ha un invoke_agent intervallo. Entrambe le superfici dipendono da invoke_agent. Emetti esattamente uno span invoke_agent a livello radice di ogni esecuzione; rendi chat, execute_tool e output_messages figli di invoke_agent tramite parentSpanId.
L'albero delle esecuzioni è danneggiato oppure gli intervalli dello strumento appaiono orfani Mancante parentSpanId o diverso traceId per gli intervalli figlio. Vedi Gerarchia degli span e raggruppamento delle esecuzioni. Ogni span non-root imposta parentSpanId e condivide il traceId del run.
Gli intervalli dello strumento mostrano vuoti ChannelName o ConversationId 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. Onora Retry-After: 1 e torna indietro con instabilità.
Agente appare non identificato nelle dashboard gen_ai.agent.id è vuoto o non è un GUID. Usare 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.
Dichiarazioni 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.
Dichiarazioni 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 senza corpo 503 Service Unavailable Non si poteva determinare l'idoneità. Rispetta Retry-After: 30 e riprova. Non considerare il corpo mancante come enabled: false.

Passaggi successivi

  • Last updated on