استثناءات OpenTelemetry في التتبع هي ما ينقصك حين يرنّ هاتف المناوبة قبيل الفجر في يوم تخفيضات: 4% من عمليات الدفع تفشل، ولا تعرض لوحة المتابعة سوى أعمدة حمراء. من دونها تعرف أن الـ span فشل ولا تعرف السبب، ومعها يصلك مكدس الاستدعاءات داخل التتبع نفسه الذي وقع فيه الخطأ.
أنطلق من هذه المناوبة وأمضي مع SDK الخاص بـ Python خطوة خطوة: ماذا نكتب في الشيفرة، وماذا يحفظ الـ span فعلًا، وكيف نقرر أمام الإهمال (deprecation) المعلن، ثم كيف نفرز النتائج في Dynatrace SaaS. هدف مهندس SRE بسيط: خفض MTTR بالانتقال من معدل الأخطاء إلى السبب في استعلامين.
ما تحققت منه وما لم أتحقق منه: شغّلت شيفرة Python مع opentelemetry-sdk الإصدار 1.45.2 وأعرض المخرجات الحقيقية. أما استعلامات DQL فـلم أشغّلها، فمصدرها وثائق Dynatrace وهي هنا أمثلة. كل ما يلي يخص Dynatrace SaaS (Grail وDQL)، ولا يشمل Dynatrace Managed.
معلومتان في حقلين: الحالة والاستثناء
الـ span الذي ينتهي صامتًا تكون حالته Unset، وتفسّرها وثائق OpenTelemetry بأنها «لا خطأ». وكي يدخل في مؤشر مستوى الخدمة (SLI) يجب تحويلها إلى ERROR. هذا هو الحقل الأول: يمكن تصفيته وعدّه.
الحقل الثاني يجيب عن سؤال الثالثة فجرًا. يعيش الاستثناء في حدث مرتبط بالـ span الذي فشل، أي بالخدمة والعملية الصحيحتين وبقيمة trace_id الدقيقة. فلا حاجة إلى مطابقة يدوية مع ملف سجل.
احفظ قاعدة القراءة هذه: الحالة للعدّ، والحدث للفهم. ولا يكفي أحدهما دون الآخر.
تسجيل استثناءات OpenTelemetry في التتبع من الشيفرة
في أمثلة Python، يقرن OpenTelemetry بين set_status وrecord_exception. ولم أجد في الصفحة التي قرأتها ما يفيد بأن الاستثناء الذي يعبر كتلة with يستدعي الدالتين تلقائيًا، لذا أكتبهما بنفسي في موضع واحد.
بيئة الاختبار: حزمة opentelemetry-sdk، ومُصدِّر إلى الطرفية لقراءة الـ span دون خادم خلفي، ودالة دفع تفشل عمدًا.

في هذا الملف تفصيلان مهمان. السطر 18 ينسخ الرسالة إلى وصف الحالة فتظهر دون فتح الحدث. والسطر 19 ينشئ الحدث. وإذا كان على المستدعي أن يعلم بالفشل فأنهِ الكتلة بـ raise، وإلا بقيت الـ spans الأم خضراء رغم فشل الابن.
قراءة الـ span: ما أنتجه التشغيل
تثبّت المواصفة اسم الحدث exception وثلاث سمات: exception.type وexception.message وexception.stacktrace. النوع والرسالة «مطلوبان بشرط» (يكفي أحدهما)، أما المكدس فمستحسن فقط. وهذا ما طبعته الطرفية عندي.

- تتجاور الحالة والحدث في الكائن نفسه، لكنهما معلومتان مستقلتان.
- يضيف الـ SDK لديّ أيضًا
exception.escaped. وتعدّه المواصفة مهجورًا، وتطلب التوقف عن تسجيل الاستثناءات المعالَجة التي لا تغادر الـ span. - تصل الرسالة إلى الخادم الخلفي كما هي، وتحذّر المواصفة من احتوائها على بيانات حساسة. لا مكان لرقم عميل أو رمز وصول في نص استثناء.
هل نخشى الإهمال؟ قرار على ثلاث مراحل
تعرض صفحة المواصفة الخاصة باستثناءات الـ spans وسم «Deprecated» وتحيل إلى اصطلاحات السجلات. ومع ذلك ما زال الـ SDK الذي شغّلته ينتج الحدث. الأمران صحيحان معًا، والترجيح بينهما عليك.
لضبط الانتقال، تعرّف المواصفة المتغيّر OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN:
- غير معرَّف: تُبقي أداة القياس على حدث الـ span؛
logs: تخرج الاستثناءات سجلات فقط؛logs/dup: تخرج الإشارتان معًا طوال فترة طرح تدريجي.
أما في السجلات فتتبع الخطورة جسامةَ الحالة: ERROR (17) لاستثناء غير معالَج لا يوقف التطبيق، وWARN (13) لاستثناء يتعيّن على الشيفرة معالجته. وإن كانت أداة القياس تنشئ spans أيضًا فيجب أن يحمل السجل سياق الـ span المعني.
وهكذا أقرر أنا. أولًا: ما دام الـ SDK يصدر الحدث واستعلاماتك تقرؤه فلا تغيّر شيئًا. ثانيًا: جرّب logs/dup على خدمة قليلة الحساسية. ثالثًا: أوقف الحدث بعد أن تعيد كتابة استعلاماتك فقط.
تنبيه: كل SDK يقرر هل يقرأ هذا المتغيّر. مع القيمة logs وSDK الخاص بـ Python 1.45.2 بقي الحدث داخل الـ span. ولم أختبر لغات أخرى ولا وكلاء القياس التلقائي.
المنطق نفسه في الانتقال موجود في HTTP: راجع اصطلاحات OpenTelemetry الدلالية واستقرارها. وللجانب المتعلق بالسجلات اقرأ سجلات OpenTelemetry المستقرة.
من معدل الأخطاء إلى السبب في Dynatrace SaaS
تصل الـ spans عبر OTLP مباشرة أو عبر Collector. يرد الإعداد في مقال Collector الخاص بـ OpenTelemetry نحو Dynatrace. ولم أختبر الإدخال من طرف إلى طرف.
تقترح صفحة «Use traces, DQL, and logs to spot patterns» في وثائق Dynatrace استعلام فرز، أشرحه بطريقتي.

يؤدي الاستعلام أربع مهام من الأعلى إلى الأسفل. أولًا يستبعد filter iAny(…) كل span لا يحمل حدث exception. ثم يفرد expand span.events القائمة: صف لكل حدث. بعدها يحوّل fieldsFlatten الحقلين exception.type وexception.message إلى أعمدة. وأخيرًا يعدّ summarize بحسب الخدمة والرسالة، فيتصدر القائمةَ المشتبهُ به الأرجح.
ولمعرفة وقت بدء الخطأ تقترح الصفحة نفسها makeTimeseries count(), by: {exception.type}, time:start_time. وبعد تحديد الخدمة افتح تتبعًا فاشلًا واقرأ المكدس. وإن لم يوجد التتبع أصلًا فابدأ بـ تشخيص غياب تتبعات OpenTelemetry.
لم أتحقق من الاسم الدقيق لحقل الحالة في spans الخاصة بـ Grail، ولن أخترعه. تأكد منه في دفتر ملاحظات (notebook) قبل بناء تنبيه عليه.
خمسة فخاخ صادفتها
- استثناء بلا حالة: يظهر في التتبع لكنه لا يدخل في معدل الأخطاء.
- حالة بلا استثناء: يظهر الـ span أحمر دون مكدس.
- الاستثناءات المعالَجة: إن التقطتها الشيفرة وواصلت فلا تسجّلها، فهي تغمر الأخطاء الحقيقية.
- العدّ المزدوج: مع
logs/dupيوجد الاستثناء نفسه مرتين. أزل التكرار قبل العدّ. - سوء فهم الإهمال: يخص اصطلاح الـ span. أما الاستدعاء
record_exceptionفما زال في مثال Python الرسمي الذي قرأته.
أفضل الممارسات
- الحالة والاستثناء في الموضع نفسه، مرة واحدة لكل span.
raiseبعد التسجيل، ليرى الآباء الفشل.- الترحيل عبر
logs/dupمع قياس قبل أي إيقاف. - رسائل استثناء خالية من البيانات الشخصية.
- سجلات مرتبطة بالتتبعات كما في سجلات OpenTelemetry مع trace_id.
الأسئلة الشائعة
هل ما زلت أستدعي record_exception؟
نعم، إن كان الـ SDK ينتج الحدث والخادم الخلفي يقرؤه. ويدل متغيّر الانتقال على أن السلوك الافتراضي ما زال حدث الـ span. اختبر الـ SDK الخاص بك.
الحالة ERROR أم الحدث exception: أيهما أختار؟
كليهما. تتيح الحالة تصفية الإخفاقات وعدّها، ويقدّم الحدث النوع والرسالة والمكدس.
كيف أرتّب الخدمات بحسب عدد الاستثناءات؟
عدّل استعلام الوثائق: filter iAny على الحدث، ثم expand ثم fieldsFlatten ثم summarize count() بحسب service.name. وهذه الاستعلامات خاصة بـ Dynatrace SaaS.
خلاصة
ثلاث خطوات: ثبّت الحالة، وسجّل الحدث، وخطّط للانتقال نحو السجلات. اليوم يعمل حدث الـ span مع الـ SDK الذي اختبرته، ويتجه المسار الرسمي نحو السجلات. طوّر استعلاماتك بتطور الـ SDK لديك، وتحقق من كل خطوة في بيئتك.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. العلامات الأخرى المذكورة تعود إلى مالكيها. الأدوات تتطور بسرعة: تحقق دائمًا من الأوامر والخيارات في الوثائق الرسمية الخاصة بإصدارك. المصادر: مواصفة الاستثناءات في الـ spans (صفحة قُرئت في 8 نوفمبر 2026).