مراقبة تطبيقات PHP باستخدام Prometheus: مكتبة promphp/prometheus_client_php

مقاييس Prometheus في PHP: دليل شامل لمكتبة promphp/prometheus_client_php

\n\n

Prometheus هو المعيار الفعلي لجمع المقاييس في البنية التحتية الحديثة لـ DevOps. إذا كان تطبيق الواجهة الخلفية الخاص بك مكتوبًا بلغة PHP، فأنت بحاجة إلى أداة يمكنها تصدير المقاييس بتنسيق يفهمه خادم Prometheus. مكتبة promphp/prometheus_client_php هي الحل الأكثر نضجًا ودعمًا لهذه المهمة. في هذه المقالة، سنشرح كيفية تثبيت المكتبة، وإنشاء مقاييس أساسية (عدادات، مدرجات تكرارية، ملخص Summary) وإخراجها في نقطة النهاية /metrics.

\n\n

ما هي promphp/prometheus_client_php؟

\n\n

هذا هو عميل PHP الرسمي لـ Prometheus، الذي طوره مجتمع promphp. تدعم المكتبة:

\n

\n
• أربعة أنواع رئيسية من المقاييس: Counter (عداد)، Gauge (مقياس)، Histogram (مدرج تكراري)، Summary (كميات مئوية).
\n
• محولات تخزين: في الذاكرة (للاختبارات)، في Redis، APCu أو نظام الملفات.
\n
• تنسيق الإخراج بتنسيق نص Prometheus (text/plain).
\n
• دعم العلامات (labels) للبيانات متعددة الأبعاد.
\n

\n\n

التثبيت

\n\n

يتم التثبيت عبر Composer. افتح الطرفية في جذر مشروعك ونفذ:

\n

composer require promphp/prometheus_client_php

\n\n

بعد التثبيت، قم بتضمين محمل Composer التلقائي في سكريبت PHP الخاص بك:

\n

require __DIR__ . '/vendor/autoload.php';

\n\n

إنشاء سجل المقاييس ومحول التخزين

\n\n

الخطوة الأولى هي إنشاء كائن Registry (سجل)، حيث سيتم تخزين جميع المقاييس، واختيار محول التخزين. للبساطة، نستخدم محول in-memory (البيانات تعيش فقط ضمن طلب واحد). للإنتاج، غالبًا ما يُستخدم Redis أو APCu.

\n\n

use Prometheus\\CollectorRegistry;\nuse Prometheus\\Storage\\InMemory;\n\n$registry = new CollectorRegistry(new InMemory());

\n\n

مثال 1: Counter — حساب عدد الطلبات

\n\n

العداد (Counter) هو قيمة تتزايد بشكل رتيب. مثالي لحساب طلبات HTTP، الأخطاء، الاستعلامات إلى قاعدة البيانات.

\n\n

// الحصول على أو إنشاء عداد\n$counter = $registry->getOrRegisterCounter(\n    'my_app',           // namespace\n    'http_requests_total', // اسم المقياس\n    'Total number of HTTP requests', // وصف help\n    ['method', 'endpoint'] // العلامات (labels)\n);\n\n// زيادة العداد بعلامات محددة\n$counter->incBy(1, ['GET', '/api/users']);

\n\n

في مخرجات /metrics سيبدو كالتالي:

\n

# HELP my_app_http_requests_total Total number of HTTP requests\n# TYPE my_app_http_requests_total counter\nmy_app_http_requests_total{method="GET",endpoint="/api/users"} 1

\n\n

مثال 2: Gauge — القيم الحالية (الذاكرة، الاتصالات)

\n\n

يمكن لـ Gauge أن يزيد أو ينقص. يُستخدم لتتبع الحالة الحالية: عدد الاتصالات النشطة، الذاكرة المستخدمة، قائمة انتظار المهام.

\n\n

use Prometheus\\Gauge;\n\n$gauge = $registry->getOrRegisterGauge(\n    'my_app',\n    'memory_usage_bytes',\n    'Current memory usage in bytes',\n    ['pool']\n);\n\n// تعيين قيمة\n$gauge->set(memory_get_usage(true), ['main']);\n// أو التغيير بالنسبة للقيمة الحالية\n$gauge->inc(1024, ['main']);   // +1KB\n$gauge->dec(512, ['main']);    // -512B

\n\n

مثال 3: Histogram — توزيع القيم (وقت الاستجابة)

\n\n

يقوم المدرج التكراري بتجميع الملاحظات في سلال (buckets) محددة. مناسب جدًا لقياس وقت تنفيذ الطلبات أو حجم الاستجابات.

\n\n

use Prometheus\\Histogram;\n\n$histogram = $registry->getOrRegisterHistogram(\n    'my_app',\n    'http_request_duration_seconds',\n    'Duration of HTTP requests in seconds',\n    ['method', 'endpoint'],\n    [0.1, 0.5, 1.0, 2.0, 5.0] // bucke