Мониторинг через Zabbix

Zabbix может контролировать доступность узлов, ресурсы серверов, очередь SMTP и пул соединений PostgreSQL. В этой инструкции метрики приложения поступают через API Клавдия, а системные метрики — через агент Zabbix.

Перед началом

• Подготовьте сервер Zabbix и агент на одном из серверов с доступом к веб-интерфейсу Клавдия.
• Создайте отдельную учётную запись Клавдия с правами чтения состояния, метрик и узлов. См. {{ССЫЛКА:install.rbac|Правила доступа и RBAC(!)}}.
• Проверьте маршруты и ответы в {{ССЫЛКА:install.api-access|Swagger установленной версии}}.
• Подготовьте доверенный TLS-сертификат или сертификат своего центра сертификации для опроса API.
• На сервере агента должен быть установлен Python 3.

API использует cookie access_token, полученную после входа. Для регулярного сбора нельзя рассчитывать на один токен, вручную скопированный из браузера: сессия может истечь. Скрипт ниже выполняет вход при каждом опросе и передаёт cookie следующему запросу.

Подготовьте доступ к API

Создайте /etc/zabbix/klvd-api.json:

{
  "base_url": "https://klavdii.example",
  "username": "zabbix-monitor",
  "password": "<пароль учётной записи>",
  "ca_file": "/etc/zabbix/klvd-ca.pem"
}

Для публичного доверенного сертификата параметр ca_file можно удалить. Если опрашиваете узел напрямую, укажите его DNS-имя и порт, например https://node1.example:8001.

Ограничьте доступ к файлу пользователем агента; в типовой Linux-установке это zabbix:

sudo chown root:zabbix /etc/zabbix/klvd-api.json
sudo chmod 640 /etc/zabbix/klvd-api.json

Настройте получение данных

Сохраните скрипт как /usr/local/libexec/klvd-zabbix-api.py:

#!/usr/bin/env python3
import http.cookiejar
import json
import ssl
import sys
import urllib.request

ROUTES = {
    "nodes": "/api/cluster/nodes",
    "system": "/api/dashboard/system-metrics",
}

def main():
    if len(sys.argv) != 2 or sys.argv[1] not in ROUTES:
        raise ValueError("Используйте аргумент nodes или system")
    with open("/etc/zabbix/klvd-api.json", encoding="utf-8") as src:
        cfg = json.load(src)
    base = cfg["base_url"].rstrip("/")
    if not base.startswith("https://"):
        raise ValueError("base_url должен использовать HTTPS")
    context = ssl.create_default_context(cafile=cfg.get("ca_file"))
    cookies = http.cookiejar.CookieJar()
    client = urllib.request.build_opener(
        urllib.request.HTTPSHandler(context=context),
        urllib.request.HTTPCookieProcessor(cookies),
    )
    payload = json.dumps({
        "username": cfg["username"], "password": cfg["password"]
    }).encode("utf-8")
    request = urllib.request.Request(
        base + "/api/login", data=payload,
        headers={"Content-Type": "application/json"}, method="POST",
    )
    with client.open(request, timeout=10) as response:
        response.read()
    if not any(cookie.name == "access_token" for cookie in cookies):
        raise RuntimeError("API не выдал cookie access_token")
    request = urllib.request.Request(
        base + ROUTES[sys.argv[1]], headers={"Accept": "application/json"}
    )
    with client.open(request, timeout=10) as response:
        result = json.load(response)
    print(json.dumps(result, ensure_ascii=False))

if __name__ == "__main__":
    try:
        main()
    except Exception as exc:
        print("Не удалось получить метрики: " + type(exc).__name__, file=sys.stderr)
        sys.exit(1)

Скрипт не выводит пароль и cookie. Он разрешает только два заданных маршрута и проверяет сертификат сервера.

Проверьте получение обоих ответов от имени агента:

sudo -u zabbix python3 /usr/local/libexec/klvd-zabbix-api.py nodes
sudo -u zabbix python3 /usr/local/libexec/klvd-zabbix-api.py system

Добавьте файл /etc/zabbix/zabbix_agentd.d/klvd.conf или соответствующий файл в каталог дополнительных настроек Zabbix Agent 2:

UserParameter=klvd.api[*],python3 /usr/local/libexec/klvd-zabbix-api.py "$1"

Убедитесь, что каталог подключается директивой Include конфигурации агента. Для последовательного входа и запроса предусмотрите тайм-аут агента и сервера Zabbix больше их суммарного времени; в примере — до 20 секунд плюс небольшой запас, в пределах, поддерживаемых вашей версией. Перезапустите используемый агент.

Создайте элементы данных

1. В Zabbix создайте узел сети для сбора метрик Клавдия.
2. Создайте два основных элемента типа [Zabbix агент] с типом информации [Текст]: ключи klvd.api[nodes] и klvd.api[system]. Интервал опроса для начала — 60s.
3. Создайте зависимые элементы данных. Для каждого добавьте предварительную обработку [JSONPath] (!).

Показатель	Основной элемент	JSONPath	Единицы
Максимальная загрузка CPU среди узлов	klvd.api[nodes]	$.nodes[*].metrics['node_cpu|util'].max()	%
Суммарная используемая память узлов	klvd.api[nodes]	$.nodes[*].metrics['node_mem|used_kb'].sum()	КБ; для единиц B добавьте умножение на 1024
Число доступных узлов	klvd.api[nodes]	$.nodes[?(@.liveness == 'alive')].length()	узлы
Очередь SMTP	klvd.api[system]	$.smtp.queue_depth	сообщения
Активные сеансы SMTP	klvd.api[system]	$.smtp.active_sessions	сеансы
Занятые соединения PostgreSQL	klvd.api[system]	$.pg_pool.active	соединения
Максимум соединений пула	klvd.api[system]	$.pg_pool.max	соединения

Вертикальная черта в ключах метрик экранирована только для Markdown-таблицы: в Zabbix вводите обычный символ |.

Проверьте каждый путь на фактическом JSON в режиме тестирования предварительной обработки. Если поле отсутствует, выясните причину; не подменяйте отсутствие данных нулём. Для отдельных узлов настройте обнаружение по их устойчивым идентификаторам из ответа API. Номер nodes[0] не закрепляет метрику за конкретным сервером.

Для системного контроля каждого сервера подключите штатный Linux-шаблон Zabbix. Средняя нагрузка из /proc/loadavg и загрузка CPU в процентах — разные показатели; не сравнивайте их с одним порогом.

Альтернатива: HTTP-агент

Zabbix может обращаться к тем же маршрутам элементами типа [HTTP агент]. В этом случае автоматизируйте получение и обновление cookie отдельно. В запросе передавайте Cookie: access_token=<токен>, включите проверку сертификата и имени сервера. Скрипт выше решает обновление сессии в варианте с агентом.

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

Начальные условия для триггеров:

Событие	Условие
Высокая загрузка CPU	среднее значение выбранной метрики за 5 минут выше 90%
Очередь SMTP не сокращается	очередь выше согласованного порога и не снижается в течение 5 минут; 1000 — только пример порога
Кластер потерял узел	число доступных узлов меньше ожидаемого состава
Сбор метрик не работает	нет свежих данных основного элемента в течение 3 минут
Пул PostgreSQL близок к пределу	занято не менее 90% лимита в течение 5 минут

Создайте выражения в конструкторе триггеров вашей версии Zabbix. Синтаксис last(5m) > 90 не означает среднее за пять минут.

Проверьте результат

1. В [Последние данные] проверьте оба JSON-ответа и зависимые числовые показатели.
2. Сравните значения с {{ССЫЛКА:maintenance.dashboard|панелью состояния Клавдия}}.
3. В окно обслуживания проверьте недоступность одного узла и получение оповещения. После восстановления убедитесь, что событие закрывается.

{{СКРИНШОТ}}

Если данные не поступают

Проверьте журнал агента, права на файл настроек, доступ к API и доверие сертификату. Ответы 401 и 403 указывают на вход или права учётной записи; успешный ответ с ошибкой JSONPath — на несоответствие пути фактическому ответу.

Связанные материалы

• {{ССЫЛКА:install.integration-prometheus|Мониторинг через Prometheus и Grafana}}
• {{ССЫЛКА:maintenance.cluster-status|Проверка состояния узлов}}
• Документация Zabbix: JSONPath

Навигация по книге

• Следующая статья: {{ССЫЛКА:install.integration-prometheus|Мониторинг через Prometheus и Grafana}}