Řešení problémů s přímou pozorovatelností OTel

Použijte tohoto průvodce k ověření příjmu telemetrie a diagnostice problémů s telemetrií agenta odesílanou přímo do služby Agent 365 přes OTLP. Je zaměřený na přímou cestu OTel – pokud používáte Agent 365 SDK nebo Microsoft OpenTelemetry Distro, viz příslušné návody. Informace o limitech na úrovni přenosového protokolu, chybových kódech a podmínkách tichého zahazování zpráv najdete v části Limity a podmínky zahazování.

Ověření ingesce

200 OK není důkazem ingesce. Některé podmínky zahazování vrátí 200 spolu s partialSuccess: null a data se jednoduše nezobrazí (viz Limity a podmínky zahazování). Vždy ověřujte první spuštění:

  1. Zkontrolujte stav HTTP. 200 → pokračování. 4xx → viz Běžné nástrahy.
  2. Parsování partialSuccess. null znamená, že rozhraní API přijalo vše. Jakákoli jiná hodnota znamená, že alespoň některé spany byly odfiltrovány filtrem na úrovni jednotlivých spanů.
  3. Počkejte přibližně 5 minut, poté spusťte níže uvedený dotaz na pokročilé hledání v aplikaci Defender.
  4. Žádný řádek? Použijte rozhodovací strom v části V aplikaci Defender nejsou žádná data.

Pokročilý vyhledávací dotaz v aplikaci Defender

Standardní dotaz (spojení podle identity agenta, kterou jste zadali):

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

Pro kompletní seznam vrstev (zobrazení aktivit agenta v aplikaci Defender, centrum pro správu Microsoft 365, Microsoft Purview) a požadavků jednotlivých rozhraní viz Kde se objevují vaše data.

V aplikaci Defender nejsou žádná data

  • partialSuccess.rejectedSpans == totalSpans → všechny vaše spany měly nesprávný gen_ai.operation.name. Oprava: Použijte jednu z možností invoke_agent, execute_tool, chat, output_messages (má být chat, ne inference).
  • 200 spolu s partialSuccess: null, ale žádný řádek v aplikaci Defender po 5 minutách → žádný uživatel v tenantovi zákazníka nemá přiřazenu licenci Microsoft 365 E7 nebo Microsoft Agent 365 (Limity a podmínky zahazování, podmínka zahazování 2). Oprava: Ověřte, že alespoň jeden uživatel v tenantu má přiřazenu licenci (nejen přítomnou v tenantu); v opačném případě kontaktujte tým pro onboarding služby Agent 365.
  • Spany se zobrazují, ale strom běhu je narušen / některé podřízené spany jsou osiřelé → chybí parentSpanId, odlišný traceId nebo gen_ai.conversation.id není nastaven na každém spanu. Oprava: Projděte si část Hierarchie spanů a seskupování běhů.

Běžná úskalí

Příznak Pravděpodobná příčina Oprava
401 Unauthorized Nesprávná hodnota aud v tokenu. Použijte 9b975845-388f-4429-889e-eab1ef63949c (nebo api://9b975845-...).
403 Forbidden, chybějící role / rozsah Token neobsahuje Agent365.Observability.OtelWrite. Onboardujte svou aplikaci Microsoft Entra do role (S2S) nebo rozsahu (delegovaného) podle části Rozsahy a souhlas. Pro S2S musí být token získán s oborem <resource>/.default.
403 Forbidden, neshoda identity agenta {agentId} v URL ≠ appid / azp tokenu, nebo span nese gen_ai.agent.id, což neodpovídá ověřenému agentovi. Trasa agentId musí být appId volající aplikace. U identit odvozených z podrobného plánu je to appId identity agenta, ne appId podrobného plánu. Ujistěte se, že odpovídá gen_ai.agent.id každého spanu.
200 OK ale partialSuccess.rejectedSpans == totalSpans Všechny spany obsahovaly nesprávný atribut gen_ai.operation.name. Použijte jednu z hodnot invoke_agent, execute_tool, chat nebo output_messages. Je to chat, ne inference.
200 OK s partialSuccess: null, ale v aplikaci Defender se nezobrazují žádná data Žádný uživatel v tenantovi zákazníka nemá přiřazenu licenci Microsoft 365 E7 nebo Microsoft Agent 365 (Limity a podmínky zahazování). Ujistěte se, že alespoň jeden uživatel v tenantu má přiřazenu licenci Microsoft 365 E7 nebo Microsoft Agent 365 (pouhá přítomnost SKU nestačí). Ověřte pomocí KQL v části Ověření ingesce; pokud se do 5 minut nic nezobrazí, kontaktujte tým služby Agent 365.
Spany se nachází v CloudAppEvents, ale běh chybí v zobrazeních aktivit agentů aplikace Defender a v centru pro správu Microsoft 365. Běh neobsahuje span invoke_agent. Obě vrstvy používají jako identifikátor hodnotu invoke_agent. V kořeni každého běhu generujte přesně jeden span invoke_agent v; pomocí parentSpanId z něj vytvořte nadřazený span pro chat / execute_tool / output_messages.
Strom běhu je rozbitý / spany nástrojů se jeví jako osiřelé U podřízených spanů chybí parentSpanId nebo mají jiný traceId. Viz Hierarchie spanů a seskupování běhů. Každý ne-kořenový span nastavuje parentSpanId a sdílí traceId běhu.
Spany nástrojů zobrazují v dotazech prázdné hodnoty ChannelName / ConversationId Kanál / konverzace nejsou nastaveny na spanu nástroje a nadřazený span invoke_agent nebyl ve stejném požadavku OTLP. Nastavte microsoft.channel.name a gen_ai.conversation.id na každém spanu.
413 Payload Too Large Text požadavku > 1 MB. Rozdělte spany do více požadavků.
429 Too Many Requests Byl dosažen limit počtu požadavků. Dodržujte hodnotu Retry-After: 1 a použijte postupné zpomalování s náhodným zpožděním.
Agent se v řídicích panelech zobrazuje jako neidentifikovaný Hodnota gen_ai.agent.id je prázdná nebo není ve formátu GUID. Použijte Entra appId agenta. Pokud agent nemá registraci Entra, viz Výběr hodnot.

Další kroky

  • Last updated on