Мониторинг «Айвы» через Zabbix Agent

Комплект для Zabbix Server/Proxy 6.0 LTS и классического Zabbix Agent (Agent v1, zabbix_agentd.exe) под Windows. Шаблон экспортирован в формате 6.0. Agent v1 здесь означает классический агент версии 6.0, а не устаревший релиз Zabbix 1.x. Agent 2 также может выполнять этот UserParameter.

Сборщик проверен командой zabbix_agentd.exe -t quince.monitoring.get на классическом Agent 6.0.46 и Windows PowerShell 5.1 с включённой локальной авторизацией «Айвы». Структура шаблона сверена с форматом экспорта 6.0. Шаблон успешно импортирован в Zabbix 6.0 (подтверждено пользователем). Первый импорт выявил, что все uuid были не версии 4 (Invalid parameter "/1/uuid": UUIDv4 is expected); они исправлены в 1.00.067+ (версия 4 на 13-й позиции, 8/9/a/b на 17-й), формат UUID сверен скриптом.

Файлы

Схема: Zabbix Server/Proxy → Agent на компьютере «Айвы» → GET http://127.0.0.1:5000/api/monitoring/zabbix. Agent выполняет один запрос quince.monitoring.get раз в 30 секунд. Zabbix разбирает ответ на зависимые показатели и discovery каналов; отдельных процессов PowerShell для каждого канала нет.

1. Подготовить «Айву»

Установите сборку приложения с этой доработкой и перезапустите службу QuinceAudioLogger обычным способом обновления приложения. Старые сборки endpoint не содержат. Новых настроек в каналах для включения мониторинга не требуется.

На компьютере «Айвы» выполните:

Invoke-RestMethod 'http://127.0.0.1:5000/api/monitoring/zabbix' | ConvertTo-Json -Depth 8

Должны появиться schema_version: 1, generated_at (Unix-время) и массив channels, включая остановленные каналы. Пустой массив допустим, если каналы не настроены. Снимок обновляется раз в 5 секунд; в самом начале запуска возможен HTTP 503.

Если порт изменён через urls в config/settings.yaml, замените его в проверке и в quince-agent.conf. Адрес прослушивания приложения должен включать loopback: стандартный http://0.0.0.0:5000 подходит. При привязке только к конкретному LAN-адресу добавьте http://127.0.0.1:5000 через ; либо используйте стандартный адрес. Не дублируйте loopback при уже существующей привязке 0.0.0.0 на том же порту.

Адреса в urls разделяются точкой с запятой (;), а не запятой: значение передаётся в UseUrls ASP.NET Core, запятая разделителем не является. Строка urls: http://0.0.0.0:5000,http://127.0.0.1:5000 не будет разобрана как два адреса и помешает запуску службы. Для мониторинга достаточно одного urls: http://0.0.0.0:5000. Изменение urls вступает в силу только после перезапуска службы.

Endpoint доступен только через прямое loopback-соединение, независимо от авторизации веб-интерфейса. Удалённый запрос или запрос с заголовками Forwarded / X-Forwarded-* получит 403. Если перед приложением есть локальный reverse proxy, исключите /api/monitoring/zabbix из публикуемых маршрутов: прокси без forwarding-заголовков выглядит как локальный клиент. Пароль пользователя «Айвы» для Agent не нужен. URL источников, пароли и пути к папкам в JSON не передаются.

HTTP-авторизация

Авторизация «Айвы» (локальные пользователи или LDAP) не мешает сборщику: запрос к /api/monitoring/zabbix обрабатывается до проверки пользовательской сессии, но проходит собственную проверку прямого loopback-соединения. Cookie, логин и пароль не нужны; остальные API по-прежнему требуют авторизацию.

Указывайте прямой адрес приложения http://127.0.0.1:5000, а не внешний URL через IIS/nginx с Basic/Windows-аутентификацией. Если запрос всё же проходит через такую внешнюю защиту, она может вернуть 401 ещё до приложения; сборщик не передаёт учётные данные и не обходит эту защиту. Исправьте адрес на прямой loopback-порт «Айвы». Для HTTPS используйте сертификат, которому доверяет учётная запись службы Agent; отключения проверки сертификатов в сборщике нет.

2. Установить и настроить Agent

1. Скачайте официальный классический Zabbix Agent для Windows ветки 6.0, установите x64 MSI на компьютер «Айвы». Если Agent уже установлен, используйте его.
2. В PowerShell от администратора, из корня этого репозитория:

New-Item -ItemType Directory -Path 'C:\ProgramData\Zabbix\quince' -Force
Copy-Item -LiteralPath '.\zabbix\quince-monitoring.ps1' -Destination 'C:\ProgramData\Zabbix\quince\quince-monitoring.ps1'
Copy-Item -LiteralPath '.\zabbix\quince-agent.conf' -Destination 'C:\ProgramData\Zabbix\quince\quince-agent.conf'

3. В основном C:\Program Files\Zabbix Agent\zabbix_agentd.conf задайте или измените существующие параметры. Не добавляйте второе определение того же параметра. Адрес 192.0.2.10 ниже — пример, замените его IP вашего Zabbix Server или Proxy:

Server=192.0.2.10
Hostname=QUINCE-RECORDER-01
Timeout=10
Include=C:\ProgramData\Zabbix\quince\quince-agent.conf

Hostname должен совпадать с техническим именем узла в Zabbix, особенно при переходе на активные проверки. Если существующий Include уже включает этот файл, ещё один не нужен. Учётной записи службы Agent достаточно права чтения скрипта и выполнения PowerShell; доступ к аудиопапкам ей не требуется. Папки сканирует сама служба «Айвы». Каталог скрипта должен оставаться доступным для изменения только администраторам.

Для пассивных проверок разрешите TCP 10050 на этом компьютере от вашего Server/Proxy. Порт веб-интерфейса «Айвы» для мониторинга открывать не нужно. Если в вашей установке Agent используется TLS, сохраните соответствующие настройки и укажите тот же режим шифрования на узле Zabbix.

4. Проверьте сборщик и ключ Agent:

powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File 'C:\ProgramData\Zabbix\quince\quince-monitoring.ps1'
& 'C:\Program Files\Zabbix Agent\zabbix_agentd.exe' -c 'C:\Program Files\Zabbix Agent\zabbix_agentd.conf' -t quince.monitoring.get
Restart-Service -Name 'Zabbix Agent'

В первом случае ожидается JSON, во втором — результат ключа с JSON без ZBX_NOTSUPPORTED. Сборщик ограничивает HTTP-запрос пятью секундами, не использует системный HTTP-прокси и не следует перенаправлениям. Любой ответ, кроме 2xx (в том числе 302), считается ошибкой, а код состояния попадает в сообщение. Timeout=10 оставляет время на запуск PowerShell. При корпоративном запрете ExecutionPolicy Bypass подпишите скрипт по правилам организации и замените политику в quince-agent.conf.

Если Agent установлен в другой каталог, используйте фактические пути и имя службы. Для Agent 2 замените их на zabbix_agent2.conf / zabbix_agent2.exe и службу Zabbix Agent 2. Сам UserParameter остаётся тем же.

Версии PowerShell

quince-monitoring.ps1 рассчитан на Windows PowerShell 2.0, 5.1 и PowerShell 7 (Core):

• Запрос выполняется через System.Net.HttpWebRequest, а не System.Net.Http: последнего нет в .NET 2.0/3.5, на котором работает PowerShell 2.0.
• Командлета ConvertFrom-Json в PowerShell 2.0 нет. Если его нет, структура ответа проверяется через JavaScriptSerializer (System.Web.Extensions, .NET 3.5). На PowerShell 3.0+ и Core используется ConvertFrom-Json.
• В скрипте нет операторов и синтаксиса PowerShell 3.0+ (-notin, [ordered] и т. п.).
• Для PowerShell 2.0 на Windows Server 2008 R2 / Windows 7 нужен .NET Framework 3.5.1 (компонент Windows). Без него Add-Type -AssemblyName System.Web.Extensions завершится ошибкой, а сборщик вернёт код 1.
• Скрипт содержит только ASCII. Не добавляйте кириллицу без BOM: Windows PowerShell 5.1 читает такой файл в OEM-кодировке и ломает разбор строк.
• Ответ выводится в UTF-8 без BOM. Установка [Console]::OutputEncoding завёрнута в try, так как в некоторых окружениях она недоступна.

Что проверено. Windows PowerShell 5.1 и PowerShell 7.6 на реальном локальном HTTP-сервере: успешный ответ с кириллицей, некорректный JSON (нет schema_version), коды 403, 503, 302 и отказ соединения; у каждого случая код выхода 0 или 1 как ожидается. Ветка без ConvertFrom-Json (для 2.0) проверена принудительным отключением командлета в PowerShell 5.1. Настоящий PowerShell 2.0 не запускался: на тестовой машине его компонент отключён, powershell.exe -Version 2 молча запускает 5.1. Перед внедрением на компьютерах с PowerShell 2.0 выполните на них проверку из шага 4 (quince-monitoring.ps1 и zabbix_agentd.exe -t).

Агент Zabbix запускает powershell.exe без параметра -Version. На современных Windows он открывает 5.1, на старых (например, Windows 7/2008 R2 без WMF 5.1) остаётся 2.0.

3. Импортировать шаблон

1. В Zabbix откройте Настройка → Шаблоны → Импорт (в 7.0: Данные → Шаблоны → Импорт). Для Zabbix 6.0 выберите template-quince.json, для Zabbix 7.0 — template-quince-7.0.json. Файл 6.0 в Zabbix 7 и наоборот импортировать не нужно: форматы экспорта различаются (в 7.0 группы шаблонов вынесены в template_groups).
2. Создайте или откройте узел компьютера с «Айвой», добавьте интерфейс Agent с его IP и портом 10050.
3. Привяжите шаблон Quince by Zabbix agent. Если узел обслуживает Proxy, выберите его и разрешите в Server= адрес именно Proxy.
4. В Мониторинг → Последние данные выберите узел и фильтр Application: Quince. После первого успешного опроса discovery создаст показатели всех каналов; обычно нужно дождаться ещё одного опроса, чтобы они заполнились.

Проверка с Server/Proxy (если установлен zabbix_get):

zabbix_get -s <IP_КОМПЬЮТЕРА_АЙВЫ> -p 10050 -k quince.monitoring.get

Для активного режима настройте ServerActive и точный Hostname в Agent, а у единственного главного элемента quince.monitoring.get поменяйте тип на Zabbix agent (active). Discovery и зависимые элементы менять не надо. Входящее подключение к порту 10050 для активного режима не требуется.

Дашборды (только Zabbix 7.0)

Шаблон template-quince-7.0.json содержит два дашборда, каждый на одной странице. Они появляются у узла с привязанным шаблоном (Мониторинг → Узлы сети → Дашборды):

Виджет Graph prototype сам разворачивается в сетку по всем обнаруженным каналам (2×2 на страницу с переключением страниц), новый канал появляется без правки дашборда. Значения на графиках числовые, расшифровка та же, что в справочниках значений: запись — 1 работает; метаданные — 0 не указаны, 1 не поступают, 2 поступают; звук — 0 неизвестно, 1 тишина, 2 есть звук. #### «Quince: Каналы» — цветные индикаторы

Четыре виджета Honeycomb в верхней строке: «Запись», «Звук», «Метаданные», «Ошибка канала». Каждая сота — один канал, подпись — название элемента (<канал>: <показатель>), цвет — состояние. Соты во всех четырёх виджетах идут в одном порядке (по названию), поэтому один и тот же канал находится в одной позиции. Под ними — Graph prototype «Текущий объём папки» по каждому каналу (4×3 на страницу с переключением страниц).

Виджеты выбирают элементы по шаблону имени (*: Запись, *: Звук, *: Метаданные, *: Ошибка канала), поэтому новый канал появляется в них без правки дашборда. Если переименовать элементы в шаблоне, поправьте и шаблоны имён в виджетах. Строки «канал → четыре индикатора → график» в одном ряду шаблонный дашборд не поддерживает: виджеты Item value и Graph не принимают прототипы, а Honeycomb показывает по одному показателю. Для сводной таблицы по каналам используйте Data overview в обычном дашборде с фильтром по тегам Application: Quince.

Статус проверки. Дашборды и четыре графика собраны по описанию полей виджетов из API 7.0 (itemid.0, graphid.0, columns, rows, reference, для Honeycomb — items.0, show.0, primary_label, thresholds.N.*); формат структуры проверен только локально (JSON, уникальные UUIDv4, отсутствие ссылок на несуществующие элементы). Импорт в работающий Zabbix 7.0 не выполнялся. Если импорт выдаст ошибку в разделе dashboards, остальной шаблон можно использовать без дашборда (удалить раздел dashboards из файла) и сообщить текст ошибки.

Показатели каналов

Ключи имеют вид quince.channel.<поле>[<monitoring_id>]; имена и тег Channel содержат читаемое название канала, а monitoring_id используется только в ключе (тега channel_id нет).

recording использует состояние выходного процесса и успешную передачу аудиоданных ему за последние 15 секунд. Прослушивание без записи не даёт статус «запущена». Это оперативный индикатор работы кодировщика, а не проверка целостности уже записанного файла.

Метаданные считаются поступающими, если за последние 5 минут был получен непустой заголовок HLS/ICY. Повтор того же названия обновляет свежесть; ICY-блок нулевой длины после ранее полученного названия тоже подтверждает, что поток метаданных жив. Однажды обнаруженная поддержка метаданных без дальнейших ответов не считается поступлением. При остановке канала с настроенными метаданными состояние — «не поступают». Для редких ID3-метаданных текущий резервный HLS reader делает однократную пробу: без дальнейшего получения метаданных статус через 5 минут станет «не поступают».

Для звука используются свежие показания измерителя уровня (не старше 15 секунд). Если детектор тишины включён, берётся его подтверждённое состояние с настроенными порогами и задержками. Если выключен, текущий True Peak сравнивается с silence_detector.threshold_dbfs (по умолчанию −60 dBFS). До заполнения аудиобуфера или при остановке канала — «неизвестно».

Процент прогноза

forecast_bytes = оценка байт/сек × retention_days × 86400
forecast_pct   = clamp(used_bytes / forecast_bytes × 100, 0, 100)

Это тот же расчёт и ограничение 0–100%, что в карточке канала. Например, 80,53 ГБ относительно прогноза 86,90 ГБ отображаются примерно как 92,66%. Значение не является процентом заполнения всего диска; приближение к 100% при установившемся архиве нормально. Поэтому аварийный порог по нему по умолчанию не задан.

Фоновое измерение папки запускается не чаще раза в 5 минут, максимум два сканирования одновременно. Медленный диск не задерживает HTTP-ответ и не создаёт неограниченные потоки сканирования. Предыдущий результат сохраняется во время обновления, но через 10 минут считается устаревшим. Ошибка доступа или отсутствующая папка даёт disk_available=0. При большом количестве папок очередь может увеличивать интервал обновления.

При бессрочном хранении (retention_days <= 0) прогноз и процент отсутствуют (null), но размер папки остаётся доступен. Неизвестные числовые значения шаблон пропускает, не подменяя их нулём. В «Последних данных» при этом может оставаться последнее старое число — проверяйте его время и disk_available. Карточка с несохранёнными настройками может отличаться от мониторинга: мониторинг использует сохранённую конфигурацию, а измерения выполняются в другое время.

Discovery и тревоги

Discovery зависит от общего снимка. Добавление, удаление, переименование или смена типа источника обрабатываются при следующем опросе; неизменный список повторяется раз в час. В Zabbix 6.0 удалённые ресурсы сохраняются 7 дней по параметру Keep lost resources period (lifetime), затем удаляются. Отдельного немедленного отключения потерянных ресурсов в этом формате нет; условия свежести каждого канала прекращают тревоги по его старым значениям после интервала QUINCE.NODATA.

У канала появляется поле monitoring_id. Для старого YAML ID детерминированно вычисляется из имени файла без изменения файла при запуске; при сохранении он записывается в YAML. Переименование через интерфейс сохраняет ID и историю, клонирование создаёт новый. При ручном переносе/переименовании YAML сохраняйте явно записанный monitoring_id. При ручном копировании для нового канала удалите это поле: одинаковые ID останавливают обновление снимка с сообщением в журнале, чтобы два канала не смешали историю.

При значении 1 последнего макроса остановка вручную тоже вызывает тревогу. Для контроля только отдельных каналов оставьте глобальное значение 0 и добавьте на узле контекстный макрос, подставив ID из JSON:

{$QUINCE.RECORDING.REQUIRED:"0123456789abcdef0123456789abcdef"} = 1

Триггеры также отслеживают отсутствие метаданных у настроенного источника, подтверждённую тишину, ошибку движка и недоступность измерения папки. Предупреждение об объёме требует 30 неуспешных измерений Agent в окне 15 минут (при стандартном опросе 30 секунд); при изменении интервала опроса измените это условие. Окно 2m проверяет все имеющиеся в нём значения и само по себе не задаёт обязательную двухминутную задержку после появления канала. При потере общего снимка срабатывает общая тревога; устаревшие данные отдельных каналов не создают новые тревоги. Проверку свободного места самого диска добавляйте стандартным шаблоном Windows.

Диагностика

• 401 или 404: запущена старая сборка «Айвы» без endpoint либо указан другой адрес/порт. Старая сборка отвечает 401, если запрос не несёт сессии (маршрут для неё обычный /api/*), 404 возможен на других адресах.
• 403: обращение не с loopback или проходит через прокси. Agent должен находиться на том же компьютере.
• 503: первый снимок ещё не готов; проверьте журнал приложения, особенно сообщения о дублирующемся monitoring_id.
• Тайм-аут / connection refused: проверьте службу «Айвы», urls, порт и Timeout=10 Agent.
• The argument '...quince-monitoring.ps1' to the -File parameter does not exist и SyntaxError: invalid json в предобработке: на компьютере, где работает Agent, нет файла сборщика по пути из quince-agent.conf (шаг 2 не выполнен, скрипт лежит в другом каталоге или Agent запущен на другой машине, не там, где «Айва»). Agent отдаёт текст ошибки PowerShell как значение элемента, зависимые элементы не могут его разобрать. Проверьте Test-Path 'C:\ProgramData\Zabbix\quince\quince-monitoring.ps1' на этом узле и путь в UserParameter; после исправления перезапустите Agent.
• Unknown metric / Unsupported item key: проверьте Include, путь скрипта и перезапустите Agent. Не добавляйте второй такой же UserParameter.
• JSON виден локально, но не в Zabbix: проверьте интерфейс узла, Server=, firewall, назначенный Proxy, шифрование и тип главного элемента.
• Процент не появился: дождитесь фонового сканирования, проверьте срок хранения, доступность папки для учётной записи «Айвы» и disk_available.
• Время снимка устарело: проверьте журнал «Айвы» и синхронизацию часов на компьютере и Server/Proxy.

Официальная документация: установка MSI, UserParameter, зависимые элементы, импорт шаблонов.