Problemen met directe OTel-observability oplossen

Gebruik deze gids om te controleren of telemetrie wordt ontvangen en om problemen te diagnosticeren met agenttelemetrie die rechtstreeks via OTLP naar Agent 365 wordt verstuurd. Deze gids is bedoeld voor het directe OTel-pad – als u de Agent 365-SDK of de Microsoft OpenTelemetry Distro gebruikt, raadpleeg dan die gidsen. Voor limieten op netwerkniveau, foutcodes en stille dropcondities, zie Limieten en dropcondities.

Gegevensopname verifiëren

Een 200 OK is geen bewijs van gegevensopname. Sommige dropcondities retourneren 200 met partialSuccess: null en uw gegevens verschijnen simpelweg niet (zie Limieten en dropcondities). Controleer altijd uw eerste runs:

  1. Controleer de HTTP-status. 200 → doorgaan. 4xx → zie Veelvoorkomende valkuilen.
  2. Parseer partialSuccess. null betekent dat de API alles accepteert. Elke andere waarde betekent dat ten minste enkele spans zijn gedropt door het per-spanfilter.
  3. Wacht ~5 minuten en voer dan de query voor geavanceerde opsporing van Defender hieronder uit.
  4. Geen rij? Gebruik de beslissingsstructuur onder Geen data in Defender.

Query voor geavanceerde opsporing van Defender

De canonieke zoekopdracht (waarbij gegevens worden gekoppeld op basis van de door u verzonden agentidentiteit):

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

Voor de volledige lijst van surfaces (agent-activiteitsweergaven van Defender, Microsoft 365-beheercentrum, Microsoft Purview) en wat elke surface vereist, zie Waar uw gegevens verschijnen.

Geen gegevens in Defender

  • partialSuccess.rejectedSpans == totalSpans → al uw spans hadden een slechte gen_ai.operation.name. Oplossing: gebruik één van deze: invoke_agent, execute_tool, chat, output_messages (het is chat, niet inference).
  • 200 met partialSuccess: null maar geen Defender-rij na 5 minuten → aan geen enkele gebruiker in de klanttenant is een Microsoft 365 E7- of Microsoft Agent 365-licentie toegewezen (Limieten en dropcondities, dropconditie 2). Oplossing: controleer of aan ten minste één gebruiker in de tenant de licentie is toegewezen (niet alleen aanwezig in de tenant); neem anders contact op met het onboardingteam van Agent 365.
  • Spans verschijnen, maar de run-structuur is verbroken / sommige onderliggende spans zijn verweesd → ontbrekende parentSpanId, andere traceId of gen_ai.conversation.id niet voor elke span ingesteld. Oplossing: zie Span-hiërarchie en run-groepering.

Veelvoorkomende valkuilen

Symptoom Waarschijnlijkste oorzaak Fix
401 Unauthorized Onjuiste aud op token. Gebruik 9b975845-388f-4429-889e-eab1ef63949c (of api://9b975845-...).
403 Forbidden, ontbrekende rol/scope Token bevat geen Agent365.Observability.OtelWrite. Onboard uw Microsoft Entra-app op de rol (S2S) of scope (gedelegeerd) volgens Scopes en toestemming. Voor S2S moet het token worden verkregen met <resource>/.default.
403 Forbidden, niet-overeenkomende agentidentiteit {agentId} in URL ≠ appid / azp van token of een span heeft een gen_ai.agent.id die niet overeenkomt met de geverifieerde agent. De route agentId moet de appId van de aanroepende app zijn. Voor blueprint-afgeleide identiteiten is dat de agentidentiteit-appId, niet de blueprint-appId. Zorg dat de gen_ai.agent.id van elke span overeenkomt.
200 OK maar partialSuccess.rejectedSpans == totalSpans Alle spans hadden een slechte gen_ai.operation.name. Gebruik een van deze: invoke_agent, execute_tool, chat, output_messages. Het is chat, niet inference.
200 OK met partialSuccess: null maar er worden geen gegevens weergegeven in Defender Aan geen enkele gebruiker in de tenant van de klant is een Microsoft 365 E7- of Microsoft Agent 365-licentie toegewezen (Limieten en dropcondities). Controleer of aan minimaal één gebruiker in de tenant een Microsoft 365 E7- of Microsoft Agent 365-licentie is toegewezen (de aanwezigheid van de SKU is niet voldoende). Controleer met de KQL in Gegevensopname verifiëren; als er na 5 minuten geen gegevens zichtbaar zijn, neem contact op met het Agent 365-team.
Spans verschijnen in CloudAppEvents, maar de run ontbreekt in de agent-activiteitsweergaven van Defender en in het Microsoft 365-beheercentrum De run heeft geen invoke_agent-span. Beide surfaces gebruiken invoke_agent als sleutel. Genereer precies één invoke_agent-span aan de root van elke run; koppel chat / execute_tool / output_messages hieraan als onderliggende spans via parentSpanId.
Run-structuur is gebroken / tool-spans lijken verweesd parentSpanId ontbreekt of onderliggende spans hebben een andere traceId. Zie Span-hiërarchie en run-groepering. Elke non-root span stelt parentSpanId in en deelt de traceId van de run.
Tool-spans tonen lege ChannelName / ConversationId in query's Kanaal/gesprek niet ingesteld op de tool-span en de bovenliggende invoke_agent zat niet in dezelfde OTLP-aanvraag. Stel microsoft.channel.name en gen_ai.conversation.id in op elke span.
413 Payload Too Large Aanvraagbody > 1 MB. Splits de spans over meerdere aanvragen.
429 Too Many Requests Aanvraaglimiet bereikt. Respecteer Retry-After: 1 en pas een back-off met jitter toe.
Agent wordt niet geïdentificeerd in dashboards gen_ai.agent.id is leeg of geen geldige GUID. Gebruik de Entra-appId van de agent. Als de agent geen Entra-registratie heeft, zie Waarden kiezen.

Volgende stappen

  • Last updated on