Навигация по циклу «Учим Zabbix не забывать историю метрик Docker Swarm»
Круг первый: боль и потерянный якорь
Круг второй: шесть попыток, один ключ ← (вы здесь)
Круг третий: разделяй и властвуй (скоро)
Чистилище (скоро)
Рай (скоро)
Ещё в самом начале сложилось понимание: хочется получать не только метрики самого контейнера (CPU, сеть и т.д.), но и знать его «положение» в Swarm — на какой ноде он работает, какой у него статус. Это намекает на логическое разделение на два канала. Я назвал их «метрический» и «оркестрационный». Начал с метрического — метрика это циферка, по ней проще понять, работает ли подход.
Спуск: канал метрический
Ситуация следующая: работает Docker-плагин Zabbix Agent 2 на условной ноде 5 возвращает сырой JSON по ключу docker.containers.discovery[false]:
{#ID}— полный Container ID.{#NAME}— имя контейнера (/cd-my-web_app.1.abc123def456ghi789jkl012mno), состоящее из:
/cd-my-web_app . 1 . abc123def456ghi789jkl012mno
└service.name┘ └slot┘ └──────── task.id ────────┘Docker-плагин Zabbix Agent 2 возвращает JSON в формате LLD (Low-Level Discovery) — это механизм Zabbix для автоматического обнаружения объектов, в нашем случае — контейнеров. Логика простая: агент отдаёт {#ID} контейнера, а прототип элемента данных по этому {#ID} идёт в Portainer и забирает статистику. Portainer умеет проксировать запросы к Docker API — ему достаточно знать ID контейнера.
Ловушка: те самые грабли
Итак, я создал первый прототип элемента данных — Memory: usage на условной ноде 5.
Циферки по Memory: usage шли прекрасно. LLD отдавал {#NAME}, Zabbix подставлял его в ключ прототипа docker.container_stats["/cd-my-web_app.1.xyz789uvw456rst123opq890"] (тоже ключ плагина, но для сбора статистики с самой ноды) — и на узле создавался полноценный элемент данных.
Ха-ха, данные собирались — до первого ребута, разумеется. Нормально же общались. "Добро пожаловать" во второй круг ада...
Начались проблемы с ключом нашего прототипа.
Будь неладен этот task.id — находясь в составе {#NAME}, он менял ключ!
Это значит, что смена task.id → новый {#NAME} → новый ключ элемента данных → Zabbix ищет этот ключ в таблице items, не находит → создаёт новый itemid. Старый itemid остаётся в базе, но перестаёт обновляться. История обрывается.
Это заставило меня копнуть в то, как Zabbix хранит метрики в своей БД. И это копание дало ключ ко всему проекту.
Вивисекция: вскрываем БД
Когда LLD обнаруживает контейнер, он формирует строку ключа из прототипа и идёт в таблицу items. Вот так она выглядит для условного сервиса cd-my-web:

Посмотрите на ключи. В каждом из них сидит abc123def456ghi789jkl012 — это task.id. Он и есть причина всех бед: при каждом ребуте Docker создаёт новую задачу, task.id меняется, а вместе с ним меняется и весь ключ.
Вот как это работает. LLD формирует строку ключа из прототипа и идёт в таблицу items:
SELECT itemid FROM items
WHERE hostid = 12345
AND key_ = 'docker.container_stats["/cd-my-web_app.1.abc123def456ghi789jkl012"]';Если запись найдена — Zabbix берёт существующий itemid и продолжает писать историю в него. Если не найдена — создаёт новую запись с новым itemid.
Но где вообще живёт сама история? К примеру, числовые метрики (целое положительное) в таблице - history_uint. Каждая запись — это одна точка на графике:
itemid | clock | value |
|---|---|---|
54321 | 1751345000 | 45 |
54321 | 1751345060 | 47 |
54321 | 1751345120 | 44 |
Все три строки привязаны к одному itemid. Это и есть история метрики — набор точек, объединённых одним идентификатором. Пока itemid не меняется — линия на графике непрерывна. Как только Zabbix создаёт новый itemid — начинается новая история, а старая остаётся в базе мёртвым грузом.
Но самое главное в этом механизме — не сама история, а то, как Zabbix находит нужный itemid. Именно это определяет, продолжится история или начнётся заново. Ключ Zabbix хранит в таблице items — сфокусируемся на ней.
А теперь представьте, что произошёл ребут. Docker создал новый task.id, скажем, xyz789uvw456rst123opq890. LLD сформировал новый ключ:
docker.container_stats["/cd-my-web_app.1.xyz789uvw456rst123opq890"]И идёт в items с этим ключом. Записи с таким ключом нет — там лежит старый. Zabbix создаёт новую запись с новым itemid. История начинается с нуля.
Совпадение ключа = доступ к существующей истории. В этом вся суть. Старый itemid остаётся в базе, но перестаёт обновляться. Новый начинает всё заново. График рвётся.
Вывод: стабильный ключ — единственный способ заставить LLD найти существующий itemid вместо создания нового. И вся работа сводится к тому, чтобы строки ключей совпадали.
Обогащение: выплавляем якорь
Как же сформировать ключ, который будет неизменный? Обратимся к атомной энергетике (шучу) - а именно к обогащению. Под обогащением я подразумеваю взять кучу сырья (всё, что вернул плагинный LLD), отсеять лишнее (убираем task.id) и сконцентрировать нужное (уникальный макрос), дабы получить уран ({#STABLE.KEY.METR}). В качестве «обогатителя урана» годится способность Zabbix к предобработке:
var lld = JSON.parse(value);
var result = [];
for (var i = 0; i < lld.length; i++) {
var item = lld[i];
var name = item['{#NAME}'];
// Получаем короткое имя ноды для тега
var hostname = item['{#NODE.HOSTNAME}'] || 'unknown';
var shortNodeName = hostname.split('.')[0];
// Реплицируемый сервис: /service.slot.taskid
var match = name.match(/^\/(.+?)\.(\d+)\.(.+)$/);
if (match) {
var serviceName = match[1];
var stackName = serviceName;
var serviceShort = serviceName;
var lastUnderscore = serviceName.lastIndexOf('_');
if (lastUnderscore > 0) {
stackName = serviceName.substring(0, lastUnderscore);
serviceShort = serviceName.substring(lastUnderscore + 1);
}
item['{#STACK.NAME}'] = stackName;
item['{#SERVICE.NAME}'] = serviceName;
item['{#SERVICE.SHORT}'] = serviceShort;
item['{#NODE.SHORT}'] = shortNodeName;
item['{#SLOT}'] = match[2];
item['{#TASK.ID}'] = match[3];
item['{#STABLE.KEY.METR}'] = serviceName + '.' + match[2];
result.push(item);
} else {
// Глобальный сервис: /service.taskid
var globalMatch = name.match(/^\/(.+?)\.(.+)$/);
if (globalMatch) {
var hostname = item['{#NODE.HOSTNAME}'] || 'unknown';
var shortName = hostname.split('.')[0];
var serviceName = globalMatch[1];
var stackName = serviceName;
var serviceShort = serviceName;
var lastUnderscore = serviceName.lastIndexOf('_');
if (lastUnderscore > 0) {
stackName = serviceName.substring(0, lastUnderscore);
serviceShort = serviceName.substring(lastUnderscore + 1);
}
item['{#STACK.NAME}'] = stackName;
item['{#SERVICE.NAME}'] = serviceName;
item['{#SERVICE.SHORT}'] = serviceShort;
item['{#NODE.SHORT}'] = shortNodeName;
item['{#SLOT}'] = 'global';
item['{#TASK.ID}'] = globalMatch[2];
item['{#STABLE.KEY.METR}'] = serviceName + '.' + shortName;
result.push(item);
}
}
}
// Возвращаем массив с обогащёнными макросами.
// {#STABLE.KEY.METR} — ключ для прототипов.
// Остальные предназначены для фильтрации, формирования тегов и использования в триггерах.
return JSON.stringify(result);Вы наверняка спросите: «Ты нормальный? Зачем так много макросов?»
А я скажу так: «Это тебе не Dark Souls... Мы в аду, сынок... Здесь всё идёт в ход. Сначала выберемся из этого дерьма, а если выживем и доберемся до Рая — я всё расскажу».
И вот у нас есть готовый {#STABLE.KEY.METR}. Для реплицируемого сервиса он состоит из двух стабильных частей: полного имени сервиса (cd-my-web_app) и слота (1).
Всё, что меняется при ребуте — task.id — в ключ не попало. Осталось только стабильное: имя сервиса и слот:
/cd-my-web_app. 1. abc123def456
└── service.name ──┘ └slot┘ └── task.id ──┘
│ │ │
│ │ └─────────────── выбрасываем
│ │
└──────────────┴────── склеиваем
│
▼
{#STABLE.KEY.METR} = cd-my-web_app.1А как же глобальные сервисы? У них нет слота (они работают на всех нодах), поэтому для них ключ формируется иначе: к имени сервиса добавляется имя ноды (node5). Это гарантирует, что Zabbix создаст отдельный элемент для каждого экземпляра на каждой ноде, и их истории не перемешаются.
Слот: разделяй и властвуй
Зачем в ключе слот? У сервиса может быть несколько реплик — app.1, app.2, app.3. Если бы ключ состоял только из имени сервиса, метрики всех реплик слились бы в один элемент данных:
container.mem.usage[cd-my-web_app] ← ключ одинаковый для всех трёх репликМы потеряли бы детализацию: не поняли бы, какая именно реплика жрёт память. Слот разводит реплики по разным элементам:
container.mem.usage[cd-my-web_app.1] ← реплика 1
container.mem.usage[cd-my-web_app.2] ← реплика 2
container.mem.usage[cd-my-web_app.3] ← реплика 3Для сервиса с одной репликой это не критично. Но если завтра реплик станет три — без слота в ключе мы получим кашу. Поэтому слот обязателен.
Глобальные сервисы: коммуналка
Отдельно пришлось предусмотреть глобальные сервисы. Они работают на каждой ноде по одному экземпляру — и у них нет слота. А раз нет слота, то и в ключе нечего разводить по репликам.
Если бы мы оставили ключ как есть — только service.name, — все экземпляры глобального сервиса получили бы одинаковый ключ:
container.mem.usage[filebeat_srv] ← ключ одинаковый для всех нодZabbix создал бы один элемент данных вместо стольких, сколько нод в кластере. Метрики со всех нод, кроме одной, потерялись бы.
Поэтому для глобальных сервисов {#STABLE.KEY.METR} формируется иначе: service.name плюс короткое имя ноды:
container.mem.usage[filebeat_srv.node5] ← нода 5
container.mem.usage[filebeat_srv.node6] ← нода 6
container.mem.usage[filebeat_srv.node7] ← нода 7Каждый экземпляр получает свой ключ. Zabbix создаёт отдельный элемент данных для каждой ноды — и история каждого экземпляра сохраняется независимо.
Отчаяние: шесть дверей
Итак.
На текущий момент наш {#STABLE.KEY.METR} — лишь гипотеза. Одно дело — придумать ключ, и совсем другое — заставить LLD создавать элементы с этим ключом, а не генерировать новые при каждом ребуте. Мне не нужен был новый элемент из прототипа — я бы хотел, чтобы метрики продолжали литься в тот же самый.
Zabbix не принимал {#STABLE.KEY.METR} напрямую — и вот почему.
Ключ элемента данных — это не просто ярлык. Это ещё и команда агенту. Когда Zabbix собирает данные, он берёт ключ и передаёт его агенту. Агент выполняет ключ и возвращает результат. То есть ключ — это не метка в базе, а инструкция: «сходи туда, сделай то, верни это».
И тут возникала проблема. Я придумал стабильный ключ, но Docker-плагин Zabbix Agent 2 не знал, что с ним делать. Ему вообще нет дела до моего {#STABLE.KEY.METR} — это закрытая система со своей жесткой логикой. Он знает только свои «плагинные» ключи (docker.containers.discovery[false], docker.container_stats[...] и т.д.)
И тут я завис. Я смотрел на этот ключ и думал: может, дело вообще не в плагине? Может, нужно стучаться не в него, а в другую точку входа?
Вся дальнейшая история сводится к одному: имея стабильный ключ, сшитый из стабильных частей serviceName + slot, заставить Zabbix принять этот ключ и продолжить писать в тот же itemid. Неважно, через агент, HTTP или что-то ещё. Главное — чтобы система приняла стабильный ключ.
Zabbix — это неприступная дверь. Ключ — в руках. Но замок не поддается — скважина слишком узкая для моего ключа. Дверь — заперта. Мы на втором круге, дно — уже рядом. Отчаянно хватаем наш {#STABLE.KEY.METR} и ломимся в эту дверь. Шесть попыток. Каждая может стать последней!
Попытка 1. Стабильный ключ в родительском элементе
Идея: Использовать {#STABLE.KEY.METR} (cd-my-web.1) напрямую в ключе прототипа:
docker.container_stats["cd-my-web_app.1"]Результат: ZBX_NOTSUPPORTED: No such container.
Причина: Плагин Docker требует полное имя контейнера (с task.id) или Container ID. Префикс service.name.slot он не принимает.
Попытка 2. Зависимые элементы
Идея: Родитель ходит к Docker по полному {#NAME} и приносит JSON. Зависимый элемент вытаскивает метрику через JSONPath, но ключ у него — стабильный {#STABLE.KEY.METR}. При ребуте родитель пересоздаётся, зависимый остаётся.
Результат: После перезапуска зависимый элемент перестаёт получать данные. Навсегда.
Причина: Зависимый элемент жёстко привязан к itemid родителя, зафиксированному при создании. Когда родитель умирает, зависимый становится сиротой — и подключиться к новому родителю уже не может.
Zabbix — он традиционный консерватор: осиротевший итем, увы, новых родителей не принимает.
Попытка 3. Прямые ключи без мастеров
Идея: Каждый прототип сам ходит к агенту, сам получает JSON и сам парсит его через Preprocessing. Без мастер-элементов.
Результат: История по-прежнему теряется при ребуте.
Причина: Ключ содержит {#NAME}, который меняется. Стабильный {#STABLE.KEY.METR} использовать в ключе нельзя — Docker API его не принимает.
Попытка 4. Подмена ID через предобработку LLD
Идея: LLD запоминает первый {#ID} и при следующих запусках подменяет новый ID на старый.
Результат: Невозможно реализовать.
Причина: JavaScript в предобработке LLD не имеет памяти между запусками. Ему доступен только текущий ответ от агента. Проще говоря: замутить движуху в предобработке без дополнительной памяти — невозможно. Отработал и забыл.
Попытка 5. HTTP Agent через Unix-сокет
Идея: Обойти плагин Docker. Пусть HTTP Agent сам ходит к Docker API через сокет:
unix:///var/run/docker.sock/containers/{#ID}/statsРезультат: Запрос не выполняется.
Причина: Zabbix HTTP Agent не поддерживает Unix-сокеты — только TCP/IP. Плюс Zabbix Server не имеет физического доступа к сокету на удалённых нодах.
(Эту галлюцинированную идею подсказал ИИ — я поплыл вместе с ним, а потом уже осознал абсурдность.)
Попытка 6. HTTP Agent через Portainer API
Идея: Раз сокет не работает — используем Portainer. У него есть API, он развёрнут, у него есть доступ к Docker API на нодах. Делаем HTTP Agent:
GET /api/endpoints/{$PORTAINER_ENDPOINT_ID}/docker/containers/{#ID}/stats Результат: 500 Unable to find the targeted agent
Причина: Portainer не знает, на какой ноде искать контейнер.
Отдельная мелочь, которая чуть не стоила ещё одной попытки. Docker API умеет отдавать статистику двумя способами: потоком (по умолчанию) и разовым снимком. Для Zabbix HTTP Agent подходит только второе — поток он не умеет читать, элемент будет висеть или получать неполный JSON. Поэтому в URL всегда добавляется ?stream=false.
Свет: заголовок-спаситель
Шестая дверь оказалась не тупиком, а окном. Не хватало одной детали — и этой деталью стал заголовок.
Portainer ответил, что не знает, на какой ноде искать. И тогда всё тот же более опытный коллега обнаружил существование X-PortainerAgent-Target. И тут всё сложилось. «Zabbix оценил упорство, система дрогнула и ответила взаимностью».
Ключ элемента данных и URL запроса — разные вещи. Они не обязаны совпадать!
Ключ содержит
{#STABLE.KEY.METR}— стабильный. По нему Zabbix находит существующийitemid.URL содержит
{#ID}— актуальный. Меняется при ребуте, но Zabbix это не волнует.Заголовок
X-PortainerAgent-Target— здесь указывается имя ноды (node5.docker.corp). Благодаря ему Portainer понимает, на какую ноду проксировать в рамках этого теста. Да, это жестко заданная нода, и при миграции контейнера история всё равно порвётся, но и это решаемо.
Момент истины
Я просто сидел в наушниках, играла TXDO - Something For You. В очередной раз нажимал «Выполнить сейчас» и обновлял страницу с «Последние данные» метрики, выжидая, когда LLD отработает.
Боже, этот момент запомнится навсегда! Я не поверил глазам, когда увидел строчку с отметкой времени и значением памяти — ведь это время было после ребута. Взрыв эмоций в моём мозгу сложно описать! Спустя пару недель отчаянных попыток я наконец увидел заветные пиксели. Волна странной эйфории от осознания хрупкости и глубины происходящего накрыла меня. Я начал всё перепроверять, а спустя минуту увидел второе значение в «Последние данные». Чёрт возьми, это, наверное, то самое, что ощущают хакеры в момент взлома.

Радовало осознание, что магия заключалась в разделении URL и ключа — и ничего ранее не мешало это сделать, я просто не пробовал. Да, это был момент истины, я сразу же убежал в курилку...

Вот так выглядит прототип сейчас — с макросом {#NODE.HOSTNAME} в заголовке. Но в момент первой победы там был захардкожен node5.example.corp. Сейчас это уже не проблема — макрос подставляет актуальную ноду динамически. Как этого добиться — в третьем круге.
Смотрим на ключ:
container.mem.usage[{#STABLE.KEY.METR}]После подстановки макроса — container.mem.usage[cd-my-web_app.1]. Без task.id. Стабильный.
Смотрим на URL:
{$PORTAINER_URL}/api/endpoints/{$PORTAINER_ENDPOINT_ID}/docker/containers/{#ID}/stats?stream=false{$PORTAINER_URL} - Адрес Portainer API — глобальный макрос
{$PORTAINER_ENDPOINT_ID} - ID окружения Docker Swarm в Portainer — глобальный макрос
{#ID} - Актуальный Container ID — LLD-макрос, меняется при ребуте
?stream=false - Отключает потоковую передачу — HTTP Agent не умеет читать поток
И наконец, заголовки:
X-API-Key - {$PORTAINER_GLOBAL_API_KEY} — ключ для аутентификации в Portainer (глобальный макрос)
X-PortainerAgent-Target - {#NODE.HOSTNAME} — нода, на которой сейчас контейнер
А вот что показала база данных:

Смотрите: все ключи — с одним и тем же стабильным cd-my-web_app.1. Никакого task.id. И это после ребута. Zabbix не создал новые элементы данных — он продолжил писать историю в существующие. itemid — те же самые.
Давайте зафиксируем логику этого механизма по шагам:
Плагин Docker делает LLD-обнаружение на ноде и находит актуальный контейнер
Предобработка формирует
{#STABLE.KEY.METR}, безжалостно отбрасывая меняющийсяtask.idВ ключ элемента данных Zabbix записывает стабильный ключ (
container.mem.usage[cd-my-web_app.1])В URL запроса к Portainer отправляется актуальный
{#ID}контейнера (тот, что вернул плагин на шаге 1)В заголовке
X-PortainerAgent-Targetуходит имя ноды ({#NODE.HOSTNAME}). Это говорит Portainer Server: «проксируй запрос не мне, а конкретной ноде, где сейчас живет контейнер»
После ребута LLD находит новый ID контейнера, подставляет его в URL, но ключ элемента остаётся прежним! Zabbix видит знакомый ключ, находит старый itemid и просто продолжает писать историю в него. Контейнер рождается заново, но для Zabbix он — тот же самый!
Именно этот паттерн — «стабильный ключ снаружи, динамический ID внутри, а адрес ноды — в динамическом заголовке» — и становится тем самым якорем, который спасает историю. Ключ держит историю, URL находит контейнер, заголовок ведёт к нужной ноде.
То что доктор прописал! Якорь надежно закреплен. История на месте.
Я не вскрывал базу данных, чтобы найти решение. Я вскрыл её после, когда решение уже работало, — чтобы удостовериться, что механизм именно такой, как я думал. Это было объяснение, а не открытие. Сначала нашёл, потом понял.
Эйфория была мощная и долгая. Но сменилась пониманием: всё это пока крутится в рамках одной ноды и подлежит масштабированию. Я снова взгрустнул...
{#STABLE.KEY.METR} отвечает за стабильность ключа, X-PortainerAgent-Target — за маршрутизацию.
А кто соберёт данные со всех нод в одном месте? Для святой троицы не хватало третьего.
Он ждал в третьем круге. Пора его вытащить...
В третьем круге мы соберем этот пазл: узнаем, как собрать все данные в одну точку, подкинем LLD синтетические макросы и вытащим последнего члена святой троицы.
Если вы пропустили начало пути, как мы искали потерянный якорь и почему Zabbix рвет графики — добро пожаловать в первый круг ада.

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