Sorun giderme doğrudan OTel gözlemlenebilirliği

Bu kılavuzu, telemetri alımını doğrulamak ve aracı telemetrisini doğrudan OTLP üzerinden Agent 365'e gönderirken yaşanan sorunları teşhis etmek için kullanın. Bu rehber, doğrudan OTel yolunu kapsar - eğer Agent 365 SDK veya Microsoft OpenTelemetry Dağıtımı kullanıyorsanız, o rehberlere bakın. Kablo seviyesindeki sınırlar, hata kodları ve sessiz bırakma koşulları için bkz. Sınırlar ve bırakma koşulları.

Telemetri alımını doğrulama

200 OK ise tüketme kanıtı değildir. Bazı drop koşulları 200 yanıtı döndürür partialSuccess: null ve verileriniz görünmez (bkz. Limitler ve drop koşulları). İlk çalıştırmalarınızı mutlaka doğrulayın:

  1. HTTP durumunu kontrol edin. 200 → devam. 4xx → bkz. Sık karşılaşılan hatalar.
  2. partialSuccess ayrıştırın. null API'nin her şeyi kabul ettiği anlamına gelir. Diğer tüm durumlar, en azından bazı span'ların span başına filtrede atıldığı anlamına gelir.
  3. ~5 dakika bekleyin, sonra aşağıdaki Defender gelişmiş avlanma sorgusunu çalıştırın.
  4. Satır yok mu? Defender'da veri yok altındaki karar ağacını kullanın.

Defender gelişmiş av sorgusu

Gönderdiğiniz aracı kimliğiyle eşleştirilen kanonik sorgu:

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

Tüm yüzeylerin (Defender aracı etkinliği görünümleri, Microsoft 365 yönetim merkezi, Microsoft Purview) ve her birinin gereksinimlerinin tam listesi için Verilerinizin nerede göründüğüne bakın.

Defender'da veri yok

  • partialSuccess.rejectedSpans == totalSpans → tüm span'lerinizde hatalı gen_ai.operation.name vardı. Düzeltme: şunlardan birini kullanır: invoke_agent, execute_tool, chat, output_messages (chat idir, inference değildir).
  • 200 yanıtı alındıysa partialSuccess: null ancak 5 dakika sonra Defender'da satır yoksa, müşteri kiracısında hiçbir kullanıcıya Microsoft 365 E7 veya Microsoft Agent 365 lisansı atanmamış demektir (Limits and drop conditions, düşürme koşulu 2). Çözüm: Kiracıda en az bir kullanıcının lisansı atandığını (sadece kiracıda değil) doğrulamak; aksi takdirde Agent 365 işe alım ekibiyle iletişime geçin.
  • Span'ler görünüyor ancak run tree bozuk / bazı alt öğe span'ler yetim kalmış → parentSpanId eksik, traceId farklı veya gen_ai.conversation.id her span'de ayarlanmamış. Düzeltme:Span hiyerarşisini ve run grouping'i gözden geçir.

Yaygın hatalar

Belirti En olası neden Düzelt
401 Unauthorized Belirteç üzerinde yanlış aud. 9b975845-388f-4429-889e-eab1ef63949c kullanın (veya api://9b975845-...).
403 Forbidden, eksik rol / kapsam Belirteç Agent365.Observability.OtelWrite taşımıyor. Microsoft Entra uygulamanızı Scopes ve onay ile role (S2S) veya kapsama (delege) dahil edin. S2S senaryosunda, jeton <resource>/.default ile alınmalıdır.
403 Forbidden, aracı kimliği uyumsuzluğu URL'deki {agentId} ile token'daki appid / azp aynı değil veya bir span, kimliği doğrulanmış aracı ile uyumsuz bir gen_ai.agent.id taşıyor. Rota agentId çağıran uygulamanın appId olmalıdır. Blueprint'ten türetilmiş kimlikler için doğru appId, blueprint appId değil, aracı kimliğinin appId'sidir. Her bir span'ın gen_ai.agent.id'sinin eşleştiğinden emin olun.
200 OK ama partialSuccess.rejectedSpans == totalSpans Tüm span'larda hatalı gen_ai.operation.name vardı. Şunlardan birini kullanın: invoke_agent, execute_tool, chat, output_messages. chat idir, inference değil.
partialSuccess: null ile 200 OK, ancak Defender'da hiçbir veri görünmüyor Müşteri kiracısındaki hiçbir kullanıcıya Microsoft 365 E7 veya Microsoft Agent 365 lisansı atanmamış (Limitler ve veri düşürme koşulları). Kiracıda en az bir kullanıcıya Microsoft 365 E7 veya Microsoft Agent 365 lisansı atanmış olduğundan emin olun (SKU'nun mevcut olması yeterli değildir). Veri alımını doğrulama bölümündeki KQL ile doğrulayın; 5 dakika içinde herhangi bir veri ulaşmazsa, Agent 365 ekibiyle iletişime geçin.
Spans içinde CloudAppEvents görünür ancak bu çalışma Defender aracı-aktivite görünümlerinde ve Microsoft 365 yönetim merkezi tarafından eksiktir Koşuda invoke_agent span yok. Her iki yüzey de invoke_agent'i temel alır. Her çalışmanın kökünde tam olarak bir invoke_agent aralığı yayın; chat / execute_tool / output_messages aralıklarını parentSpanId ile onun alt öğesi olarak bağlayın.
Run ağacı bozulmuş / araç aralıkları yetim kalmış Alt öğe span'larda parentSpanId eksik veya traceId farklı. Span hiyerarşisi ve koşu gruplaması bölümüne bakın. Her kök olmayan span, parentSpanId ayarlar ve çalışmanın traceId değerini paylaşır.
Araç span'ları sorgularda boş ChannelName / ConversationId olarak görünür. Araç span üzerinde kanal / konuşma ayarlanmadı ve üst öğe invoke_agent aynı OTLP isteğinde değildi. Her bir span üzerinde microsoft.channel.name ve gen_ai.conversation.id ayarlayın.
413 Payload Too Large İstek gövdesi > 1 MB. Span'leri birden fazla isteğe dağıtın.
429 Too Many Requests Oran limiti aşıldı. Retry-After: 1 değerine uyun ve jitter ile geri çekilin.
Aracı gösterge panellerinde kimliği belirsiz görünüyor gen_ai.agent.id boş ya da bir GUID değil. Aracının Entra appId'sini kullanın. Aracının Entra kaydı yoksa, Değerleri Seçme bölümüne bakın.

Sonraki adımlar

  • Last updated on