Мониторинг и аларми за OpenClaw: Prometheus + Grafana

01Какво ще научиш

• Кои сигнали си струва да следиш при OpenClaw и защо „процесът върви“ не значи „асистентът работи“.
• Как да четеш официалните проби /healthz и /readyz с blackbox_exporter.
• Как да включиш официалния плъгин за метрики и да го четеш със защитен достъп.
• Как да подредиш Prometheus, Alertmanager, node_exporter и blackbox_exporter като услуги, които слушат само на твоята машина.
• Как да нарисуваш табло в Grafana: проби, закъснение на модела, натоварване.
• Как да получаваш аларми в Discord без тайни в конфигурацията и как да ги изпробваш безопасно.

02Преди да започнеш

• Минал си Обучение 3: OpenClaw 🔒 локално върви като услуга в Ubuntu на WSL2 (със systemd), а Ollama 🔒 локално отговаря.
• Docker — само за Grafana. Ако ползваш Docker Desktop, за мрежа „host“ трябва версия 4.34+ и включена опция „Enable host networking“; Docker Engine, инсталиран направо в Ubuntu, не иска настройка.
• Discord канал с webhook за известията 🌐 глобален. Адресът на webhook е като парола — не го пишем в команди, чат или Git.
• Права sudo в Ubuntu и достъп до токена на Gateway — същия, който ползват операторските клиенти (виж „Източници“ за правата).
• Портът на Gateway е по подразбиране 18789; ако си го сменил, замени го навсякъде по-долу.

03Стъпки

1. Какво следим и с какво

   Първо избираме източника на всеки сигнал. Защо: най-простото е най-малко крехко — не пишем свой сървър там, където има готов инструмент. Прочетохме страниците на OpenClaw за здраве и за Prometheus: здравни адреси и плъгин за метрики съществуват, затова blackbox_exporter чете пробите, а метриките идват от плъгина.

   Какво	Откъде идва сигналът	Как
   OpenClaw е жив	/healthz	blackbox HTTP проба
   OpenClaw е готов (агенти, Discord)	/readyz	blackbox HTTP проба
   Заявки към модела, опашки, памет на процеса	плъгин diagnostics-prometheus	Prometheus чете защитен маршрут
   Ollama отговаря	/api/tags на Ollama	blackbox HTTP проба
   Памет и процесор на WSL2	node_exporter	готов инструмент

   Веригата: източници → Prometheus (пита ги на 15–30 секунди) → Grafana (таблата) и Alertmanager (известията в Discord).

   ℹ️

   Ollama: проба, не заявка за генериране

   Старият урок пращаше текст към модела на всеки 15 секунди. Така той се товари в паметта и натоварва видеокартата само за да се измери. Пробата към /api/tags показва, че услугата отговаря и колко бързо, но не измерва скорост на генериране. Истинското закъснение на заявките виждаш в метриките на плъгина.
   🖥️

   node_exporter в WSL2

   Той вижда виртуалната машина на WSL2, не целия Windows. „Паметта е 85%“ означава паметта на WSL2, а тя има собствен лимит.

2. Здравните проби на OpenClaw

   Gateway дава три двойки адреси без вход (GET/HEAD). Различават се по това какво казват:

   Адрес	Значи	За какво е
   /healthz (и /health)	HTTP сървърът е жив	Жив ли е процесът; решение за рестарт
   /startupz (и /startup)	Стартирането е приключило и не се изключва	Следене на старта
   /readyz (и /ready)	Готов е: агентните бази са приети, а настроените канали минават дълбока проверка	Може ли да приема работа

   Защо ни трябва /readyz: според документацията счупен канал (например Telegram) може да върне там 503, докато /startupz остава „started“. Затова процес, който „върви“, но не може да вземе съобщение от Discord, се вижда само на /readyz. Отдалечените извиквания без вход получават само ok и status — подробности за кои части не работят виждат локалните или удостоверените.

   Опитай от Ubuntu (портът е по подразбиране):

   bashкопирай

   for p in healthz startupz readyz; do
     printf '%s ' "$p"
     curl -s -o /dev/null -w '%{http_code}\n' "http://localhost:18789/$p"
   done

   Очакваш три пъти 200. Ако /readyz дава 503, виж openclaw channels status и openclaw logs --follow.

3. Метрики: официалният плъгин за Prometheus

   Плъгинът diagnostics-prometheus слага на Gateway маршрут GET /api/diagnostics/prometheus в стандартния текстов формат. Инсталира се и се включва така; маршрутът се регистрира при старт, затова следва рестарт:

   bashкопирай

   openclaw plugins install clawhub:@openclaw/diagnostics-prometheus
   openclaw plugins enable diagnostics-prometheus
   openclaw gateway restart
   openclaw plugins list --enabled

   ⚠️

   Ако вече имаш plugins.allow

   Документацията показва настройка със списък plugins.allow. Ако твоят вече съдържа други плъгини, добави този към него, не го замествай — иначе другите ще спрат.

   Маршрутът е защитен: иска същия достъп като операторските клиенти (право operator.read). Документацията изрично предупреждава да не се публикува като открит /metrics. Без вход получаваш 401 — това е очакваното. Проверка с токена на Gateway (въведи го скрито, както токена на Discord в Обучение 3):

   bashкопирай

   read -rs OPENCLAW_GATEWAY_TOKEN; export OPENCLAW_GATEWAY_TOKEN
   curl -s -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
     http://localhost:18789/api/diagnostics/prometheus | head -n 20

   Празен отговор значи, че още няма събития — прати съобщение на бота и опитай пак (броячите се появяват след първо събитие). За Prometheus сложи същия токен като един ред във файл само за потребителя на мониторинга (потребителят monitoring се създава в следващата стъпка):

   bashкопирай

   sudo mkdir -p /etc/prometheus
   sudo touch /etc/prometheus/openclaw-gateway-token
   sudo chmod 600 /etc/prometheus/openclaw-gateway-token
   sudoedit /etc/prometheus/openclaw-gateway-token     # залепи токена, един ред

   Какво получаваш (по документацията): заявки и времена на RPC към Gateway, брой и продължителност на заявките към модела по доставчик и модел, използвани токени, опашки, „заседнали“ сесии, закъснение на цикъла на събитията и памет на процеса. Текстове на съобщения, отговори, пътища и тайни не излизат в метриките. Стойностите са в паметта: след рестарт на Gateway броячите започват от нула — затова ползваме rate() и increase().

   ℹ️

   А OpenTelemetry?

   OpenClaw може и да праща метрики, следи и дневници към колектор (плъгин diagnostics-otel). Тук ползваме „дърпащия“ модел на Prometheus — по-прост, без допълнителен колектор и само метрики. Виж „Източници“.

4. Инсталиране на Prometheus, Alertmanager и двата exporter-а

   Един и същ шаблон: архив, двоични файлове, systemd услуга, отделен потребител без вход. Защо: ако някой счупи уеб страницата на Grafana или exporter, не получава права над твоите файлове. Архивите са за linux-amd64 (обикновен компютър с Windows; за ARM вземи arm64).

   bash · в Ubuntu (WSL2)копирай

   sudo useradd --system --no-create-home --shell /usr/sbin/nologin monitoring
   sudo mkdir -p /etc/prometheus /var/lib/prometheus /etc/alertmanager /var/lib/alertmanager /etc/blackbox
   cd /tmp
   wget https://github.com/prometheus/node_exporter/releases/download/v1.12.1/node_exporter-1.12.1.linux-amd64.tar.gz
   wget https://github.com/prometheus/blackbox_exporter/releases/download/v0.28.0/blackbox_exporter-0.28.0.linux-amd64.tar.gz
   wget https://github.com/prometheus/prometheus/releases/download/v3.15.0/prometheus-3.15.0.linux-amd64.tar.gz
   wget https://github.com/prometheus/alertmanager/releases/download/v0.34.1/alertmanager-0.34.1.linux-amd64.tar.gz
   tar xzf node_exporter-1.12.1.linux-amd64.tar.gz
   tar xzf blackbox_exporter-0.28.0.linux-amd64.tar.gz
   tar xzf prometheus-3.15.0.linux-amd64.tar.gz
   tar xzf alertmanager-0.34.1.linux-amd64.tar.gz
   sudo cp node_exporter-1.12.1.linux-amd64/node_exporter /usr/local/bin/
   sudo cp blackbox_exporter-0.28.0.linux-amd64/blackbox_exporter /usr/local/bin/
   sudo cp blackbox_exporter-0.28.0.linux-amd64/blackbox.yml /etc/blackbox/
   sudo cp prometheus-3.15.0.linux-amd64/{prometheus,promtool} /usr/local/bin/
   sudo cp alertmanager-0.34.1.linux-amd64/{alertmanager,amtool} /usr/local/bin/
   sudo chown -R monitoring: /var/lib/prometheus /var/lib/alertmanager
   sudo chown monitoring: /etc/prometheus/openclaw-gateway-token

   Файлът blackbox.yml от архива вече съдържа модул http_2xx, който ни трябва. Ето четирите услуги. Забележи localhost във всяка: всичко слуша само на твоята машина, в същия дух като Обучение 3.

   ini · /etc/systemd/system/ (всяка услуга в свой файл)копирай

   # node_exporter.service
   [Unit]
   Description=Node Exporter
   After=network-online.target
   [Service]
   User=monitoring
   ExecStart=/usr/local/bin/node_exporter --web.listen-address=localhost:9100
   Restart=on-failure
   [Install]
   WantedBy=multi-user.target
   
   # blackbox_exporter.service
   [Unit]
   Description=Blackbox Exporter
   After=network-online.target
   [Service]
   User=monitoring
   ExecStart=/usr/local/bin/blackbox_exporter --config.file=/etc/blackbox/blackbox.yml --web.listen-address=localhost:9115
   Restart=on-failure
   [Install]
   WantedBy=multi-user.target
   
   # prometheus.service
   [Unit]
   Description=Prometheus
   After=network-online.target
   [Service]
   User=monitoring
   ExecStart=/usr/local/bin/prometheus --config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/var/lib/prometheus --web.listen-address=localhost:9090
   Restart=on-failure
   [Install]
   WantedBy=multi-user.target
   
   # alertmanager.service
   [Unit]
   Description=Alertmanager
   After=network-online.target
   [Service]
   User=monitoring
   ExecStart=/usr/local/bin/alertmanager --config.file=/etc/alertmanager/alertmanager.yml --storage.path=/var/lib/alertmanager --web.listen-address=localhost:9093 --cluster.listen-address=
   Restart=on-failure
   [Install]
   WantedBy=multi-user.target

   --cluster.listen-address= (празно) изключва клъстерния режим на Alertmanager — не ни трябва за една машина. Услугите стартираме чак в стъпка 7, когато конфигурациите са готови.

5. Prometheus: кого питаме

   Три задачи: node (машината), openclaw (метриките, със защитен достъп) и openclaw_probe (пробите през blackbox). Редът alerting е онова, което свързва Prometheus с Alertmanager — без него правилата се оценяват, но известие не тръгва.

   yaml · /etc/prometheus/prometheus.ymlкопирай

   global:
     scrape_interval: 15s
     evaluation_interval: 15s
   alerting:
     alertmanagers:
       - static_configs:
           - targets: ['localhost:9093']
   rule_files:
     - /etc/prometheus/alerts.yml
   scrape_configs:
     - job_name: node
       static_configs:
         - targets: ['localhost:9100']
     - job_name: openclaw
       scrape_interval: 30s
       metrics_path: /api/diagnostics/prometheus
       authorization:
         credentials_file: /etc/prometheus/openclaw-gateway-token
       static_configs:
         - targets: ['localhost:18789']
     - job_name: openclaw_probe
       metrics_path: /probe
       params:
         module: [http_2xx]
       static_configs:
         - targets:
             - http://localhost:18789/healthz
             - http://localhost:18789/readyz
             - http://localhost:11434/api/tags      # Ollama: само „отговаря ли“
       relabel_configs:
         - source_labels: [__address__]
           target_label: __param_target
         - source_labels: [__param_target]
           target_label: instance
         - target_label: __address__
           replacement: localhost:9115

   Трите relabel_configs са стандартният трик на blackbox: адресът, който искаш да провериш, става параметър target, а Prometheus всъщност пита exporter-а на 9115. authorization с credentials_file праща токена като Bearer — Prometheus го чете от файла, не от конфигурацията.

6. Правила за аларми

   Правилата казват кога е „лошо“. Всяко има for — докато състоянието не се задържи толкова време, няма известие. Защо: кратък срив при рестарт не бива да буди никого.

   yaml · /etc/prometheus/alerts.ymlкопирай

   groups:
     - name: openclaw
       rules:
         - alert: TargetDown
           expr: up == 0
           for: 1m
           labels: {severity: critical}
           annotations:
             summary: "Не отговаря: {{ $labels.job }}"
         - alert: GatewayNotLive
           expr: probe_success{job="openclaw_probe", instance=~".*/healthz"} == 0
           for: 1m
           labels: {severity: critical}
           annotations:
             summary: "Gateway не отговаря на /healthz"
         - alert: GatewayNotReady
           expr: probe_success{job="openclaw_probe", instance=~".*/readyz"} == 0
           for: 2m
           labels: {severity: warning}
           annotations:
             summary: "Gateway работи, но /readyz връща грешка (канал или агент не са готови)"
         - alert: OllamaNotResponding
           expr: probe_success{job="openclaw_probe", instance=~".*/api/tags"} == 0
           for: 2m
           labels: {severity: critical}
           annotations:
             summary: "Ollama не отговаря"
         - alert: ModelCallsSlow
           expr: |
             histogram_quantile(0.95,
               sum by (le, provider, model) (rate(openclaw_model_call_duration_seconds_bucket[10m]))
             ) > 30
           for: 10m
           labels: {severity: warning}
           annotations:
             summary: "95-и персентил на заявките към модела над 30 s ({{ $labels.model }})"
         - alert: MemoryHigh
           expr: (1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100 > 85
           for: 5m
           labels: {severity: warning}
           annotations:
             summary: "Заета памет във WSL2: {{ $value | printf \"%.0f\" }} %"

   • GatewayNotLive — процесът не отговаря; GatewayNotReady — отговаря, но не може да работи (например счупен Discord канал). Две различни аларми, защото изискват различно действие.
   • ModelCallsSlow ползва хистограмата на плъгина за заявките към модела; 30 s е пример — виж какво е нормално при теб и го поправи.
   • Текстовете в известията са кратки и без съдържание на съобщения: само име на услуга и състояние.

7. Discord известия през Alertmanager и старт на всичко

   Alertmanager има вградена поддръжка за Discord (discord_configs). Адресът на webhook го пазим в отделен файл и конфигурацията само сочи към него (webhook_url_file):

   bashкопирай

   sudo touch /etc/alertmanager/discord_webhook
   sudo chown monitoring: /etc/alertmanager/discord_webhook
   sudo chmod 600 /etc/alertmanager/discord_webhook
   sudoedit /etc/alertmanager/discord_webhook     # залепи адреса на webhook, един ред

   yaml · /etc/alertmanager/alertmanager.ymlкопирай

   route:
     receiver: discord
     group_by: ['alertname']
     group_wait: 10s
     group_interval: 5m
     repeat_interval: 1h
   receivers:
     - name: discord
       discord_configs:
         - webhook_url_file: /etc/alertmanager/discord_webhook
           send_resolved: true

   send_resolved: true праща и съобщение „оправено“, когато алармата угасне. Интервалите са примерни. Преди старт провери синтаксиса — така хващаш грешка в отстъпа, преди да е спряла услугата:

   bashкопирай

   promtool check config /etc/prometheus/prometheus.yml
   promtool check rules /etc/prometheus/alerts.yml
   amtool check-config /etc/alertmanager/alertmanager.yml
   sudo systemctl daemon-reload
   sudo systemctl enable --now node_exporter blackbox_exporter prometheus alertmanager

   Отвори в браузъра на Windows адреса на Prometheus (localhost, порт 9090) и страницата Status → Targets (/targets): всяка задача трябва да е UP. Ако openclaw е „401“, токенът във файла е грешен; ако е празно, плъгинът още не е включен или няма събития.

8. Grafana: таблото

   Grafana вдига таблата. Образът е grafana/grafana (старият grafana-oss вече не се обновява). Пускаме го с --network=host, за да вижда Prometheus на localhost — вътре в контейнера localhost иначе е самият контейнер. Данните са в именуван том, а GF_SERVER_HTTP_ADDR го държи на loopback.

   bashкопирай

   docker run -d --name=grafana --network=host \
     -e GF_SERVER_HTTP_ADDR=127.0.0.1 \
     -v grafana-data:/var/lib/grafana \
     grafana/grafana:13.2.3

   • Отвори http://localhost:3000. Първият вход е със стандартните данни на Grafana; тя веднага иска нова парола — задай я и я запиши в мениджър на пароли.
   • Добави източник на данни: Connections → Data sources → Add → Prometheus, адрес http://localhost:9090, запази. ⚠️ Менюто на Grafana 13 не е проверявано на живо — ако имената се различават, виж документацията ѝ.
   • Dashboards → New → Import, ID 1860 („Node Exporter Full“) — готово табло за паметта и процесора на WSL2.
   • Направи свое табло „OpenClaw“ с панелите от таблицата по-долу. Запази го и като JSON (Export) — ще го възстановиш бързо след преинсталиране.

   Панел	Заявка (PromQL)
   Жив / готов / Ollama (Stat, 1 = да)	probe_success{job="openclaw_probe"}
   Време на отговор на пробите	probe_duration_seconds{job="openclaw_probe"}
   Заявки към Gateway в секунда	sum by (method) (rate(openclaw_gateway_rpc_requests_total[5m]))
   Заявки към модела — 95-и персентил	histogram_quantile(0.95, sum by (le, provider, model) (rate(openclaw_model_call_duration_seconds_bucket[10m])))
   Памет на процеса на OpenClaw	openclaw_memory_bytes{kind="rss"}
   Сигнал за препълнени серии (трябва да е 0)	increase(openclaw_prometheus_series_dropped_total[15m])
   Активни аларми	ALERTS{alertstate="firing"}

   ⚠️

   Мрежа „host“ и Docker Desktop

   Документацията на Docker: мрежата „host“ в Docker Desktop е от версия 4.34 и иска включена опция (Settings → Resources → Network → Enable host networking). Не сме го пускали с WSL интеграцията. Ако не върви, инсталирай Docker Engine направо в Ubuntu или публикувай порта като -p 127.0.0.1:3000:3000 и сочи източника към адреса на Prometheus, достижим от контейнера.

9. Изпробвай алармата — без да чупиш нищо

   Без тест аларма не е аларма. Най-безопасният начин не е да спираш услуги, а да добавиш временно правило, което винаги гори. Добави в alerts.yml, в списъка rules на групата:

   yaml · временнокопирай

         - alert: ProbnaAlarma
           expr: vector(1)
           for: 0m
           labels: {severity: info}
           annotations:
             summary: "Пробна аларма: Alertmanager и Discord работят"

   Рестартирай Prometheus и почакай минута-две:

   bashкопирай

   promtool check rules /etc/prometheus/alerts.yml
   sudo systemctl restart prometheus

   Очакваш: алармата във /alerts в Prometheus и съобщение в Discord. После махни правилото, пусни пак check rules и рестартирай — след малко идва съобщение „resolved“. Ако нищо не дойде: провери реда alerting в prometheus.yml, правата на файла с webhook (sudo -u monitoring cat … трябва да успее) и journalctl -u alertmanager.

   После направи и истинска проверка: рестартирай Gateway с openclaw gateway restart и виж в Prometheus, че пробите може за кратко да паднат и да се върнат, без да тръгне аларма (защото for е по-дълго от рестарта). ⚠️ Колко трае рестартът при теб — не сме го мерили.

04Проверка

Чеклист

• /healthz и /readyz връщат 200 от Ubuntu.
• Плъгинът е включен и маршрутът за метрики отговаря с токен, а без токен връща 401.
• promtool и amtool не дават грешки; всички задачи в /targets са UP.
• Prometheus, Alertmanager, exporter-ите и Grafana слушат само на localhost.
• Токенът на Gateway и адресът на webhook са във файлове с права 600, не в Git, чат или споделени архиви.
• Пробната аларма стигна до Discord и „resolved“ дойде след махането ѝ; временното правило е изтрито.
• В Grafana виждаш проби, закъснение на модела, заявки към Gateway и памет.
• Известията не съдържат имена, текстове на съобщения или лични данни.

Тест

05Какво следва

Близки уроци: Блок 9 · Наблюдаемост на AI в production (следи и метрики за модели) и Мониторинг на Raspberry Pi 5 (същите инструменти за малка система).

06Източници

1. OpenClaw: проверки на здравето 🔒 локално — HTTP пробите /healthz, /startupz, /readyz; команди health и status.
2. OpenClaw: метрики за Prometheus — плъгин diagnostics-prometheus, маршрут, вход, списък на метриките, рецепти.
3. OpenClaw: износ към OpenTelemetry — алтернативата с „изпращане“ (следи, дневници).
4. OpenClaw: права на операторите · сигурност.
5. Prometheus: конфигурация — scrape_config, authorization, relabel_configs; Alertmanager: конфигурация — discord_config, webhook_url_file.
6. blackbox_exporter (0.28.0) · node_exporter (1.12.1) · Alertmanager (0.34.1) · Prometheus (3.15.0) — версии и архиви.
7. Grafana в Docker 🔒 локално · табло 1860 „Node Exporter Full“.
8. Docker: мрежа „host“ — Docker Desktop 4.34+ и включена опция.
9. OpenClaw: Ollama като доставчик 🔒 локално.