انطلق تنبيه زمن الاستجابة p99، ويُظهر رسم Grafana ذروة عند الساعة 14:07، ويعود إلى المناوب السؤال نفسه دائمًا: أي طلب كان البطيء؟ هنا تأتي Prometheus exemplars. فهي تربط بنقطة المقياس معرّف تتبع حقيقي، فتنتقل من الرسم إلى تتبع OpenTelemetry بنقرة واحدة.
مصدر المعلومات وثائق Prometheus ومواصفة OpenMetrics ووثائق Grafana، وقد قُرئت في 12 نوفمبر 2026. لم أبنِ بيئة كاملة لهذا المقال: اللقطات تعرض ملفات أمثلة مبنية على تلك الصفحات، وكل ما لم أتحقق منه موسوم بذلك صراحة.
إن كانت الـ spans جديدة عليك، فابدأ بقراءة تشريح span في OpenTelemetry. الإشارتان تكمّل إحداهما الأخرى: المقياس يخبرك «متى وكم»، والتتبع يخبرك «أيّ طلب».
المشكلة: المتوسط لا يشير إلى طلب بعينه
يجمع مقياس التأخر آلاف الطلبات في بضعة عدّادات، وهذا ما يجعله رخيصًا. لكن عندما يرتفع p99 تحتاج إلى طلب محدد، وقد نسيه المقياس بالفعل.
بلا رابط مباشر تبدأ رحلة تنقيب: تدوّن وقت الذروة، وتفتح أداة التتبع، وتصفّي بحسب الخدمة والمدة، وتأمل ألّا يكون أخذ العينات قد أسقط التتبع المطلوب. وكل دقيقة تُنفق هنا تُضاف إلى MTTR.
القرار التشغيلي إذن بسيط: هل تقبل أن تخزّن إلى جانب سلاسلك مجموعة صغيرة من المراجع إلى التتبعات؟ هذا هو مبدأ الـ exemplar، وله كلفة ذاكرة محددة نحسبها أدناه.
ما الذي تسمح به المواصفة في Prometheus exemplars
الـ exemplar مرجع إلى بيانات خارج المقياس، وهو عادةً معرّف تتبع. تربطه صفحة feature flags في Prometheus بصيغة OpenMetrics: تتيح هذه الصيغة للهدف الذي يُجمع منه أن يُلحق exemplars ببعض المقاييس.
تحدّ مواصفة OpenMetrics النطاق: تسمح بـ exemplar على قيم الـ buckets في المدرج التكراري وعلى المجموع في العدّاد، ولا تذكر المقاييس من نوع gauge ولا summary. وفي سطر النص يأتي الـ exemplar بعد القيمة وبعد علامة #، ومعه وسومه وقيمته المرصودة.

قيد يجب معرفته: وفق المواصفة، لا يتجاوز الطول الإجمالي لأسماء الوسوم وقيمها في الـ exemplar الواحد 128 نقطة ترميز UTF-8. ومعرّف التتبع يتّسع لها بسهولة. لكن لا تضف وسومًا أخرى «لمزيد من السياق».
تفعيل exemplar-storage دون مفاجآت في الذاكرة
افتراضيًا لا يحتفظ Prometheus بالـ exemplars التي يجمعها. يجب تشغيل الخادم مع --enable-feature=exemplar-storage. وبحسب الوثائق تُحفظ الـ exemplars حينئذٍ في مخزن دائري داخل الذاكرة بحجم ثابت، تشترك فيه جميع السلاسل.
- شغّل Prometheus مع feature flag بالاسم
exemplar-storage. - اضبط حجم المخزن في كتلة
storageثمexemplarsمن الإعدادات: قيمةmax_exemplarsالافتراضية 100000 بحسب صفحة الإعدادات، ويمكن تغييرها دون إعادة تشغيل. - تأكد من أن أهدافك تعرض exemplars فعلًا في صيغة الجمع التي تستخدمها.

تعطي الوثائق رتبة حجم: الـ exemplar الذي يحوي trace_id فقط يزن نحو 100 بايت. ومع 100000 إدخال يبلغ المجموع نحو 10 ميغابايت، وهذا حسابي من ذلك الرقم لا قياس فعلي. ولأن المخزن دائري، تختفي الـ exemplars الأقدم أولًا. وفي بيئة كثيرة الضجيج قد لا تتعدى النافذة بضع دقائق: تحقق في بيئتك.
نقطة أخرى: بحسب الصفحة نفسها تُكتب الـ exemplars أيضًا في WAL للحفظ المحلي وطوال مدة بقاء WAL. لم أقرأ سلوكها مع remote write، فإن كنت ترسل إلى تخزين بعيد فاقرأ القسم المعني، مثل Grafana Mimir لتخزين مقاييس Prometheus.
الاستعلام عن الـ exemplars عبر الواجهة البرمجية
قبل ضبط Grafana، تأكد أن Prometheus استقبلها. تقدّم الواجهة البرمجية نقطة النهاية /api/v1/query_exemplars عبر GET أو POST، وتصفها الوثائق بأنها تجريبية. تأخذ استعلام PromQL ونافذة start وend.
يسرد الرد لكل سلسلة وسومها seriesLabels ثم مصفوفة exemplars. يضم كل exemplar وسومه labels (مثل trace_id) وقيمة value وطابعًا زمنيًا timestamp بثواني Unix. فإن كانت المصفوفة فارغة فلا داعي للمتابعة: المشكلة في المنبع، إما في العرض أو في feature flag.
من الرسم إلى تتبع OTel في Grafana
يظهر الـ exemplar في Grafana نجمةً على الرسم. عند تمرير المؤشر تقرأ معرّف التتبع، ويفتح زرٌّ التتبع في مصدر بيانات التتبعات، وهو Tempo في مثال الوثائق. ودعم الـ exemplars معلن لمصدر بيانات Prometheus فقط.
يُعلن الربط في مصدر Prometheus. يحدد الحقل Label name مفتاح الوسم الحامل للمعرّف، ويشير رابط داخلي إلى مصدر التتبعات. وبالـ provisioning يبدو هكذا.

إن لم يكن لديك خلفية للتتبعات بعد، فمقالنا عن Grafana Tempo مع kube-prometheus-stack يصف تثبيتًا. موضع الحذر في مكان آخر: يجب أن يكون المعرّف نفسه في الجهتين. ويتحقق ذلك حين يقرأ التطبيق trace_id من span في OpenTelemetry نشط لحظة تسجيل المدة.
فخ أخذ العينات
هذه الحالة هي الأكثر إيقاعًا بالناس. يشير الـ exemplar إلى تتبع أسقطه tail sampling، فتقودك النقرة إلى صفحة «غير موجود». يسجّل التطبيق الـ exemplar، لكن قرار الاحتفاظ بالتتبع يُتخذ لاحقًا في المسار.
علاجان تختار بينهما بحسب ميزانيتك. الأول أن تحتفظ دائمًا بالتتبعات البطيئة وتلك التي فيها أخطاء، كما في قواعد tail sampling في Collector. والثاني ألّا تسجّل exemplar إلا إذا كان التتبع موسومًا بأنه مأخوذ في العينة: لم أتحقق من أن مكتبة العميل لديك تتيح ذلك، فراجع وثائقها.
ممارسات جيدة
- ابدأ بتأخر خدمة حرجة واحدة على مدرج تكراري، لا بالأسطول كله.
- اجعل
trace_idالوسم الوحيد في الـ exemplar: الحد 128 حرفًا. - تحقق عبر
query_exemplarsقبل أن تلوم Grafana. - أبقِ التتبعات البطيئة في tail sampling، وإلا قادتك النجمة إلى لا شيء.
- دوّن في دليل التشغيل: «ذروة p99، مرّر المؤشر على النجوم، افتح التتبع الأبطأ».
الأسئلة الشائعة
هل تعمل الـ exemplars مع أي مقياس؟
لا. تتوقعها مواصفة OpenMetrics على buckets المدرج التكراري وعلى مجموع العدّاد، ولا تصفها للمقاييس من نوع gauge.
كم تستهلك الـ exemplars من الذاكرة؟
تذكر الوثائق نحو 100 بايت لـ exemplar يقتصر على trace_id، داخل مخزن بحجم ثابت يضبطه max_exemplars (القيمة الافتراضية 100000). قِس في بيئتك قبل تغيير هذه القيمة.
وماذا لو كنت أستخدم Dynatrace؟
يتناول هذا المقال Prometheus وGrafana وOpenMetrics فقط. وللربط بين المقاييس والتتبعات في Dynatrace راجع docs.dynatrace.com مع التمييز بين SaaS وManaged، فأنا لا أخلط هنا بين أي وظيفة منهما. ولمقارنة المقاربتين انظر OpenTelemetry وPrometheus.
الخلاصة
تحوّل Prometheus exemplars ذروة التأخر إلى قائمة تتبعات مرشّحة مقابل بضعة ميغابايت من الذاكرة. فعّل الـ feature flag، وتحقق عبر الواجهة البرمجية، وأعلن الربط في Grafana، ثم احمِ تتبعاتك البطيئة من أخذ العينات. المصادر: feature flags في Prometheus، ومواصفة OpenMetrics، وexemplars في Grafana.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا لشركة Grafana Labs ولا لـ Prometheus Authors. العلامات التجارية المذكورة تعود إلى أصحابها. الأدوات تتغير بسرعة، فتحقق دائمًا من الأوامر والخيارات في الوثائق الرسمية الخاصة بإصدارك.