Моніторинг

Перевірки стану доступні на публічному порту, метрики Prometheus на внутрішніх. Необов’язковий стек моніторингу (Grafana, Prometheus, Alertmanager, Loki та експортери для хоста, контейнерів і доступності) запускається поруч із Railhook однією командою Compose.

Перевірки стану

RAILHOOK_URL є адресою вашого інстансу: http://localhost після типового встановлення, http://localhost:<port>, якщо ви передали --port, або https://<your domain>, якщо встановлювали з --domain.

curl -f "$RAILHOOK_URL/actuator/health/liveness"
curl -f "$RAILHOOK_URL/actuator/health/readiness"

nginx проксує лише шляхи перевірок стану. Будь-який інший шлях /actuator/ на публічному порту відповідає 404.

Метрики

Метрики доступні на портах керування (management) лише всередині мережі Docker, без облікових даних:

Сервіс	Адреса метрик
API	http://api:8082/actuator/prometheus
Воркер	http://worker:8081/actuator/prometheus

На публічний порт їх не проксовано, бо вони розкрили б назви ендпоінтів і обсяги трафіку.

Обидва сервіси публікують їх завжди, тож ці порти може опитувати будь-який наявний Prometheus: бакети затримок HTTP і лічильники прийнятих подій, створених доставок, спрацювань правил і очищення даних. Мітки обмежені: жодних ідентифікаторів організацій, проєктів чи ендпоінтів.

Вбудований стек

monitoring/ у репозиторії є другим Compose-проєктом: Grafana, Prometheus, Alertmanager, Loki і Promtail, node-exporter, cAdvisor та blackbox-exporter. Він вимкнений, доки його не запустити; ліміти пам’яті в сумі 1,5 ГБ.

Порт публікує лише Grafana, 127.0.0.1:3001. Prometheus, Alertmanager і Loki лишаються в мережі стека; сторінки Explore та Alerting у Grafana читають усі три.

На сервері, встановленому через install.sh

1. Задайте пароль Grafana. Типового пароля немає: Grafana не стартує без нього або з паролем, коротшим за 16 символів.

   cd /opt/railhook
   echo "GRAFANA_ADMIN_PASSWORD=$(openssl rand -base64 24)" >> .env

2. Вкажіть, куди йдуть сповіщення. Листи йдуть через SMTP-релей платформи (EMAIL_FROM, SMTP_*), якщо не задано ALERTMANAGER_SMTP_*. Кожен лист має посилання на Grafana на MONITORING_DOMAIN; без домену він пояснює SSH-тунель. Info-сповіщення, як-от непорожній DLQ, поштою не надсилаються: вони можуть горіти днями, тому їх показує Grafana.

   echo "ALERTMANAGER_EMAIL_TO=you@example.com" >> .env

   Slack (ALERTMANAGER_SLACK_WEBHOOK_URL), довільний вебхук (ALERTMANAGER_WEBHOOK_URL) і Telegram (ALERTMANAGER_TELEGRAM_BOT_TOKEN, ALERTMANAGER_TELEGRAM_CHAT_ID) налаштовуються так само.

3. Завантажте monitoring/ для релізу, на якому працює сервер, і запустіть стек. Це окремий Compose-проєкт railhook-monitoring, який читає .env платформи:

   v=$(grep '^API_IMAGE_TAG=' .env | cut -d= -f2)
   curl -fsSL "https://github.com/vadymkykalo/railhook/archive/refs/tags/v${v}.tar.gz" \
     | tar xz --strip-components=1 --wildcards '*/monitoring/*'
   docker compose -p railhook-monitoring --env-file .env -f monitoring/docker-compose.yml up -d

   Стек приєднується до мережі платформи: railhook_webhook-network, якщо каталог встановлення називається railhook. Для будь-якого іншого каталогу задайте в .env змінну RAILHOOK_NETWORK з назвою, яку показує docker network ls. Задайте MONITORING_NODENAME — ім’я сервера для дашборду Host.

   Після ./railhook upgrade знову завантажте monitoring/ для нового релізу й виконайте той самий up -d з --force-recreate. Контейнери монтують файли, з якими стартували, тож без цього прапорця лишаються на старих правилах і дашбордах.

4. Відкрийте Grafana через SSH-тунель і увійдіть як admin з паролем із .env:

   ssh -L 3001:127.0.0.1:3001 root@your-server

   Потім відкрийте http://localhost:3001.

Та сама команда з ps, logs -f [service] або down замість up -d показує контейнери, показує логи в реальному часі або зупиняє стек. down зберігає метрики та логи в томах railhook-monitoring_*.

Grafana на власному домені

Задайте MONITORING_DOMAIN=grafana.example.com у .env, спрямуйте це доменне ім’я на сервер і перезапишіть Caddyfile через --refresh інсталятора:

curl -fsSL https://railhook.io/install.sh | bash -s -- --refresh --dir /opt/railhook

Він додасть ім’я до Caddyfile і перезавантажить Caddy, який отримає сертифікат так само, як для платформи. ./railhook upgrade цей блок зберігає. Якщо ви встановлювали з --behind-proxy, натомість спрямуйте на 127.0.0.1:3001 власний проксі.

Обережно

Поставте перед цим іменем identity-aware проксі, наприклад Cloudflare Access, щоб вхід у Grafana не був єдиним бар’єром до ваших логів. Якщо проксі охоплює всі шляхи, виключіть /.well-known/acme-challenge/, інакше Caddy не зможе оновити сертифікат.

Cloudflare з Always Use HTTPS перенаправляє перевірку Let’s Encrypt на HTTPS, де сертифіката ще немає. Дайте Caddy готовий (наприклад, origin-сертифікат Cloudflare для цього імені): скопіюйте його й ключ у том даних Caddy, вкажіть їх у .env і знову виконайте --refresh, наведений вище:

docker exec webhook-caddy mkdir -p /data/certs
docker cp grafana.pem webhook-caddy:/data/certs/grafana.example.com.pem
docker cp grafana.key webhook-caddy:/data/certs/grafana.example.com.key
printf '%s\n' MONITORING_TLS_CERT=/data/certs/grafana.example.com.pem \
  MONITORING_TLS_KEY=/data/certs/grafana.example.com.key >> .env

З клону

1. Запустіть Railhook командою make up, потім додайте GRAFANA_ADMIN_PASSWORD до .env.

2. Запустіть стек:

   make monitoring-up

3. Відкрийте Grafana на http://localhost:3001.

make monitoring-down зупиняє стек; make monitoring-logs показує його логи в реальному часі.

Дашборди

Дашборд	Що показує
Railhook — Overview	Чи доступний публічний сайт, активні сповіщення, диск, пам’ять, CPU і вік резервної копії, далі — події, доставки, черги та DLQ
Alerts	Усі активні й очікувані сповіщення, чи працює сам ланцюжок сповіщень, історія сповіщень і посилання, щоб приглушити будь-яке з них
Errors	Рядки логів з помилками й попередженнями за сервісами, найчастіші повідомлення про помилки, 4xx і 5xx в API та nginx, 401/403/429, невдалі доставки та зростання DLQ
Logs	Рядки логів API, воркера, nginx інтерфейсу, Caddy, Postgres і резервного копіювання з фільтрами за сервісом, рівнем, текстом, correlation ID або organization ID
Host	Node Exporter Full: CPU, пам’ять, диски, мережа, файлові системи
Containers	CPU, пам’ять відносно ліміту Compose, мережа й перезапуски для кожного контейнера
Uptime	Стан перевірок, доступність за період, час відповіді, скільки днів лишилося сертифікату TLS, резервні копії
Worker & Circuit Breaker, JVM & Micrometer	Внутрішня робота платформи

Які сповіщення надсилає

Правила платформи ті самі, що в Helm-чарті. Правила сервера додатково:

Сповіщення	Спрацьовує, коли
HostDiskAlmostFull, HostDiskCritical	Файлова система заповнена більш ніж на 85% або більш ніж на 95%
HostMemoryHigh, HostOomKill	Пам’ять зайнята більш ніж на 90% протягом 10 хвилин або ядро вбило процес
HostLoadHigh	15-хвилинне навантаження перевищує кількість CPU в 1,5 раза
ContainerRestarting, ContainerOomKilled, ContainerMemoryNearLimit	Контейнер двічі перезапустився за 15 хвилин, досяг ліміту пам’яті або перевищує 90% від нього
PublicEndpointDown, PublicEndpointSlow	Публічний URL не відповідає ззовні або відповідає довше за 3 секунди
UiDown, CaddyDown	nginx інтерфейсу або Caddy перестає відповідати всередині мережі
TlsCertificateExpiringSoon, TlsCertificateExpiryImminent	Сертифікат спливає менш ніж за 14 днів або менш ніж за 3
ErrorLogSpike, EdgeServerErrorSpike	Сервіс пише в лог понад 10 помилок на хвилину або nginx віддає понад 5 відповідей 5xx на хвилину
BackupStale, BackupMissing	Найновіша планова резервна копія старша за 26 годин або її немає
Watchdog	Завжди. Надсилається лише на ALERTMANAGER_HEARTBEAT_URL

Перевірки запитують https://RAILHOOK_DOMAIN/, /docs/ і /actuator/health; щоб перевіряти інші адреси, задайте MONITORING_PROBE_URLS.

Порада

Будь-яке інше сповіщення надсилає сервер, який воно описує, тож жодне не повідомить, що цей сервер ліг. Спрямуйте ALERTMANAGER_HEARTBEAT_URL на heartbeat-сервіс, наприклад healthchecks.io: він щохвилини отримує Watchdog і сповіщає вас, коли той зникає.

Стек знаходить мережу Docker платформи за міткою Compose; якщо він вибрав не ту, задайте RAILHOOK_NETWORK. Усі змінні є в довіднику конфігурації.

На що ставити сповіщення

Метрика	Чому
delivery_oldest_pending_age_seconds	Вік найстарішої незавершеної доставки. Будь-яку проблему видно тут. forward_oldest_pending_age_seconds є вхідним відповідником
webhook_dlq_depth, incoming_forward_dlq_depth	Доставки й пересилання, у яких закінчилися повторні спроби і які потребують уваги людини
circuit_breaker_degraded_total	Redis був недоступний, і circuit breaker пропускав виклики без захисту

Kubernetes

Увімкніть інтеграції чарта з kube-prometheus-stack:

values.yaml

monitoring:
  serviceMonitor:
    enabled: true
  prometheusRule:
    enabled: true
  grafanaDashboards:
    enabled: true

ServiceMonitor збирає метрики з порту management API та воркера.