لماذا تيليجرام وليس البريد الإلكتروني؟

تعاني تنبيهات البريد الإلكتروني من مشكلة أساسية: لا أحد يقرأها في الوقت الفعلي. سيتم إغراق رسالة التنبيه عبر البريد الإلكتروني في الساعة 3 صباحًا في تدفق اليوم التالي. يهتز تنبيه Telegram في جيب DBA عند الطلب - ويمتد زمن الوصول بين الحادث ورد الفعل من ساعات إلى ثوانٍ.

يستخدم PmaControl Telegram كقناة التنبيه الأساسية الخاصة به. إنها ليست أداة: إنها خيار تقني. روبوتات Telegram مجانية، وAPI بسيط، وتدعم الرسائل Markdown، وتسمح المجموعات بتوجيه التنبيهات حسب الخطورة.

إنشاء بوت تيليجرام

الخطوة 1: تواصل مع @BotFather

افتح Telegram وابحث عن @BotFather. هذا هو روبوت Telegram الرسمي لإنشاء روبوتات أخرى.

Vous : /newbot
BotFather : Alright, a new bot. How are we going to call it?
Vous : PmaControl Alerts
BotFather : Good. Now let's choose a username for your bot.
Vous : pmacontrol_alerts_bot
BotFather : Done! [...] Use this token to access the HTTP API:
            7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

احتفظ بهذا الرمز — إنه مفتاح API الخاص ببرنامج الروبوت الخاص بك. لا تضعه في مستودع Git، ولا تشاركه بشكل واضح.

الخطوة الثانية: احصل على معرف الدردشة

يحتاج الروبوت إلى معرفة من يرسل الرسائل إليه. لمجموعة:

قم بإنشاء مجموعة Telegram (على سبيل المثال: "PmaControl - تنبيهات الإنتاج")
أضف الروبوت الخاص بك إلى المجموعة
أرسل رسالة في المجموعة
اتصل بـ API getUpdates:

curl -s "https://api.telegram.org/bot7123456789:AAHxxxx/getUpdates" | python3 -m json.tool

في الرد، ابحث عن chat_id للمجموعة (وهو سلبي بالنسبة للمجموعات):

{
    "result": [{
        "message": {
            "chat": {
                "id": -1001234567890,
                "title": "PmaControl - Alertes Production",
                "type": "supergroup"
            }
        }
    }]
}
`

chat_idهو-1001234567890`.

الخطوة 3: الاختبار

curl -s -X POST "https://api.telegram.org/bot7123456789:AAHxxxx/sendMessage" \
  -d chat_id=-1001234567890 \
  -d parse_mode=Markdown \
  -d text="*Test* : PmaControl alert system is working."

إذا ظهرت الرسالة في المجموعة، فهذا يعني أن التكوين يعمل.

تكوين PmaControl

ملف التكوين

يمكن العثور على تكوين Telegram لـ PmaControl في:

/srv/www/pmacontrol/configuration/telegram.php

<?php
// configuration/telegram.php

define('TELEGRAM_TOKEN', '7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
define('TELEGRAM_CHAT_ID', '-1001234567890');

// Optional: separate channels by severity
define('TELEGRAM_CHAT_ID_CRITICAL', '-1001234567891');
define('TELEGRAM_CHAT_ID_WARNING', '-1001234567890');
define('TELEGRAM_CHAT_ID_INFO', '-1001234567892');

هام: يحتوي هذا الملف على سر (الرمز المميز). تطبيق الأذونات المناسبة:

chmod 640 /srv/www/pmacontrol/configuration/telegram.php
chown root:www-data /srv/www/pmacontrol/configuration/telegram.php

أنواع التنبيهات

يرسل PmaControl أربعة أنواع من التنبيهات، كل منها بمستوى خطورة:

معلومات

تُعلم التنبيهات الإعلامية بالأحداث العادية ولكن البارزة:

ℹ️ Info — PmaControl
Server: db-prod-01 (10.0.1.1:3306)
Event: Service restarted
Version: MariaDB 10.11.6
Uptime: 0 days 0 hours 2 minutes
Time: 2026-04-13 14:32:15

أمثلة على أحداث المعلومات:

إعادة تشغيل خدمة MariaDB / MySQL
تم الكشف عن تغيير الإصدار
تمت إضافة خادم جديد للمراقبة
اكتمل تصدير المخطط

تحذير

تشير التحذيرات إلى المواقف التي يجب الانتباه إليها:

⚠️ Warning — PmaControl
Server: db-prod-slave-01 (10.0.1.2:3306)
Event: Replication lag exceeds threshold
Lag: 120 seconds (threshold: 60s)
Status: IO=Yes, SQL=Yes
Duration: 5 minutes
Time: 2026-04-13 14:32:15

أمثلة على أحداث التحذير:

تأخر النسخ المتماثل > العتبة القابلة للتكوين
مساحة القرص < 20%
عدد الاتصالات > 80% من الحد الأقصى
تزايد الاستعلامات البطيئة

التحسين

يتم إنشاء اقتراحات التحسين بواسطة Marina+ أو القواعد الداخلية:

💡 Improvement — PmaControl
Server: db-prod-01 (10.0.1.1:3306)
Suggestion: Missing index detected
Query: SELECT * FROM orders WHERE customer_id = ?
Rows examined/sent ratio: 450:1
Recommended: ALTER TABLE orders ADD INDEX idx_customer_id (customer_id)

الإجراء مطلوب

تتطلب التنبيهات الحرجة التدخل الفوري:

🔴 Action Required — PmaControl
Server: db-prod-slave-01 (10.0.1.2:3306)
Event: Replication stopped
Slave_IO_Running: No
Slave_SQL_Running: No
Last_SQL_Error: Error 'Duplicate entry' on table 'users'
Time: 2026-04-13 14:32:15
Link: https://pmacontrol.example.com/fr/slave/show/42/

أمثلة على الأحداث المطلوبة:

توقف النسخ المتماثل (IO أو SQL Thread)
الخادم غير قابل للوصول (فشل اتصال SSH أو MySQL)
تم اكتشاف قاتل OOM في السجلات
مساحة القرص < 5% (حرجة)
خطأ اتصال مستمر (> 3 محاولات)

RBAC: المسار حسب الخطورة

في مرحلة الإنتاج، لا تشتمل جميع التنبيهات على نفس الجمهور. PmaControl يدعم توجيه الخطورة إلى مجموعات Telegram المختلفة.

الهندسة المعمارية الموصى بها

Groupe "PmaControl - Critical"    ← Action Required uniquement
  Membres : DBA astreinte, lead tech, SRE

Groupe "PmaControl - Operations"  ← Warning + Action Required
  Membres : équipe DBA, SRE

Groupe "PmaControl - All"         ← Info + Warning + Improvement + Action Required
  Membres : équipe élargie, développeurs principaux

يثبت

// configuration/telegram.php

// Groupe principal (tous les niveaux)
define('TELEGRAM_CHAT_ID', '-1001234567890');

// Groupes par sévérité
define('TELEGRAM_CHAT_ID_CRITICAL', '-1001234567891');  // Action Required
define('TELEGRAM_CHAT_ID_WARNING',  '-1001234567890');  // Warning
define('TELEGRAM_CHAT_ID_INFO',     '-1001234567892');  // Info + Improvement

// Activer le routage par sévérité
define('TELEGRAM_ROUTE_BY_SEVERITY', true);

عندما يكون TELEGRAM_ROUTE_BY_SEVERITY هو true، يتم إرسال كل تنبيه فقط إلى المجموعة المقابلة لخطورته. تحصل المجموعة الرئيسية (TELEGRAM_CHAT_ID) على نسخة من كل شيء.

أحداث التنبيه

إعادة تشغيل الخدمة

يكتشف PmaControl عمليات إعادة التشغيل عبر المتغير Uptime. إذا انتقل وقت التشغيل من X ساعة إلى بضع دقائق بين مجموعتين، فهذا يعد إعادة تشغيل:

if ($current_uptime < $previous_uptime) {
    Telegram::sendInfo(
        "Service restarted",
        $server,
        "Previous uptime: " . formatDuration($previous_uptime) .
        "\nCurrent uptime: " . formatDuration($current_uptime)
    );
}

تأخر النسخ

تتم مراقبة التأخر بشكل مستمر. يتم تشغيل التنبيه عندما يتجاوز الفارق الحد لمدة قابلة للتكوين (وليست ذروة معزولة):

// Alerte seulement si le lag est > seuil depuis 5 minutes
if ($lag > $threshold && $lag_duration > 300) {
    Telegram::sendWarning(
        "Replication lag exceeds threshold",
        $server,
        "Lag: {$lag}s (threshold: {$threshold}s)\n" .
        "Duration: " . formatDuration($lag_duration)
    );
}

مساحة القرص

PmaControl يجمع استخدام القرص عبر SSH. العتبات:

تحذير: < 20% مجاني
الحرجة: < 5% مجانًا

🔴 Action Required — PmaControl
Server: db-prod-01 (10.0.1.1:3306)
Event: Disk space critical
Partition: /var/lib/mysql
Usage: 96% (used 458GB / 480GB)
Free: 22GB

أوم القاتل

يقوم PmaControl بتحليل سجل النظام وdmesg لاكتشاف أحداث OOM:

🔴 Action Required — PmaControl
Server: db-prod-01 (10.0.1.1:3306)
Event: OOM Killer invoked
Process killed: mysqld (PID 1234)
Memory at kill: RSS 14.2GB, limit 16GB
Time: 2026-04-13 03:42:15

الاتصال

إذا لم يتمكن PmaControl من الاتصال بالخادم (تم رفض مهلة SSH أو تم رفض اتصال MySQL):

🔴 Action Required — PmaControl
Server: db-prod-03 (10.0.1.3:3306)
Event: Connection failed
Error: SSH timeout after 30s
Attempts: 3/3 failed
Last successful: 2026-04-13 14:25:00 (7 min ago)

يتم إرسال التنبيه فقط بعد 3 محاولات فاشلة لتجنب النتائج الإيجابية الخاطئة لوجود خلل في الشبكة.

إرسال تقارير مخصصة

يمكن لوكلاء PmaControl إرسال رسائل بتنسيق Markdown:

// Rapport hebdomadaire
$report = "*Weekly Report — PmaControl*\n\n";
$report .= "📊 *Servers monitored*: 142\n";
$report .= "✅ *Healthy*: 138\n";
$report .= "⚠️ *Warnings*: 3\n";
$report .= "🔴 *Critical*: 1\n\n";
$report .= "*Top issues this week:*\n";
$report .= "1. db-prod-slave-03: lag spike (max 340s) — resolved\n";
$report .= "2. db-staging-01: disk 87% — cleanup scheduled\n";
$report .= "3. db-prod-02: 12 slow queries > 10s — indexes added\n";

Telegram::send($report, TELEGRAM_CHAT_ID, 'Markdown');

يدعم تنسيق Telegram Markdown:

غامق: *texte*
مائل: _texte_
Code inline: `نص`
كتل التعليمات البرمجية:


``

texte

الروابط: [texte](url)

التكامل مع وكيل Relem

Relem هو وكيل تحسين MariaDB / MySQL خارجي. وعندما يتم دمجه مع PmaControl، يتم إرسال توصياته عبر Telegram:

💡 Improvement — Releem via PmaControl
Server: db-prod-01 (10.0.1.1:3306)
Recommendation: Increase innodb_buffer_pool_size
Current: 4GB
Recommended: 8GB
Reason: Buffer pool hit ratio 91.2% (target: >99%)
Impact: Estimated 15% improvement in read performance

يتم التكامل على مستوى المستمع: عندما يرسل Releem توصية عبر API، يقوم PmaControl بمعالجتها وتوجيهها إلى Telegram بالتنسيق القياسي.

أفضل الممارسات

1. لا تغرق المجموعات

تكوين عتبات واقعية. سيتم تجاهل مجموعة Telegram التي تتلقى 50 تنبيهًا يوميًا. الهدف:

الحرجة: 0-2 رسائل في الأسبوع (الحالة المثالية 0)
تحذير: 5-10 رسائل يوميًا كحد أقصى
المعلومات: في مجموعة منفصلة يشاهدها الأشخاص عند الطلب

2. قم بتضمين روابط الإجراءات

يجب أن يحتوي كل تنبيه على رابط مباشر إلى صفحة PmaControl المقابلة. ينقر DBA عند الطلب ويصل مباشرة إلى لوحة التحكم الخاصة بالخادم الذي به مشكلة.

3. أضف السياق

"تأخر النسخ المتماثل: 120 ثانية" أقل فائدة من "تأخر النسخ المتماثل: 120 ثانية (كان 5 ثوانٍ قبل ساعة، العتبة: 60 ثانية، التنبيه الثالث هذا الأسبوع)". السياق يساعد في تحديد الأولويات.

4. اختبر الروبوت بانتظام

أرسل رسالة اختبار يومية ("PmaControl نبضات القلب: جميع الأنظمة قيد التشغيل"). إذا لم تعد الرسالة تصل، فأنت تعلم أن الروبوت معطل قبل وقوع حادث حقيقي.

# Cron quotidien de heartbeat
0 8 * * * curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -d chat_id=$CHAT_ID \
  -d text="PmaControl heartbeat: $(date) — all systems operational"

5. حماية الرمز المميز

لا تلزمه أبدًا بـ Git
قم بتخزينه في ملف تكوين بأذونات مقيدة
استخدام مدير سري في الإنتاج
إلغاء الرمز المميز وإعادة إنشائه في حالة اختراقه (/revoke على @BotFather)

6. تكوين إشعارات الهاتف المحمول

يتيح لك Telegram تكوين الإشعارات حسب المجموعة:

حرجة: تمكين الإشعارات، تمكين الصوت، مرئي دائمًا
العمليات: تمكين الإخطارات، تعطيل الصوت
الكل: تم تعطيل الإشعارات (التشاور عند الطلب)

استكشاف الأخطاء وإصلاحها

البوت لا يرسل رسائل

تحقق من الرمز المميز: curl "https://api.telegram.org/bot$TOKEN/getMe"
تحقق من معرف الدردشة: curl "https://api.telegram.org/bot$TOKEN/getUpdates"
التحقق من أن الروبوت عضو في المجموعة
تحقق من أذونات الملف telegram.php
تحقق من سجلات PHP بحثًا عن أخطاء الاتصال

رسائل مكررة

إذا وصل كل تنبيه بشكل مكرر، فتأكد من تكوين TELEGRAM_ROUTE_BY_SEVERITY بشكل صحيح. وبدون التوجيه، ينتقل التنبيه إلى المجموعة الافتراضية. مع التوجيه، فإنه يذهب إلى مجموعة محددة. إذا كان كلاهما نفس المجموعة، تصل الرسالة مرتين.

تحديد المعدل

API حدود Telegram هي 30 رسالة في الثانية لكل روبوت. إذا قام PmaControl بمراقبة 200 خادم وجميعهم يواجهون مشكلة متزامنة، فيمكن التحكم في الرسائل. الحل: تجميع التنبيهات على دفعات:

🔴 Action Required — PmaControl (batch)
Multiple servers affected:
- db-prod-01: Connection failed
- db-prod-02: Connection failed
- db-prod-03: Connection failed
Possible cause: Network outage in DC-1

الخلاصة

Telegram هي قناة التنبيه المثالية لـ PmaControl: الوقت الفعلي، الجوال، تنسيق Markdown، المجموعات حسب الخطورة. التكوين بسيط (10 دقائق) والنتيجة فورية: يتم اكتشاف حوادث MariaDB / MySQL والإخطار بها في الوقت الفعلي، مع السياق اللازم للتصرف.

الفخ الكلاسيكي هو الإفراط في التنبيه. يعد غرق مجموعة Telegram في الإشعارات أسوأ من عدم وجود تنبيهات على الإطلاق - حيث يقوم الأشخاص بكتمها. قم بمعايرة الحدود وفصل درجات الخطورة واختبار عمل الروبوت بانتظام.

قم بتوصيل Telegram بـ PmaControl: تنبيهات في الوقت الفعلي