Навигация по циклу «Учим 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 отработает.

Боже, этот момент запомнится навсегда! Я не поверил глазам, когда увидел строчку с отметкой времени и значением памяти — ведь это время было после ребута. Взрыв эмоций в моём мозгу сложно описать! Спустя пару недель отчаянных попыток я наконец увидел заветные пиксели. Волна странной эйфории от осознания хрупкости и глубины происходящего накрыла меня. Я начал всё перепроверять, а спустя минуту увидел второе значение в «Последние данные». Чёрт возьми, это, наверное, то самое, что ощущают хакеры в момент взлома.

Заголовок X-PortainerAgent-Target — мост между Zabbix и Docker Swarm

Заголовок X-PortainerAgent-Target — мост между Zabbix и Docker Swarm

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

Разделение ключа и URL. Ключ привязан к стабильному {#STABLE.KEY.METR}, а URL подставляет актуальный {#ID} контейнера.

Разделение ключа и URL. Ключ привязан к стабильному {#STABLE.KEY.METR}, а URL подставляет актуальный {#ID} контейнера.

Вот так выглядит прототип сейчас — с макросом {#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 — те же самые.

Давайте зафиксируем логику этого механизма по шагам:

  1. Плагин Docker делает LLD-обнаружение на ноде и находит актуальный контейнер

  2. Предобработка формирует {#STABLE.KEY.METR}, безжалостно отбрасывая меняющийся task.id

  3. В ключ элемента данных Zabbix записывает стабильный ключ (container.mem.usage[cd-my-web_app.1])

  4. В URL запроса к Portainer отправляется актуальный {#ID} контейнера (тот, что вернул плагин на шаге 1)

  5. В заголовке X-PortainerAgent-Target уходит имя ноды ({#NODE.HOSTNAME}). Это говорит Portainer Server: «проксируй запрос не мне, а конкретной ноде, где сейчас живет контейнер»

После ребута LLD находит новый ID контейнера, подставляет его в URL, но ключ элемента остаётся прежним! Zabbix видит знакомый ключ, находит старый itemid и просто продолжает писать историю в него. Контейнер рождается заново, но для Zabbix он — тот же самый!

Именно этот паттерн — «стабильный ключ снаружи, динамический ID внутри, а адрес ноды — в динамическом заголовке» — и становится тем самым якорем, который спасает историю. Ключ держит историю, URL находит контейнер, заголовок ведёт к нужной ноде.

То что доктор прописал! Якорь надежно закреплен. История на месте.

Я не вскрывал базу данных, чтобы найти решение. Я вскрыл её после, когда решение уже работало, — чтобы удостовериться, что механизм именно такой, как я думал. Это было объяснение, а не открытие. Сначала нашёл, потом понял.

Эйфория была мощная и долгая. Но сменилась пониманием: всё это пока крутится в рамках одной ноды и подлежит масштабированию. Я снова взгрустнул...


{#STABLE.KEY.METR} отвечает за стабильность ключа, X-PortainerAgent-Target — за маршрутизацию.
А кто соберёт данные со всех нод в одном месте? Для святой троицы не хватало третьего.
Он ждал в третьем круге. Пора его вытащить...


В третьем круге мы соберем этот пазл: узнаем, как собрать все данные в одну точку, подкинем LLD синтетические макросы и вытащим последнего члена святой троицы.

Если вы пропустили начало пути, как мы искали потерянный якорь и почему Zabbix рвет графики — добро пожаловать в первый круг ада.