Агрегация по ключам

В версии KOMRAD v4.5 появилась возможность производить агрегацию отфильтрованных событий по определенному полю. Для этого при создании правила директивы необходимо выбрать тип узла "Событие" и написать правило агрегации на предметно-ориентированном языке в поле для выражения.

Язык правила агрегации

Синтаксис языка можно хорошо представить в виде следующего шаблона:

group_by [ <поле группировки> ] window
    <максимальное число событий> last events
   or
    <временное окно> threshold <минимальное количество событий>
derive [
    <агрегированное поле> = <правило трансформации> (agg.)?<поле события>
    ...
],
* from <last|first> event <with|without> overwrite

Разберем язык подробнее. Условно можно поделить выше написанное правило на три секции:

• Само правило агрегации (group_by ...)
• Частный вывод полей (derive [ ... ])
• Общий вывод полей (* from ...)

Правило агрегации

group_by

Правило агрегации начинается с ключевого слова group_by и обязательно должно быть указано в выражении (иначе оно будет воспринято как правило CEL). После group_by в квадратных скобках необходимо указать поле события, по которому будет проводиться агрегация. Это означает, что между собой будут объединяться события с одинаковым (и присутствующим) значением данного поля. Допустим, у нас есть 4 события с полем ECS.Client.Port:

group_by [ECS.Client.Port] ...

Event 1: ECS.Client.Port = 40999
Event 2: ECS.Client.Port = 41001
Event 3: ECS.Client.Port = 41001
Event 4: ECS.Client.Port = 40999

В таком случае при агрегации мы получим одно агрегированное событие с портом 40999 и второе с портом 41001.

Функция unnest

Необходимо отметить, что если в качестве поля будет указан массив (например, AssetIPs), то агрегация будет проходить не по каждому элементу массива, а целиком по массиву. То есть, события будут агрегированы только в том случае, если все элементы массива в них совпадают. Чтобы избежать этого, можно использовать на массив функцию unnest, тогда для агрегации будут использованы отдельные элементы массива. Пример:

group_by [unnest(AssetIPs)] ...

Временное окно

После указания поля агрегации необходимо указать временное окно. Пример:

... window 25 last events or 1h threshold 10 ...

Данное окно имеет максимальный размер в 25 событий, либо срабатывает по истечении часа с, как минимум, 10 событиями. Временной интервал имеет следующий формат:

<число>.<число>d <число>.<число>h <число>.<число>m <число>.<число>s

Каждая из частей необязательна, но должна быть указана хотя бы одна. Здесь секция 'd' означает количество дней, 'h' - количество часов, 'm' - количество минут, 's' - количество секунд.

Вывод полей

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

• Частный вывод (вывод отдельных полей)
• Общий вывод (вывод всех полей)

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

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

Разберем частный вывод полей.

Частный вывод полей

Секция частного вывода полей начинается с ключевого слова derive, после которого в квадратных скобках указаны правила для вывода отдельных полей.

Пример:

... derive [
    MaxPackets = max agg.ECS.Client.Packets,
    UniqueAssets = distinct agg.AssetIPs
    ]

Как можем увидеть, результирующему агрегированному полю можно задавать любое имя - оно затем будет отображено в переменных истории. Также здесь используются правила трансформации max и distinct. Помимо них также существуют и другие правила. Рассмотрим все:

• first - использовать значение поля из первого события
• last - использовать значение поля из последнего события
• distinct - использовать все уникальные значения из полей событий в виде массива. Если поле само является массивом, то правило будет применено к отдельным его элементам
• avg - использовать среднее значение поля. Применяется только к полям с числовым типом значения
• sum - использовать сумму значений поля. Применяется только к полям с числовым типом значения
• min - использовать минимальное значение поля. Применяется только к полям с числовым типом значения
• max - использовать максимальное значение поля. Применяется только к полям с числовым типом значения

Общий вывод полей

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

...], * from first event without overwrite

Секция общего вывода полей начинается со звездочки (по подобию SQL), после которого указано ключевое слово from. Затем идет указатель "базового" события - first event или last event - используем мы первое или последнее событие в агрегации. Именно на основе "базового" события происходит вывод всех полей.

После указания базового события необходимо указать отсутствие или наличие перезаписи значений - without overwrite или with overwrite. Если перезапись активна, а одним из частных правил уже выведено поле, то, если базовое событие имеет данное поле, то его значением будет перезаписано старое из частного вывода.