استكشاف أخطاء الرصد المباشر عبر OTel وإصلاحها

استخدم هذا الدليل للتحقق من استيعاب بيانات تتبع الاستخدام وتشخيص المشاكل المتعلقة ببيانات تتبع الاستخدام للعامل المرسلة إلى العامل 365 مباشرة عبر OTLP. يقتصر هذا على مسار OTel المباشر — إذا كنت تستخدم Agent 365 SDK أو Microsoft OpenTelemetry Distro، فارجع إلى تلك الأدلة بدلاً من ذلك. للحصول على حدود على مستوى الأسلاك ورموز الخطأ وشروط الإفلات الصامتة، راجع الحدود وشروط الإفلات.

التحقق من الاستيعاب

200 موافق ليس دليلاً على الاستيعاب. ترجع بعض حالات الإفلات 200 مع partialSuccess: null ولا تظهر بياناتك ببساطة (راجع الحدود وشروط الإفلات). تحقق دائمًا من عمليات التشغيل الأولى:

  1. تحقق من حالة HTTP. 200 → المضي قدما. 4xx → انظر الأخطاء الشائعة.
  2. حلل partialSuccess. null يعني أن واجهة برمجة التطبيقات قبلت كل شيء. أي شيء آخر يعني أنه تم إسقاط بعض النطاقات على الأقل عند عامل التصفية لكل نطاق.
  3. انتظر ~5 دقائق، ثم قم بتشغيل استعلام البحث المتقدم التالي في Defender.
  4. ألا يوجد صف؟ استخدم شجرة القرار ضمن No data in Defender.

استعلام البحث المتقدم في Defender

البحث الأساسي (بالاعتماد على هوية العامل التي أرسلتها):

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

للحصول على القائمة الكاملة للأسطح (Defender طرق عرض نشاط العامل، مركز مسؤولي Microsoft 365، Microsoft Purview) وما يحتاجه كل منها، راجع أين تظهر بياناتك.

لا توجد بيانات في Defender

  • partialSuccess.rejectedSpans == totalSpans ← جميع نطاقاتك احتوت على gen_ai.operation.name سيء. إصلاح: استخدم واحدا من invoke_agent، ، execute_tool، chatoutput_messages(إنه chat، وليس inference).
  • 200 مع partialSuccess: null لكن لم يكن هناك صف Defender بعد 5 دقائق ← لا يوجد أي مستخدم في مستأجر العميل لديه ترخيص Microsoft 365 E7 أو Microsoft Agent 365 معيَّن له (الحدود وشروط الإسقاط، شرط الإسقاط 2). إصلاح: تأكد من أن مستخدما واحدا على الأقل في المستأجر لديه الترخيص المعين (وليس فقط موجود في المستأجر)؛ وإلا اتصل بفريق إلحاق Agent 365.
  • تظهر النطاقات ولكن شجرة التشغيل معطلة / بعض التوابع معزولة ← مفقودة parentSpanIdأو مختلفة traceIdأو gen_ai.conversation.id غير معيَّن في كل نطاق. إصلاح: راجع التدرج الهرمي للنطاقات وتجميع عمليات التشغيل.

المزالق الشائعة

عَرَض السبب الأكثر احتمالا إصلاح
401 Unauthorized aud غير صحيح في الرمز. استخدم 9b975845-388f-4429-889e-eab1ef63949c (أو api://9b975845-...).
403 Forbidden، الدور / النطاق المفقود لا يتضمن الرمز Agent365.Observability.OtelWrite. ألحق تطبيق Microsoft Entra الخاص بك بالدور (S2S) أو النطاق (المفوَّض) وفقًا لـ النطاقات والموافقة. بالنسبة إلى S2S، يجب الحصول على الرمز المميز باستخدام <resource>/.default.
403 Forbidden، عدم تطابق هوية العامل {agentId} في عنوان URL رقم appid / azp للرمز المميز أو أن نطاق يحمل gen_ai.agent.id لا يتطابق مع العامل المُصادق عليه. يجب أن يكون المسار agentIdمعرف التطبيق لتطبيق الاتصال. بالنسبة للهويات المشتقة من المخطط، إن هذا هو معرف التطبيق الخاص بالعامل، وليس معرف التطبيق الخاص بالمخطط. تأكد من تطابق كل امتداد gen_ai.agent.id .
200 OK لكن partialSuccess.rejectedSpans == totalSpans جميع نطاقاتك احتوت على gen_ai.operation.name سيء. استخدم واحدا من invoke_agent، execute_tool، ، chat. output_messages إنه chat، وليس inference.
200 OK مع partialSuccess: null ولكن لا تظهر أي بيانات في Defender لا يوجد لدى أي مستخدم في مستأجر العميل ترخيص Microsoft 365 E7 أو Microsoft Agent 365 مُعيَّن (الحدود وشروط الإسقاط). تأكد من أن مستخدما واحدا على الأقل في المستأجر لديه ترخيص Microsoft 365 E7 أو Microsoft Agent 365 المعين (وحدة SKU الحالية غير كافية). تحقّق باستخدام KQL في التحقق من الاستيعاب؛ إذا لم تصل أي بيانات بعد 5 دقائق، فاتصل بفريق Agent 365.
تظهر النطاقات في CloudAppEvents ‏، ولكن عملية التشغيل غير موجودة في طرق عرض نشاط عامل Defender وفي مركز مسؤولي Microsoft 365. لا يحتوي المقطع على أي invoke_agent span. يعتمد كلا السطحين على invoke_agent. أصدر عنصر span واحدًا فقط invoke_agent في الجذر لكل تشغيل؛ واجعل chat / execute_tool / output_messages عناصر فرعية له باستخدام parentSpanId.
شجرة التشغيل معطلة / نطاقات الأدوات تبدو معزولة parentSpanId المفقود أو traceId المختلف في النطاقات التابعة. راجع التدرج الهرمي للنطاقات وتجميع عمليات التشغيل. يقوم كل نطاق غير جذر بتعيين parentSpanId ومشاركة traceId الخاص بالتشغيل.
تظهر امتدادات الأدوات فارغة ChannelName / ConversationId في الاستعلامات لم يتم تعيين القناة / المحادثة في نطاق الأداة، ولم يكن invoke_agent موجودًا في طلب OTLP نفسه. تعيين microsoft.channel.name و gen_ai.conversation.id على كل امتداد.
413 Payload Too Large > نص الطلب 1 ميغابايت. قسّم النطاقات على عدة طلبات.
429 Too Many Requests تم تحديد الحد الأقصى للسعر. احترم Retry-After: 1 وتراجع مع التشويش.
يظهر العامل غير معروف في لوحات المعلومات gen_ai.agent.id فارغ أو ليس معرف GUID. استخدم معرف تطبيق Entra الخاص بالعامل. إذا لم يكن لدى العامل تسجيل Entra، فشاهد انتقاء القيم.

الخطوات التالية

  • Last updated on