Prometheus / الأساسي: الجمع ومعنى السلاسل الزمنية / الدرس 3
العدادات والمقاييس الحالية وعقود العرض
اختر نوع المقياس بحسب معنى الكمية، واقرأ مقطع عرض نصي، وافصل إعلان نوعه عن العملية التي يجب تطبيقها في الاستعلام.
في هذه الصفحة
أهداف الدرس
- قارن العدادات والمقاييس الحالية والتوزيعات.
- فسّر إعلاني HELP وTYPE في صيغة العرض.
- راجع الوحدات والتسمية وسلامة نقطة العرض.
اختر النوع قبل كتابة الاستعلام
يراكم العداد أحداثاً أو كمية غير سالبة، وقد يعاد ضبطه عند إعادة تشغيل العملية. ويمثل gauge قيمة حالية يمكن أن ترتفع أو تنخفض، مثل عدد الطلبات الجارية. وتمثل المدرجات والملخصات توزيعات بخصائص تجميع مختلفة سنبحثها لاحقاً. لا تطبق rate آلياً على كل سلسلة عددية؛ فانخفاض عمق طابور ليس إعادة ضبط عداد. اكتب الكمية ووحدتها وحد تحديثها والتجميع المقصود قبل اختيار الأداة. لا ينقذ قبول صياغة الاستعلام أداة تعد محاولات كتابة بينما يعد توثيقها كتابات مثبتة.
اقرأ البيانات الوصفية والعينات منفصلة
يعلن المقطع النصي عداداً وgauge بتعليقي HELP وTYPE، ثم يقدم عينات افتراضية. يصف الإعلان القصد، ولا يجعل استعلاماً غير مناسب ذا معنى. يركز مرجع الدورة الثابت على العينات العائمة وسلاسل المدرجات التقليدية، دون افتراض إمكان تبادل كل قدرات البروتوكولات. لصيغة العرض قواعد هروب وترميز ونوع محتوى واتساق، وينبغي أن تعالجها مكتبة عميل مدعومة في الشيفرة الفعلية. قد تستجيب النقطة على مستوى HTTP بينما يمنع محتواها المشوه أو غير المتوافق جمعاً مفيداً. ليس المقطع تطبيقاً مراقباً كاملاً.
# HELP warehouse_requests_total Eligible warehouse API attempts.
# TYPE warehouse_requests_total counter
warehouse_requests_total 42
# HELP warehouse_in_flight Current warehouse API work.
# TYPE warehouse_in_flight gauge
warehouse_in_flight 3
يصف العداد محاولات متراكمة، ويصف gauge العمل الحالي. المقطع توضيحي ولم يُقدّم عبر خدمة أو يُجمع أو يُفحص ببروتوكول.
قارن المتراكم بالحالي
يزيد النموذج المحلي عدد العمليات المكتملة، ويغير العمل الحالي عبر البدء والانتهاء. يكون العداد النهائي اثنين والعمل الجاري واحداً. تجيب الكميتان سؤالين مختلفين، ولا ينبغي طرحهما كأنهما مجموعة واحدة. يغفل النموذج التزامن وإعادة تشغيل العملية وتزامن مكتبة العميل، ولا يثبت إلا الانتقالات المعروضة. يجب أن تتعامل الأداة الفعلية مع نموذج تنفيذها المدعوم، وأن تتجنب إنشاء تسميات مكلفاً في المسارات الساخنة. وضح معنى الفشل والإلغاء بدلاً من ترك سطر زيادة واحد يحدد تصنيفهما مصادفة.
completed = 0
in_flight = 0
for action in ["start", "start", "finish", "start", "finish"]:
if action == "start":
in_flight += 1
else:
in_flight -= 1
completed += 1
assert in_flight >= 0
print("completed_total", completed)
print("in_flight", in_flight)
completed_total 2
in_flight 1
تُعالج قائمة أفعال ثابتة فقط. لا تستورد العينة مكتبة عميل، ولا تنفذ تطبيقاً متزامناً أو مرصوداً.
اجعل الاسم والوحدة يخدمان التفسير
استخدم أسماء واضحة للكميات ووحدات أساسية متسقة، مثل الثواني للمدة والبايتات للحجم، وفق عقد المشروع الفعلي. تنتهي أسماء العدادات عادة بـ_total، ولا ينبغي أن تتضمن قيم تسميات متغيرة. لا تخلط كميات فيزيائية مختلفة تحت اسم واحد. لا تحول تسمية الوحدة في اللوحة القياس المحفوظ تلقائياً في كل أداة. إن استخدم مقياس قديم المللي ثانية، فوثق هجرة مقصودة، ولا تقسم لدى مستهلك واحد وتترك الآخرين على افتراض قديم. راجع إرشادات التسمية الرسمية مع توثيق نسخة الخادم الثابتة.
اعرض الأدلة اللازمة فقط
قد تكشف نقاط المقاييس تفاصيل النشر ونشاط العمل، حتى دون كلمة مرور ظاهرة. أبعد الحقول الشخصية غير اللازمة وبيانات الاعتماد والمعرفات غير المحدودة عن التسميات. تخضع حماية الوصول والنقل لتصميم البيئة المخول. لا تجعل الجمع يطلق عملاً تجارياً مكلفاً أو يعدل حالة التطبيق؛ بل اعرض مشاهدات بتكلفة مضبوطة. لا تفتح الدورة مستمعاً ولا تجمع بيانات. يتحقق نموذج بايثون من سلوك الكمية فقط، ويترك تزامن المكتبة والتسلسل وتفاوض HTTP والمصادقة وتوافق الجمع دون اختبار.
الأخطاء الشائعة وإصلاحها
يفسر انخفاض gauge كإعادة تشغيل.
- لماذا يحدث؟
- طُبق منطق العداد على قيمة حالية.
- كيف تصلحه؟
- اختر الاستعلام من نوع الكمية ومعناها.
- كيف تتجنب تكراره؟
- احفظ معنى الأداة في عقد المقياس.
يُعد TYPE counter ضماناً لصحة معدل خاطئ.
- لماذا يحدث؟
- عوملت البيانات الوصفية كضمان صحة.
- كيف تصلحه؟
- راجع الزيادات والضبط وحدود الرصد.
- كيف تتجنب تكراره؟
- اختبر انتقالات أحداث ممثلة.
يغير العرض الوحدة دون هجرة للبيانات.
- لماذا يحدث؟
- اختلطت التسمية بالتحويل العددي.
- كيف تصلحه؟
- وحّد قياس المصدر وكل المستهلكين.
- كيف تتجنب تكراره؟
- نسّخ تغير الوحدة وعينات القيم المعلومة.
اختبر فهمك
1. هل ينبغي تمثيل مقدار الذاكرة الحرة الحالية بعداد لا يتوقف عن الزيادة؟
اعرض الحل المشروح
لا. الذاكرة الحرة كمية حالية قد ترتفع أو تنخفض. اختر تمثيل gauge مناسباً، وعرّف الوحدة والنطاق. قد يفيد عداد تراكمي مستقل للتخصيصات، لكنه يقيس كمية مختلفة ولا يستطيع أن يحل محل مشاهدة الحالة الحالية.
2. يسمى مقياس كتابات مكتملة، لكنه يزداد قبل تنفيذ التخزين. ما التغيير المطلوب في عقده أو موضع رصده؟
اعرض الحل المشروح
إما أعد تسميته ووثقه بوصفه محاولات عمل، أو انقل المشاهدة إلى حد الاكتمال المطلوب. أدرج النتائج الفاشلة والملغاة والمجهولة في العقد. لا تجعل جملة HELP زيادة قبل الثبات دليلاً على اكتمال دائم، ونجاح تصدير القياس مسألة منفصلة.
أهم ما تعلمته
- يتبع نوع المقياس سلوك الكمية.
- لا تضمن بيانات العرض الوصفية صحة معنى العمل.
- تحتاج الوحدات والسلامة وحدود الاكتمال مراجعة مقصودة.