peval

Описание

Выполняет различные операции над данными. Базируется на внутренних механизмах хранилища.

осторожно

Использование peval в запросе допустимо в случае, если перед ней находятся только команды, также работающие с внутренними механизмами хранилища. К ним относятся source и search. Это условие должно выполняться и для всех подзапросов в запросе.

Синтаксис

 | peval <field>=<expression>["," <field>=<expression>]...

Параметр	Синтаксис	Описание
field	<string>	Название поле с результатом выполнения операции.
expression	<expression>	Операция (вычисление) или набор операций (вычислений), которые необходимо выполнить для нового поля.

Поддерживаемые операции expression

Тип операции	Синтаксис	Описание
Арифметические операции	(+|-|*|/)	Арифметические операции применяются к числовым полям типа numeric.
Логические операции	(==|!=|>|>=|<|<=) (AND|OR|NOT)	Логические операции включают сравнения и логические операторы, возвращающие boolean.
Условные операции	cidrmatch coalesce like nullif case if validate	Условные операции предоставляют дополнительные возможности для обработки данных.
Математические операции	abs ceil exact exp floor ln log pi pi pow round sigfig sqrt	Математические операции с числовыми значениями для получения различных вычислений.
Временные операции	now strftime strptime	Временные операции, связанные с обработкой, управлением или анализом данных во временном интервале.
Операции идентификации типов данных	isbool isint isnotnull isnull isnum isstr typeof	Операции, в которых система или программа оценивает тип данных переменной, объекта или выражения.
Операции конвертации данных	printf tobool tonumber tostring	Это процессы преобразования данных в различные типы.
Статистические операции	max min	Это операция, которая задана для объекта или типа объектов, но не запускается для экземпляра объекта
Текстовые операции	len lower ltrim replace rtrim substr trim upper	Это набор действий, выполняемых для анализа, преобразования, форматирования, хранения или обработки текстовых данных.
Multivalues операции	mvappend mvcount mvdedup mvjoin mvrange mvsort mvzip split	Операции предназначены для работы с полями типа multivalue или создания и обработки таких массивов.
Регулярные выражения	regex	Операции на поиск по регулярному выражению.
Painless-скрипты	_script	Операции описанные на скриптовом языке Painless.

Типы данных

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

• string
• numeric
• boolean
• null
• multivalue

к сведению

Multivalues представляют из себя массивы значений, где каждый элемент - базовый тип.

Особенности для OpenSearch

• Scripts в OpenSearch выполняют обработку по числовым типам полей или же keyword, если поле текстовое. В соответствии с этим для текстовых полей нужно дописывать <название поля>.keyword.
• Регулярные выражения необходимо оборачивать в функцию regex. Она формирует правильное значение для скрипта OpenSearch:
  • Синтаксис: regex("<регулярное выражение>")
• Позволяет выполнять собственные painless-скрипты во время выполнения команды с помощью функции _script:
  • Синтаксис: _script("<script>", (<arg_name>, <arg_value>)...)

Примеры запросов

Пример 1

Конкатенация полей с добавлением строкового разделителя.

Пример №1

source nix_events-*
| search host="SPB-*"
| peval agent= agent + ":" + port
| search agent="*log*77"
| aggs values(per_number) by agent

В данном примере система фильтрует события host с префиксом SPB-*. Далее создается новое поле agent путем конкатенации строковых значений agent и port с разделителем :. Затем запрос отбирает события, где поле agent содержит подстроку log и заканчивается на 77. После этого выполняется агрегация, суммирующая значения поля per_number для каждого уникального agent.

Пример входных данных:

host	agent	port	per_number
SPB-WS-01	nginx-log	77	ivanov
SPB-WS-02	nginx-log	77	petrov
MSK-DB-02	syslog	53363	ivanov
SPB-DB-03	syslog	57177	andreev
SPB-WS-03	nginx-error	77	andreev

Результатом выполнения запроса может быть следующая таблица:

agent	values (per_number)
nginx-log:77	ivanov petrov
syslog:57177	andreev

---

Пример 2

Вычисление разницы числовых полей.

Пример №2

... | peval temp_diff=ups_adv_battery_temperature - env_temperature
| where temp_diff > 10

В данном примере команда вычисляет разность между числовыми полями ups_adv_battery_temperature и env_temperature, записывая результат в temp_diff. Фильтр where оставляет события, где разница превышает 10 градусов.

Пример входных данных:

ups_adv_battery_temperature	env_temperature
35	20
30	22
28	25

Результатом выполнения запроса может быть следующая таблица:

ups_adv_battery_temperature	env_temperature	ups_adv_battery_temperature
35	20	15
30	22	8

---

Пример 3

Классификация по значению числового поля с использованием Painless-скриптов.

Пример №3

... | peval res=_script("if (doc['total_price'].value < 1000 ) { return 'low'; } else if (doc['total_price'].value < 2000) { return 'medium'; } else { return 'high'; }", (total_price, total_price))

В данном примере команда классифицирует заказы по значению числового поля total_price через doc['total_price'].value как low (менее 1000), medium (от 1000 до 1999) или high (2000 и выше) с использованием Painless-скрипта с помощью функции _script.

Результатом выполнения запроса может быть следующая таблица:

user_id	items_quantity	operation_status	total_price	res
1	3	success	1815	medium
2	7	success	4073	high
3	10	success	5520	high
4	1	success	599	low

---

Пример 4

Определение уровня статуса на основе количества ошибок и порогового значения для каждого документа с помощью скрипта calcStatusByErrors.

... | peval level=calcStatusByErrors(errorCount, 3)

Результатом выполнения запроса может быть следующая таблица:

errorCount	level	service
3	warning	auth
0	ok	cache
10	critical	search
5	critical	billing

Пример 5

Создание массива статусов с использованием multivalue операций:

Пример №4

| peval status_list=mvappend(case(http.response.status_code == 200, "OK", http.response.status_code == 404, "Not Found", "Error"), tostring(http.response.status_code))

В данном примере система обрабатывает числовые HTTP-статусы http.response.status_code в массив status_list, содержащий текстовое описание и исходный код в виде строки.

Результатом выполнения запроса может быть следующая таблица:

source.address	destination.address	http.request.method	http.request.status	status_list
172.24.76.116	192.168.12.17	GET	200	OK 200
172.23.10.193	192.168.12.98	GET	404	Not Found 404
172.27.99.179	192.168.12.1	GET	403	Error 403

---

Пример 6

Извлечение текстового значения из поля host.name и преобразование его первой части в нижний регистр.

Пример №5

... | peval hn=lower(mvindex(split(host.name, "."), 0))

В данном примере функция split разделяет строку host.name на multivalue поле hn по разделителю ., а функция mvindex извлекает элемент с индексом 0 из этого поля. В результате функция lower преобразует этот элемент в нижний регистр.

Результатом выполнения запроса может быть следующая таблица:

user	action	host	hn	hn (без функции mvindex)
ivanov	added-user-account	WS-01.work.local	ws-01	ws-01 local work
popov	changed-password	WS-02.work.local	ws-02	ws-01 local work
andreev	removed-member-from-group	WS-03.work.local	ws-03	ws-01 local work

---

Пример 7

Создание поля для классификации событий на основе статуса HTTP-ответа:

Пример №6

source web_indexes
| peval name=if(isnull(user.name), "None", user.name)

В данном примере функция if проверяет условие isnull (user.name), возвращая true, если поле содержит пустое значение. Если условие истинно, в поле name записывается строка None; если ложно, в user.name записывается исходное значение.

Результатом выполнения запроса может быть следующая таблица:

source	destination	path	status	user	user (до выражения if)
172.26.0.240	192.168.12.100	/veil.jpg	200	Ivanov	Ivanov
172.26.0.241	192.168.12.101	/number/seashore	404	None	null
172.26.0.242	192.168.12.102	/advice	403	None	null
172.26.0.243	192.168.12.103	/walk/stove	200	Petrov	Petrov