Prometheus وGrafana

أساسيات PromQL

18 دقيقة الدرس 3 من 32

أساسيات PromQL

PromQL (لغة استعلام Prometheus) هي المحرك الذي يحوّل بيانات السلاسل الزمنية الخام إلى معلومات قابلة للتنفيذ. على خلاف SQL التي تتعامل مع الصفوف، تتعامل PromQL مع تدفقات من عينات float64 مفهرسة بالتسميات (Labels). أتقنها وستستطيع الإجابة عن أي سؤال مراقبة يطرحه نظامك — توزيعات الزمن الكامن، وميزانيات الأخطاء، واتجاهات الإشباع، والتجميعات عبر مجموعات متعددة — دون مغادرة لغة استعلام واحدة.

نموذج البيانات في فقرة واحدة

كل مقياس في Prometheus يُعرَّف باسم المقياس ومجموعة من أزواج مفتاح-قيمة تُعرف بالتسميات. تجمع الاسم والتسميات معاً يُحدد سلسلة زمنية فريدة. تُنتج تعبيرات PromQL دائماً أحد أربعة أنواع للنتيجة: متجه لحظي (عينة واحدة لكل سلسلة في لحظة معينة)، متجه نطاقي (نافذة من العينات لكل سلسلة)، عددي (رقم بسيط)، أو نصي. فهم النوع الذي تحمله يحدد العوامل التي يمكنك تطبيقها.

المحددات: تحديد السلاسل التي تريدها

يُسمّي محدد المتجه اللحظي مقياساً ويُصفّي اختيارياً بالتسميات باستخدام مطابقات الأقواس المعقوصة. أربعة عوامل متاحة:

= — مطابقة تامة
!= — مطابقة تامة سلبية
=~ — مطابقة تعبير منتظم (صياغة RE2، مثبّتة في الطرفين تلقائياً)
!~ — مطابقة تعبير منتظم سلبية

# كل عدادات طلبات HTTP لخدمة المدفوعات في بيئة الإنتاج
http_requests_total{namespace="production", service="payments"}

# كل ردود 5xx عبر جميع الخدمات (تعبير منتظم)
http_requests_total{status=~"5.."}

# كل وظيفة ما عدا المُجمِّع القديم
up{job!="legacy-scraper"}

# متجه نطاقي: نافذة 5 دقائق، لاستخدامه مع rate() لاحقاً
http_requests_total{job="api-gateway"}[5m]

اسم المقياس هو اختصار نحوي للتسمية __name__="http_requests_total". يمكنك الاستعلام عبر {__name__=~"http_.*", job="api"} لمطابقة مقاييس متعددة في آنٍ واحد — مفيد في الاتحاد وتصحيح الأخطاء.

تُركَّب محددات التسمية بدلالة AND: يجب أن تتحقق كل محدد في الأقواس. لا يوجد OR عبر مفاتيح تسمية مختلفة على مستوى المحدد — استخدم or على مستوى العامل الثنائي لذلك.

دالتا rate() و increase()

قيم العدادات الخام لا تزيد إلا؛ معدل التغيير في الثانية هو ما تريده فعلاً. كلتا rate() وincrease() تتطلبان محدد متجه نطاقي. rate() تُعيد المعدل المتوسط في الثانية عبر النافذة؛ أما increase() فتُعيد الزيادة المطلقة المُستقرأة لمدة النافذة تماماً. وهما مترابطتان: increase(m[5m]) == rate(m[5m]) * 300.

# معدل الطلبات في الثانية خلال آخر 5 دقائق
rate(http_requests_total{job="api-gateway"}[5m])

# إجمالي الطلبات المستلمة في آخر ساعة (لميزانيات SLO)
increase(http_requests_total{job="api-gateway"}[1h])

# نسبة الأخطاء — الأخطاء في الثانية مقسوماً على الإجمالي في الثانية
rate(http_requests_total{status=~"5..", job="api-gateway"}[5m])
  /
rate(http_requests_total{job="api-gateway"}[5m])

يجب أن تكون نافذة النطاق أكبر من 4 أضعاف فترة الجمع (Scrape Interval) على الأقل. مع فترة جمع 15 ثانية، استخدم [1m] كحد أدنى. النافذة الأقصر من عينتين قد تُعيد لا بيانات لأن Prometheus يحتاج عينتين على الأقل لحساب المعدل. تستخدم فرق كثيرة [5m] للوحات تشغيلية و[1h] أو [6h] لتنبيهات معدل الحرق في SLO.

استخدم irate() — المعدل اللحظي المبني على آخر عينتين فقط — حصراً عندما تحتاج رصد ارتفاعات حادة جداً. irate() صاخبة وغير مناسبة للتنبيه؛ فضّل rate() في جميع قواعد التنبيه في الإنتاج.

عوامل التجميع

يُطوّي التجميع سلاسل متعددة إلى سلاسل أقل عبر تطبيق اختزال رياضي. تقبل جميع التجميعات جملة by أو without اختيارية تتحكم في التسميات التي تبقى بعد الاختزال.

تُطوى ثلاث سلاسل خاصة بـ "api" إلى سلسلة واحدة عبر sum by (job)؛ بينما تمر سلسلة "worker" مستقلة.

أهم عوامل التجميع:

sum — الإجمالي عبر التسميات المختارة (حركة المرور، البايتات، الأعداد)
avg — المتوسط (متوسط الزمن الكامن، متوسط المعالج عبر الـ pods)
max / min — أسوأ/أفضل نسخة (مفيد للإشباع)
count — عدد السلاسل المطابقة (حجم الأسطول، عدد النسخ)
topk(n, expr) / bottomk(n, expr) — أعلى/أدنى N سلسلة
quantile(φ, expr) — النسيل التقريبي φ عبر السلاسل

# معدل الطلبات الإجمالي عبر كل الـ pods، مجمَّع حسب الخدمة
sum by (service) (
  rate(http_requests_total[5m])
)

# زمن الاستجابة عند النسيل 99 من مخطط التوزيع، لكل خدمة
histogram_quantile(
  0.99,
  sum by (service, le) (
    rate(http_request_duration_seconds_bucket[5m])
  )
)

# أعلى 5 خدمات بمعدل خطأ
topk(5,
  sum by (service) (rate(http_requests_total{status=~"5.."}[5m]))
  /
  sum by (service) (rate(http_requests_total[5m]))
)

# عدد الـ pods العاملة لكل namespace
count by (namespace) (up == 1)

استخدم دائماً sum by (...) بدلاً من sum المجردة عند تجميع المخططات التوزيعية قبل histogram_quantile(). يجب الإبقاء على تسمية le وإلا يُعيد حساب النسيل أرقاماً خاطئة بصمت. هذا أحد أكثر أخطاء PromQL شيوعاً في الإنتاج.

العمليات الثنائية والمطابقة

تدعم PromQL العمليات الحسابية (+ - * /)، والمقارنة (== != > < >= <=)، والمنطقية (and or unless) بين متجهين لحظيين. عند تطابق مجموعة التسميات في الجانبين تكون المطابقة تلقائية؛ عند الاختلاف تستخدم on(...) أو ignoring(...) لمحاذاتهما، وgroup_left / group_right للانضمامات من-واحد-إلى-كثير.

# نسبة استخدام المعالج — مقياسان يتشاركان {instance, job}
1 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m]))

# إرفاق تسمية "region" من مقياس target-info (انضمام كثير-إلى-واحد)
rate(http_requests_total[5m])
  * on(instance) group_left(region)
target_info

عوامل المقارنة تُعيد قيمة الجانب الأيسر عندما يتحقق الشرط، وتحذف السلسلة عندما لا يتحقق. هذه هي آلية عمل تعبيرات التنبيه: rate(errors[5m]) > 0.01 تُعيد فقط السلاسل التي تحرق أخطاء تتجاوز 1% حالياً.

الإزاحة والاستعلامات الفرعية

يُزيح مُعدِّل offset نافذة التقييم للخلف في الزمن. rate(metric[5m] offset 1h) يمنحك المعدل من ساعة مضت — لا غنى عنه لمقارنات الأسبوع بالأسبوع وحسابات ميزانية أخطاء SLO. أما الاستعلامات الفرعية (expr[range:step]) فتُقيّم تعبيراً غير نطاقي عبر نطاق، مما يتيح أشياء كـ max_over_time(rate(metric[5m])[1h:1m]) — أعلى معدل رُصد خلال الساعة الماضية، بأخذ عينة كل دقيقة.

انضباط الاستعلام في الإنتاج

المحددات عالية التشعب (__name__=~".*" بلا مرشحات أخرى) يمكنها إيقاع خادم Prometheus في نفاد الذاكرة. على نطاق الشركات الكبرى، تفرض الفرق هذه القواعد: أدرج دائماً محدداً بالمساواة على تسمية منخفضة التشعب كـ job، وضع --query.max-samples للتحكم في تكلفة التقييم، ووجّه الاستعلامات التاريخية الثقيلة إلى Thanos Querier أو Cortex بدلاً من Prometheus المحلي. تُحسب قواعد التسجيل مسبقاً التجميعات المكلفة لتبقى لوحات المعلومات سريعة حتى عند ملايين السلاسل.