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

Обзор

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

Эта возможность поддерживает различные сценарии использования, например:

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

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

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

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

См. также: Примеры предобработки

Конфигурация

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

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

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

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

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

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

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

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

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

Параметры:

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

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

• Если входное значение не совпадает, элемент данных станет неподдерживаемым;
  
• Регулярное выражение поддерживает извлечение максимум 10 захваченных групп с помощью последовательности \N;
  
• Если установить флажок Custom on fail, можно указать пользовательские параметры обработки ошибок: либо отбросить значение, либо установить указанное значение, либо установить указанное сообщение об ошибке. В случае сбоя на этапе предобработки элемент данных не станет неподдерживаемым, если выбрана опция отбросить значение или установить указанное значение.
  
• Некоторые существующие примеры приведены в разделе regular expressions.

Заменить

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

Параметры:

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

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

• Все вхождения строки поиска будут заменены;
• Можно использовать escape-последовательности для поиска или замены переводов строк, возврата каретки, табуляции и пробелов "\n \r \t \s"; обратную косую черту можно экранировать как "\\" , а escape-последовательности можно экранировать как "\\n";
• Экранирование переводов строк, возврата каретки и табуляции выполняется автоматически во время обнаружения низкого уровня.

Обрезать

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

Обрезать справа

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

Обрезать слева

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

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

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

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

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

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

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

• Используйте эту опцию, чтобы преобразовывать значения, полученные в KB, MBps и т. д., в B, Bps. В противном случае Zabbix не сможет корректно устанавливать префиксы (K, M, G и т. д.).
  
• Обратите внимание, что если тип информации элемента данных — Numeric (unsigned), входящие значения с дробной частью будут усечены (то есть '0.9' станет '0') до применения пользовательского множителя;
  
• Если вы используете пользовательский множитель или сохраняете значение как Change per second для элементов данных с типом информации Numeric (unsigned), и итоговое вычисленное значение фактически является числом с плавающей точкой, это вычисленное значение всё равно будет принято как корректное: дробная часть будет отброшена, а значение сохранено как целое число;
  
• Поддерживается: научная нотация, например 1e+70; пользовательские макросы и LLD-макросы; строки, включающие макросы, например {#MACRO}e+10, {$MACRO1}e+{$MACRO2}. Макросы должны разрешаться в целое число или число с плавающей точкой.
• Если вы установите флажок Custom on fail, можно указать пользовательские параметры обработки ошибок: либо отбросить значение, установить указанное значение или установить указанное сообщение об ошибке. В случае сбоя шага предобработки элемент данных не станет неподдерживаемым, если выбрана опция отброса значения или установки указанного значения.

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

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

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

• Этот шаг может быть полезен для измерения постоянно растущего значения;
  
• Вычисляется как value-prev_value, где value — текущее значение; prev_value — ранее полученное значение;
  
• Для одного элемента данных допускается только одна операция изменения ("Simple change" или "Change per second");
• Если текущее значение меньше предыдущего, Zabbix отбрасывает эту разницу (ничего не сохраняет) и ожидает другое значение;
  
• Если вы установите флажок Custom on fail, можно указать пользовательские варианты обработки ошибок: либо отбросить значение, либо установить указанное значение, либо установить указанное сообщение об ошибке. В случае сбоя шага предобработки элемент данных не станет неподдерживаемым, если выбрана опция отбросить значение или установить указанное значение.

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

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

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

• Этот шаг полезен для вычисления скорости в секунду для постоянно растущего значения;
  
• Поскольку результатом этого вычисления могут быть числа с плавающей точкой, рекомендуется установить для параметра 'Type of information' значение Numeric (float), даже если входящие необработанные значения являются целыми числами. Это особенно важно для небольших чисел, где имеет значение дробная часть. Если значения с плавающей точкой велики и могут превысить длину поля 'float', в результате чего всё значение может быть потеряно, фактически рекомендуется использовать Numeric (unsigned) и тем самым отсечь только дробную часть.
  
• Вычисляется как (value-prev_value)/(time-prev_time), где value — текущее значение; prev_value — ранее полученное значение; time — текущая временная метка; prev_time — временная метка предыдущего значения;
  
• Допускается только одна операция изменения на элемент данных ("Simple change" или "Change per second");
• Если текущее значение меньше предыдущего, Zabbix отбрасывает эту разницу (ничего не сохраняет) и ожидает следующее значение. Это помогает корректно работать, например, с переполнением (циклическим возвратом) 32-битных SNMP-счётчиков.
  
• Если установить флажок Custom on fail, можно указать пользовательские варианты обработки ошибок: либо отбросить значение, либо установить указанное значение, либо установить указанное сообщение об ошибке. В случае сбоя на шаге предобработки элемент данных не станет неподдерживаемым, если выбрана опция отбросить значение или установить указанное значение.

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

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

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

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

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

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

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

Шестнадцатеричное в десятичное

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

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

JavaScript

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

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

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

В диапазоне

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

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

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

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

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

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

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

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

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

Проверка ошибки в JSON

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

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

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

Проверка ошибки в XML

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

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

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

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

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

Параметры:

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

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

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

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

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

Параметры:

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

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

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

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

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

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

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

Отбрасывать неизменившееся с контрольным интервалом

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

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

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

Шаблон Prometheus

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

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

Prometheus в JSON

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

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

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

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

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

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

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