2. Предобработка значений элементов данных

Обзор

Предварительная обработка позволяет применять преобразования к полученным значениям элементов данных перед сохранением их в базе данных. Эти преобразования/шаги предобработки выполняются Zabbix сервером или прокси (если элементы данных отслеживаются через прокси).

Этот функционал поддерживает множество вариантов использования, таких как:

• преобразование байтов в биты (например, умножая значения сетевого трафика на «8»);
• расчёт посекундной статистики постепенно возрастающих значений;
• применение регулярных выражений для извлечения или изменения значений;
• выполнение пользовательских скриптов для обработки значений;
• отбрасывание неизменившихся значений для оптимизации хранения базы данных.

Для элемента данных можно настроить один или несколько шагов предварительной обработки. Эти шаги выполняются в том порядке, в котором они настроены.

Все значения, передаваемые в предварительную обработку, изначально рассматриваются как строки. Преобразование в требуемый тип значения (как определено в конфигурации элемента данных) выполняется в конце конвейера предобработки. Однако, определённые шаги предварительной обработки могут инициировать более ранние преобразования, если это необходимо. Подробную техническую информацию смотрите в разделе Подробности предварительной обработки.

Чтобы убедиться, что ваша конфигурация предварительной обработки работает так, как ожидается, можно её протестировать.

Смотрите также: Примеры предварительной обработки

Настройка

Шаги предварительной обработки задаются на вкладке Предварительная обработка формы настройки элемента данных.

Нажмите Добавить, чтобы выбрать поддерживаемое преобразование.

Поле Тип информации отображается в нижней части вкладки, если задан хотя бы один шаг предварительной обработки. При необходимости тип информации можно изменить, не покидая вкладку Предварительная обработка. Подробное описание параметров см. в разделе Создание элемента данных.

Поддерживаемые преобразования

Ниже перечислены все поддерживаемые преобразования.
Нажмите имя преобразования, чтобы просмотреть подробную информацию о нем.

Если для выбранного преобразования включен флажок Пользовательское действие при ошибке, его можно установить и указать пользовательские параметры обработки ошибок: Отбросить значение (отбросить значение), Установить значение (установить указанное значение) или Установить ошибку (установить указанное сообщение об ошибке).
Если шаг предварительной обработки завершается ошибкой, элемент данных не перейдет в состояние «не поддерживается», если выбран параметр Отбросить значение или Установить значение.

Обратите внимание, что для шагов предварительной обработки Изменение и Ограничение частоты Zabbix должен запоминать последнее значение, чтобы при необходимости вычислять или сравнивать новое значение.
Эти предыдущие значения обрабатываются менеджером предварительной обработки.
Если сервер Zabbix или прокси перезапущены либо в шаги предварительной обработки внесены изменения, последнее значение соответствующего элемента данных сбрасывается, что приводит к следующему:

• для шагов Простое изменение и Изменение в секунду следующее значение будет проигнорировано, поскольку отсутствует предыдущее значение, относительно которого можно вычислить изменение;
• для шагов Отбрасывать неизменившиеся и Отбрасывать неизменившиеся с контрольным сигналом следующее значение никогда не будет отброшено, даже если согласно правилам отбрасывания оно должно было быть отброшено.

Регулярное выражение

Сопоставьте значение с регулярным выражением и замените его требуемым результатом.

Параметры:

• pattern - регулярное выражение;
  
• output - шаблон форматирования результата. Экранирующая последовательность \N (где N=1…9) заменяется на N-ю совпавшую группу. Экранирующая последовательность \0 заменяется на совпавший текст.

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

• Если входное значение не соответствует регулярному выражению, элемент данных станет неподдерживаемым;
  
• Регулярное выражение поддерживает извлечение максимум 10 захваченных групп с помощью последовательности \N;
  
• Дополнительные примеры приведены в разделе регулярные выражения.

Замена (Replace)

Найти искомую строку и заменить её на другую (или на пустую строку).

Параметры:

• строка поиска (search string) — строка для поиска и замены, с учётом регистра (обязательно);
  
• замена (replacement) — строка для замены строки поиска. Строка замены также может быть пустой, что позволяет эффективно удалять строку поиска при ее обнаружении.

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

• Будут заменены все вхождения строки поиска;
• Можно использовать управляющие последовательности для поиска или замены переводов строк, возврата каретки, табуляции и пробелов «\n \r \t \s»; обратную косую черту можно экранировать как «\\», а управляющие последовательности можно экранировать как «\\n»;
• Экранирование переводов строк, возвратов каретки и табуляций выполняется автоматически при низкоуровневом обнаружении.

Обрезать (Trim)

Удалить указанные символы с начала и конца значения.

Обрезать справа (Right trim)

Удалить указанные символы с конца значения.

Обрезать слева (Left trim)

Удалить указанные символы с начала значения.

XML XPath

Извлечение значения или фрагмента из данных XML с помощью функциональности XPath.

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

• Для работы этого параметра сервер Zabbix (или прокси Zabbix) должен быть скомпилирован с поддержкой libxml;
  
• Пространства имен не поддерживаются.

Примеры:

number(/document/item/value) #извлечет «10» из <document><item><value>10</value></item></document>
number(/document/item/@attribute) #извлечет «10» из <document><item attribute="10"></item></document>
/document/item #извлечет «<item><value>10</value></item>» из <document><item><value>10</value></item></document>

JSONPath

Извлечение значения или фрагмента из данных JSON с использованием функциональности JSONPath.

CSV в JSON

Преобразует данные CSV-файла в формат JSON.

Дополнительную информацию см. в разделе: Предобработка CSV в JSON.

XML в JSON

Преобразование данных из формата XML в JSON.

Дополнительную информацию см. в разделе: Правила сериализации.

Значение SNMP walk

Извлечение значения по указанному имени OID/MIB и применение параметров форматирования:

• Без изменений - возврат hex-строки в виде экранированной hex-строки (обратите внимание, что подсказки отображения по-прежнему применяются);
  
• UTF-8 из hex-STRING - преобразование hex-строки в строку UTF-8;
  
• MAC из hex-STRING - проверка hex-строки как MAC-адреса и возврат корректной строки MAC-адреса (где ' ' заменяются на ':');
  
• Целое число из BITS - преобразование первых 8 байт битовой строки, представленной в виде последовательности шестнадцатеричных символов (например, "1A 2B 3C 4D"), в 64-битное беззнаковое целое число. В битовых строках длиной более 8 байт последующие байты игнорируются.

Преобразование SNMP walk в JSON

Преобразование значений SNMP в JSON.

Укажите имя поля в JSON и соответствующий путь к SNMP OID. Значения полей будут заполнены значениями из указанного пути к SNMP OID.

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

• Доступны аналогичные параметры форматирования значений, что и на шаге Значение SNMP walk;
  
• Этот шаг предварительной обработки можно использовать для обнаружения SNMP OID.

Получение значения SNMP

Применение параметров форматирования к значению, полученному по SNMP:

• UTF-8 из Hex-STRING — преобразовать шестнадцатеричную строку в строку UTF-8;
  
• MAC из Hex-STRING — проверить шестнадцатеричную строку как MAC-адрес и вернуть корректную строку MAC-адреса (где ' ' заменяются на ':');
  
• Целое число из BITS — преобразовать первые 8 байт битовой строки, представленной в виде последовательности шестнадцатеричных символов (например, "1A 2B 3C 4D"), в 64-битное беззнаковое целое число. В битовых строках длиной более 8 байт последующие байты игнорируются.

Пользовательский множитель

Умножает значение на указанное целое число или число с плавающей точкой.

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

• Используйте этот параметр для преобразования значений, полученных в КБ, МБ/с и т. д., в Б, Б/с. В противном случае Zabbix не сможет корректно установить префиксы (К, М, Г и т. д.).
  
• Обратите внимание: если тип информации элемента данных — Числовой (без знака), входящие значения с дробной частью будут усечены (то есть «0.9» превратится в «0») до применения пользовательского множителя;
  
• Если вы используете пользовательский множитель или сохраняете значение как Изменение в секунду для элементов данных с типом информации Числовой (без знака), а результирующее вычисленное значение фактически является числом с плавающей точкой, оно всё равно принимается как корректное: десятичная часть отбрасывается, а значение сохраняется как целое число;
  
• Поддерживаются: экспоненциальная запись, например 1e+70; пользовательские макросы и макросы LLD; строки, содержащие макросы, например {#MACRO}e+10, {$MACRO1}e+{$MACRO2}. Макросы должны разрешаться в целое число или число с плавающей точкой.

Простое изменение

Вычисляет разницу между текущим и предыдущим значением.

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

• Этот шаг может быть полезен для измерения постоянно увеличивающегося значения;
  
• Вычисляется как value-prev_value, где value — текущее значение; prev_value — ранее полученное значение;
  
• Для одного элемента данных допускается только одна операция изменения («Простое изменение» или «Изменение в секунду»);
• Если текущее значение меньше предыдущего, Zabbix отбрасывает эту разницу (ничего не сохраняет) и ожидает следующее значение.

Изменение в секунду

Рассчитать скорость изменения значения (разницу между текущим и предыдущим значением) в секунду.

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

• Этот шаг полезен для расчета скорости в секунду для постоянно увеличивающегося значения;
  
• Поскольку в результате этого расчета могут получаться числа с плавающей запятой, рекомендуется установить для параметра «Тип информации» значение Числовой (с плавающей запятой), даже если исходные входящие значения являются целыми числами. Это особенно важно для небольших чисел, где имеет значение десятичная часть. Если значения с плавающей запятой являются большими и могут превысить длину поля float, в результате чего может быть потеряно все значение, рекомендуется использовать Числовой (без знака) и таким образом отбрасывать только десятичную часть;
  
• Вычисляется как (value-prev_value)/(time-prev_time), где value — текущее значение; prev_value — ранее полученное значение; time — текущая временная метка; prev_time — временная метка предыдущего значения;
  
• Для одного элемента данных разрешена только одна операция изменения («Простое изменение» или «Изменение в секунду»);
• Если текущее значение меньше предыдущего, Zabbix отбрасывает эту разницу (ничего не сохраняет) и ожидает следующее значение. Это помогает корректно работать, например, с переполнением 32-разрядных счетчиков SNMP.

Логическое значение в десятичное

Преобразование значения из логического формата в десятичный.

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

• Текстовое представление преобразуется в 0 или 1. Таким образом, «TRUE» сохраняется как 1, а «FALSE» — как 0. Все значения сопоставляются без учета регистра. В настоящее время распознаются следующие значения: для TRUE — true, t, yes, y, on, up, running, enabled, available, ok, master; для FALSE — false, f, no, n, off, down, unused, disabled, unavailable, err, slave. Кроме того, любое ненулевое числовое значение считается значением TRUE, а нулевое — значением FALSE.

Из восьмеричной системы в десятичную

Преобразует значение из восьмеричного формата в десятичный.

Преобразование шестнадцатеричного числа в десятичное

Преобразует значение из шестнадцатеричного формата в десятичный.

JavaScript

Введите код JavaScript в модальном редакторе, который открывается при нажатии на поле параметра или на значок карандаша рядом с ним.

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

• Доступная длина JavaScript зависит от используемой базы данных;
  
• Для получения дополнительной информации смотрите: Предобработка Javascript.

В диапазоне

Определите диапазон, в котором должно находиться значение, указав минимальное и максимальное значения (включительно).

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

• Допускаются числовые значения (любое количество цифр, необязательная десятичная и экспоненциальная части, отрицательные значения);
  
• Минимальное значение должно быть меньше максимального;
  
• Должно существовать хотя бы одно значение;
  
• Можно использовать пользовательские макросы и макросы низкоуровневого обнаружения.

Соответствует регулярному выражению

Укажите регулярное выражение, которому должно соответствовать значение.

Не соответствует регулярному выражению

Укажите регулярное выражение, которому значение не должно соответствовать.

Проверка наличия ошибки в JSON

Проверка сообщения об ошибке на уровне приложения, расположенного по JSONPath. Прекратить обработку, если проверка выполнена успешно и сообщение не пустое; в противном случае продолжить обработку со значением, которое было до этого шага предварительной обработки.

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

• Эти ошибки внешней службы отображаются пользователю как есть, без добавления информации о шаге предварительной обработки;
  
• Ошибка не будет отображаться в случае сбоя при разборе некорректного JSON.

Проверка наличия ошибки в XML

Проверка сообщения об ошибке на уровне приложения, расположенного по адресу XPath.
Прекратить обработку, если проверка выполнена успешно и сообщение не пусто; в противном случае продолжить обработку со значением, которое было до этого шага предварительной обработки.

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

• Эти ошибки внешней службы отображаются пользователю без изменений, без добавления информации о шаге предварительной обработки;
  
• Ошибка не будет отображаться в случае сбоя при разборе некорректного XML.

Проверка ошибки с помощью регулярного выражения

Проверка сообщения об ошибке на уровне приложения с помощью регулярного выражения.
Прекратить обработку, если проверка выполнена успешно и сообщение не пустое; в противном случае продолжить обработку со значением, которое было до этого шага предварительной обработки.

Параметры:

• pattern - регулярное выражение;
  
• output - шаблон форматирования вывода.
  Экранирующая последовательность \N (где N=1…9) заменяется на N-ю найденную группу.
  Экранирующая последовательность \0 заменяется на найденный текст.

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

• Эти ошибки внешней службы сообщаются пользователю как есть, без добавления информации о шаге предварительной обработки.

Проверка неподдерживаемого значения

Проверка того, удалось ли получить значение элемента данных. Укажите, как следует обрабатывать ошибку, на основе анализа возвращенного сообщения об ошибке.

Параметры:

• scope - выберите область обработки ошибки:
  any error - любая ошибка;
  error matches - только ошибка, соответствующая регулярному выражению, указанному в поле pattern;
  error does not match - только ошибка, не соответствующая регулярному выражению, указанному в поле pattern
  
• pattern - регулярное выражение для сопоставления с ошибкой. Если в параметре области выбрано значение any error, это поле не отображается. Если поле отображается, оно является обязательным.
  

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

• Обычно отсутствие значения или невозможность его получить приводит к тому, что элемент данных становится неподдерживаемым. Этот шаг предварительной обработки позволяет изменить такое поведение.
• Этот шаг предварительной обработки проверяет только невозможность получить значение элемента данных. Он не проверяет, например, соответствует ли тип полученного значения (например, строка) типу информации элемента данных (например, числовой); подробную информацию см. в разделе Примеры предварительной обработки. При несовпадении типов элемент данных все еще может стать неподдерживаемым после выполнения всех шагов предварительной обработки. Для проверки несовпадения типов можно, например, использовать шаг предварительной обработки Custom multiplier; см. Примеры предварительной обработки.
• Захват групп регулярного выражения поддерживается в полях Set value to или Set error to. Используйте \N (где N=1…9), чтобы получить N-ю совпавшую группу; используйте \0, чтобы получить совпавший текст;
• Эти шаги всегда выполняются первыми и после сохранения изменений элемента данных размещаются над всеми остальными шагами предварительной обработки;
• Поддерживается несколько шагов Check for not supported value в указанном порядке. Шаг для any error автоматически размещается последним шагом в этой группе.

Отбрасывать не изменившееся (Discard unchanged)

Отбросить значение, если оно не изменилось.

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

• Если значение отбрасывается, оно не сохраняется в базе данных и Zabbix сервер не будет знать, что значение было получено. Выражения триггеров не будут пересчитываться, в результате не будут созданы/закрыты проблемы по связанным триггерам. Функции триггеров будут работать только на основе данных, которые фактически сохраняются в базу данных. Поскольку динамика изменений строится на основе данных в базе данных, если в течение часа не сохраняются значения, то для этого часа также не будет данных динамики изменений.
  
• Для элемента данных можно указать только один параметр троттлинга.

Отбрасывать неизменившиеся значения с периодической передачей

Отбрасывать значение, если оно не изменилось в течение заданного периода времени (в секундах).

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

• Для указания количества секунд поддерживаются положительные целые числа (минимум - 1 секунда);
  
• Можно использовать суффиксы времени (например, 30s, 1m, 2h, 1d);
  
• Можно использовать пользовательские макросы и макросы обнаружения низкого уровня;
  
• Если значение отбрасывается, оно не сохраняется в базе данных, и сервер Zabbix не знает, что это значение было получено. Выражения триггеров вычисляться не будут, поэтому проблемы для связанных триггеров создаваться или разрешаться не будут. Функции будут работать только на основе данных, фактически сохраненных в базе данных. Поскольку тренды строятся на основе данных в базе данных, если за час не было сохранено ни одного значения, данные трендов за этот час также отсутствуют.
  
• Для одного элемента данных можно указать только один параметр регулирования.

Шаблон Prometheus

Используйте следующий запрос для извлечения необходимых данных из метрик Prometheus.

Дополнительные сведения см. в разделе Проверки Prometheus.

Prometheus в JSON

Преобразует необходимые метрики Prometheus в JSON.

Подробнее см. в разделе Проверки Prometheus.

Поддержка макросов

Пользовательские макросы и пользовательские макросы с контекстом поддерживаются в:

• параметрах шагов предварительной обработки, включая код JavaScript;
• параметрах обработки пользовательских ошибок (поля Задать значением и Задать ошибку в).

Тестирование

Смотрите тестирование предварительной обработки.