timeaggs
Описание
Выполняет поиск и генерацию массива данных, распределенных по временной шкале с помощью внутренних механизмов хранилища.
Использование timeaggs в запросе допустимо в случае, если перед ней находятся только команды, также работающие с внутренними механизмами хранилища. К ним относятся source, search и peval. Это условие должно выполняться и для всех подзапросов в запросе.
Синтаксис
timeaggs [<composite>] [<span>] [<timefield>] [<limit>] [<useother>] <functions-expression> ["," <functions-expression>] [<by_expression>]
Обязательные аргументы
functions-expression Обязательно использование хотя бы одной из функций:
| Параметр | Синтаксис | Описание |
|---|---|---|
count | count | count(<field>) | Вычисляет количество событий, содержащих поле. Если поле не указано, рассчитывает общее количество событий. |
avg | avg(<field>) | Вычисляет среднее значение по заданному полю. |
dc | dc(<field>) | Вычисляет количество уникальных значений в заданном поле. |
max | max(<field>) | Вычисляет максимальное значение по заданному полю. |
min | min(<field>) | Вычисляет минимальное значение по заданному полю. |
sum | sum(<field>) | Вычисляет сумму значений по заданному полю. |
perc | perc(<field>, <percent>) | Вычисляет персентиль по заданному полю и проценту. |
median | median(<field>) | Вычисляет медиану по заданному полю. |
Опциональные аргументы
| Параметр | Синтаксис | По умолчанию | Описание |
|---|---|---|---|
span | span=<span> | см. Предопределенные значения span | Определяет интервал для распределения отрезков. |
timefield | timefield=<field> | @timestamp | Имя поля в котором хранится временная метка. |
composite | composite=<boolean> | false | Дает возможность использования скроллинга в агрегациях и получить все возможные сегменты (buckets) с помощью нескольких запросов (аналогично scroll в stats). Может быть применен только при наличии группировки (by полей). Количеством сегментов (buckets), которые будут возвращены в ответе имеет фиксированное значение — 1000. |
limit | limit=<int> | 10 | Максимальное количество уникальных значений by_field, которые будут использоваться в названии столбцов результата. Остальные значения объединятся в поле OTHER. |
useother | useother=<boolean> | true | При значении false параметр limit не учитывается. |
by_expression | by <field> | Имя поля для группировки значений. |
Допустим следующий формат временных параметров: (+|-)<int>(s|m|h|d|w|month):
- s/sec/secs/second/seconds - секунды
- m/min/mins/minute/minutes - минуты
- h/hr/hrs/hour/hours - часы
- d/day/days - дни
- w/week/weeks - недели
- mon/month/months - месяцы
Если не указан параметр span для временного поля, будут действовать предопределенные параметры.
Перечень предопределенных параметров:
| Временной интервал | span |
|---|---|
| последние 15 минут | 10 секунд |
| последние 60 минут | 1 минута |
| последние 4 часа | 5 минут |
| последние 24 часа | 30 минут |
| последние 7 дней | 1 день |
| последние 30 дней | 1 день |
| последний год | 1 месяц |
Аргумент composite доступен при запросе к OpenSearch.
Aggregations в OpenSearch выполняют статистическую обработку по числовым типам полей или же keyword, если поле текстовое. В соответствии с этим для текстовых полей нужно дописывать <название поля>.keyword. Это необходимо делать как в заданных, так и в by полях. Пример:
... | timeaggs avg(user.keyword), earliest(country.keyword) by event.keyword, user_count
Примеры запросов
Пример 1:
Расчет среднего количества сообщений для каждого пользователя по часовым интервалам:
... | timeaggs span=1h avg(msgNums) by user.keyword
В данном примере для каждого уникального значения поля user.keyword рассчитывается среднее количество сообщений msgNums за каждый часовой интервал.
Пример 2:
В данном примере для каждого уникального значения поля event.outcome производится агрегация данных за интервал времени в 15 минут с подсчетом количества событий.
... | timeaggs span=15m count by event.outcome
Для входных данных, представленных ниже в качестве примера, строится столбчатая диаграмма c группировкой серий:
| username | request | path | status | event.outcome |
|---|---|---|---|---|
| Ivanov | GET | /veil | 200 | success |
| Petrov | GET | /cherry | 200 | success |
| Ivanov | POST | /fuel | 403 | failure |
| Andreev | GET | /quilt | 200 | success |
Пример 3:
Подсчет общего количества событий и максимального смещения лога по 3-часовым интервалам:
... | timeaggs composite=true span=3h count, max(log.offset)
Пример 4:
В данном примере для каждого 5-дневного интервала система вернет значение поля log.offset которое встречается в 5 процентах случаев:
... | timeaggs span=5d perc(log.offset, 5)
Пример 5:
Расчет максимального объема сетевого трафика для каждого хоста по 30-минутным интервалам с ограничением на количество уникальных хостов:
В данном примере создается новое поле network.kb, которое преобразует значения поля network.bytes в килобайты, команда round округляет килобайты до 2 значащий цифр и сохраняет в новое поле network.kb_round.
... | peval network.kb=network.bytes/1024, network.kb_round=round(network.kb, 2)
| timeaggs limit=3 span=30m max(network.kb_round) by hostname
Для каждого уникального значения хоста hostname рассчитывается максимальный объем сетевого трафика network.kb_round за 30-минутные интервалы. Параметр limit=3 ограничивает количество уникальных хостов в результате до трех; остальные хосты объединяются в столбец OTHER.
| timeaggs limit=3 span=30m max(network.kb_round) by hostname
Пример входных данных:
| hostname | network.bytes | @timestamp |
|---|---|---|
| SPB | 72343 | 2025-05-26T15:25:39.697685Z |
| NSK | 85804 | 2025-05-26T15:25:33.003472Z |
| NN | 60239 | 2025-05-26T15:25:24.338701Z |
| SPB | 10646 | 2025-05-26T15:25:24.290198Z |
| MSK | 10646 | 2025-05-26T15:25:25.223198Z |
Результатом выполнения запроса может быть следующая таблица:
| OTHER | SPB | NSK | NN | _time |
|---|---|---|---|---|
| 99,84 | null | null | 87,4 | 2025-05-26T16:00:00.000Z |
| 91,71 | 87,409 | null | null | 2025-05-26T16:30:00.000Z |
| 85.36 | null | 89,75 | 15,96 | 2025-05-26T16:30:00.000Z |
