PmaControl logo PmaControl
← Вернуться в блог

Подключение Telegram к PmaControl: алерты в реальном времени

Автор Aurélien LEQUOY
pmacontrol telegram alerting notifications automation
Поделиться X LinkedIn Facebook Email PDF
Подключение Telegram к PmaControl: алерты в реальном времени

Почему Telegram, а не email?

Оповещения по email имеют фундаментальную проблему: никто не читает их в реальном времени. Email-оповещение в 3 часа ночи утонет в потоке следующего дня. Оповещение Telegram вибрирует в кармане дежурного DBA — задержка между инцидентом и реакцией сокращается с часов до секунд.

PmaControl использует Telegram как основной канал оповещений. Это не игрушка: это технический выбор. Боты Telegram бесплатны, API прост, сообщения поддерживают Markdown, а группы позволяют маршрутизировать оповещения по уровню серьёзности.

Создание бота Telegram

Шаг 1: Обратиться к @BotFather

Откройте Telegram и найдите @BotFather. Это официальный бот Telegram для создания других ботов.

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

Сохраните этот токен — это API-ключ вашего бота. Не коммитьте его в Git-репозиторий, не передавайте в открытом виде.

Шаг 2: Получить chat_id

Бот должен знать, кому отправлять сообщения. Для группы:

  1. Создайте группу Telegram (например: «PmaControl - Alertes Production»)
  2. Добавьте бота в группу
  3. Отправьте сообщение в группу
  4. Вызовите 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

Информационные оповещения уведомляют о нормальных, но примечательных событиях:

ℹ️ 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

Примеры Info-событий:

  • Перезапуск сервиса MariaDB / MySQL
  • Обнаружена смена версии
  • Новый сервер добавлен в мониторинг
  • Экспорт схемы завершён

Warning

Предупреждения сигнализируют о ситуациях, требующих наблюдения:

⚠️ 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

Примеры Warning-событий:

  • Лаг репликации > настраиваемого порога
  • Дисковое пространство < 20%
  • Количество соединений > 80% от максимума
  • Рост числа медленных запросов

Improvement

Предложения по улучшению генерируются 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

Критические оповещения требуют немедленного вмешательства:

🔴 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/

Примеры Action Required-событий:

  • Репликация остановлена (IO или SQL поток)
  • Сервер недоступен (SSH или MySQL-подключение неудачно)
  • OOM killer обнаружен в логах
  • Дисковое пространство < 5% (критическое)
  • Постоянная ошибка подключения (>3 попыток)

RBAC: маршрутизация по серьёзности

В продакшне не все оповещения предназначены для одной аудитории. PmaControl поддерживает маршрутизацию по серьёзности в разные группы Telegram.

Рекомендуемая архитектура

Группа "PmaControl - Critical"    ← только Action Required
  Участники: дежурный DBA, ведущий технический специалист, SRE

Группа "PmaControl - Operations"  ← Warning + Action Required
  Участники: команда DBA, SRE

Группа "PmaControl - All"         ← Info + Warning + Improvement + Action Required
  Участники: расширенная команда, ключевые разработчики

Конфигурация

// configuration/telegram.php

// Основная группа (все уровни)
define('TELEGRAM_CHAT_ID', '-1001234567890');

// Группы по серьёзности
define('TELEGRAM_CHAT_ID_CRITICAL', '-1001234567891');  // Action Required
define('TELEGRAM_CHAT_ID_WARNING',  '-1001234567890');  // Warning
define('TELEGRAM_CHAT_ID_INFO',     '-1001234567892');  // Info + Improvement

// Включить маршрутизацию по серьёзности
define('TELEGRAM_ROUTE_BY_SEVERITY', true);

Когда TELEGRAM_ROUTE_BY_SEVERITY равно true, каждое оповещение отправляется только в группу, соответствующую его серьёзности. Основная группа (TELEGRAM_CHAT_ID) получает копию всего.

События оповещений

Перезапуск сервиса

PmaControl обнаруживает перезапуски через переменную Uptime. Если uptime падает с X часов до нескольких минут между двумя сборами — это перезапуск:

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

Лаг репликации

Лаг мониторится непрерывно. Оповещение срабатывает, когда лаг превышает порог в течение настраиваемого времени (не единичный всплеск):

// Оповещение только если лаг > порога в течение 5 минут
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. Пороги:

  • Warning: < 20% свободно
  • Critical: < 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

OOM Killer

PmaControl анализирует syslog и 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 connection refused):

🔴 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-сообщения:

// Еженедельный отчёт
$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');

Markdown-формат Telegram поддерживает:

  • Жирный: *текст*
  • Курсив: _текст_
  • Код inline: `текст`
  • Блоки кода: ```текст```
  • Ссылки: [текст](url)

Интеграция с агентом Releem

Releem — внешний агент оптимизации 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

Интеграция осуществляется на уровне Listener: когда Releem отправляет рекомендацию через API, PmaControl обрабатывает её и маршрутизирует в Telegram в стандартном формате.

Лучшие практики

1. Не засорять группы

Настройте реалистичные пороги. Группа Telegram, получающая 50 оповещений в день, будет игнорироваться. Целевые показатели:

  • Critical: 0-2 сообщения в неделю (в идеале 0)
  • Warning: максимум 5-10 сообщений в день
  • Info: в отдельной группе, которую просматривают по запросу

2. Включать ссылки на действия

Каждое оповещение должно содержать прямую ссылку на соответствующую страницу PmaControl. Дежурный DBA кликает и попадает прямо на дашборд проблемного сервера.

3. Добавлять контекст

«Replication lag: 120s» менее полезно, чем «Replication lag: 120s (was 5s an hour ago, threshold: 60s, 3rd alert this week)». Контекст помогает приоритизировать.

4. Тестировать бота регулярно

Отправляйте ежедневное тестовое сообщение («PmaControl heartbeat: all systems operational»). Если сообщение перестаёт приходить, вы узнаете о поломке бота ДО реального инцидента.

# Ежедневный heartbeat через cron
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 позволяет настраивать уведомления по группам:

  • Critical: уведомления включены, звук включён, всегда видимо
  • Operations: уведомления включены, звук выключен
  • All: уведомления выключены (просмотр по запросу)

Устранение неполадок

Бот не отправляет сообщения

  1. Проверить токен: curl "https://api.telegram.org/bot$TOKEN/getMe"
  2. Проверить chat_id: curl "https://api.telegram.org/bot$TOKEN/getUpdates"
  3. Проверить, что бот является участником группы
  4. Проверить права файла telegram.php
  5. Проверить PHP-логи на ошибки подключения

Дублирование сообщений

Если каждое оповещение приходит дважды, проверьте правильность конфигурации TELEGRAM_ROUTE_BY_SEVERITY. Без маршрутизации оповещение идёт в группу по умолчанию. С маршрутизацией — в специализированную группу. Если обе — одна и та же группа, сообщение приходит дважды.

Rate limiting

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, засыпанная уведомлениями, хуже, чем отсутствие оповещений вовсе — люди ставят её на беззвучный режим. Калибруйте пороги, разделяйте серьёзности и регулярно тестируйте работоспособность бота.

Поделиться X LinkedIn Facebook Email PDF
← Вернуться в блог

Комментарии (0)

Комментариев пока нет.

Оставить комментарий