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

Обзор

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

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

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

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

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

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

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

Настройка

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

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

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

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

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

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

Обратите внимание, что для шагов предварительной обработки Изменение и Регулирование 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>

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 и соответствующий путь к OID SNMP. Значения полей будут заполнены значениями из указанного пути к OID SNMP.

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

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

Получение значения 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 сервер не будет знать, что значение было получено. Выражения триггеров не будут пересчитываться, в результате не будут созданы/закрыты проблемы по связанным триггерам. Функции триггеров будут работать только на основе данных, которые фактически сохраняются в базу данных. Поскольку динамика изменений строится на основе данных в базе данных, если в течение часа не сохраняются значения, то для этого часа также не будет данных динамики изменений.
  
• Для элемента данных можно указать только один параметр троттлинга.

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

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

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

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

Шаблон Prometheus (Prometheus pattern)

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

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

Prometheus в JSON

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

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

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

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

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

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

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