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

Обзор

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

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

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

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

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

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

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

Настройка

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

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

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

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

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

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

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

Регулярное выражение (Regular expression)

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

Параметры:

• шаблон (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>

JSON Path

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

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

CSV в JSON

Сконвертировать данные файла CSV в формат JSON.

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

XML в JSON

Сконвертировать данные в формате XML в JSON.

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

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

Значение SNMP walk (SNMP walk value)

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

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

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

SNMP walk в JSON

Преобразовать значения SNMP в JSON.

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

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

• Доступны параметры форматирования значений, аналогичные шагу Значение SNMP walk;
  
• Можно использовать этот шаг предварительной обработки для обнаружения SNMP OID;
  
• Если выбрана опция Другое при ошибке, можно указать пользовательские варианты обработки ошибок: либо отбросить значение, либо задать нужное значение, либо задать нужное сообщение об ошибке. В случае неудачного завершения шага предобработки элемент данных не станет неподдерживаемым, если выбран вариант отбросить значение или выставить в указанное значение.

SNMP get значение (SNMP get value)

Применить параметры форматирования к SNMP get значение:

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

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

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

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

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

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

Простое изменение (Simple change)

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

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

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

Изменение в секунду (Change per second)

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

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

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

Логический в десятичный (Boolean to decimal)

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

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

• Текстовое представление значения переводится в значения 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.
  
• Если выбрана опция Другое при ошибке, можно указать пользовательские варианты обработки ошибок: либо отбросить значение, либо задать нужное значение, либо задать нужное сообщение об ошибке. В случае неудачного завершения шага предобработки элемент данных не станет неподдерживаемым, если выбран вариант отбросить значение или выставить в указанное значение.

Восьмеричное в десятичное (Octal to decimal)

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

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

Шестнадцатеричное в десятичное (Hexadecimal to decimal)

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

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

JavaScript

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

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

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

По диапазону (In range)

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

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

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

Соответствие регулярному выражению (Matches regular expression)

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

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

Не совпадает с регулярным выражением (Does not match regular expression)

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

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

Проверка на ошибку в JSON (Check for error in JSON)

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

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

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

Проверка на ошибку в XML (Check for error in XML)

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

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

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

Проверка на ошибку с использованием регулярного выражения (Check for error using a regular expression)

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

Параметры:

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

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

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

Проверка на неподдерживаемое значение (Check for not supported value)

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

Параметры:

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

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

• Обычно отсутствие/неудача при получении значения приводит к тому, что элемент данных становится неподдерживаемым. Этот шаг предварительной обработки позволяет изменить это поведение. Если отметить флажок Другое при ошибке (для этого шага предварительной обработки он всегда отмечен и неактивен), то можно указать пользовательские параметры обработки ошибок: либо отбросить значение, либо задать указанное значение, либо установить указанное сообщение об ошибке. В случае неудачного шага предварительной обработки элемент данных не станет неподдерживаемым, если выбрана опция отбросить значение или установить указанное значение.
• Этот шаг предобработки проверяет только факт того, что не удалось извлечь значение элемента данных. Он не проверяет, например, соответствует ли тип полученного значения (скажем, строка) типу информации элемента данных (скажем, числовой). Если есть несоответствие типов, элемент данных всё равно может стать неподдерживаемым после выполнения всех шагов предобработки. Для проверки несоответствия типов можно использовать, например, шаг предобработки Пользовательский множитель; смотрите Примеры предварительной обработки.
• В полях Задать значением или Задать ошибку в поддерживаются скобочные группы регулярных выражений. Используйте управляющую последовательность \N (где N=1…9), чтобы извлечь N-ю совпавшую группу, используйте управляющую последовательность \0 для извлечения всего совпавшего текста.
• Эти шаги всегда выполняются первыми шагами предварительной обработки и размещаются над всеми остальными после сохранения изменений в элементе данных.
• Поддерживаются несколько шагов Проверка на неподдерживаемое значение в указанном порядке. Шаг для любой ошибки будет автоматически помещён последним шагом в этой группе.

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

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

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

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

Отбрасывать не изменившееся с периодическим контролем (Discard unchanged with heartbeat)

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

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

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

Шаблон Prometheus (Prometheus pattern)

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

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

Prometheus в JSON

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

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

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

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

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

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

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