Функции событий и активных списков

В данной статье при описании функций приняты следующие обозначения:

  • Типы значений, которые принимает аргумент, указаны в угловых скобках.

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

  • После :: в угловых скобках указаны типы значений, которые возвращает функция.

Функции секретов

get_secret

Возвращает значение заданного секрета из события.

Спецификация функции

get_secret(key: <строка>)
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

key

строка

Имя секрета.

да

Примеры

Получить ключ API Datadog из метаданных события.

Example 1. Исходный код
get_secret("datadog_api_key")
Example 2. Результат
secret value

remove_secret

Удаляет секрет из события.

Спецификация функции

remove_secret(ключ: <строка>)
:: <пустое значение>
Аргумент Тип Описание По умолчанию Обязателен

ключ

строка

Имя секрета для удаления.

да

Примеры

Удаление ключа API Datadog из события.

Example 3. Исходный код
remove_secret("datadog_api_key")
Example 4. Результат
null

set_secret

Устанавливает указанный секрет в событие.

Спецификация функции

set_secret(ключ: <строка>, секрет: <строка>)
:: <пустое значение>
Аргумент Тип Описание По умолчанию Обязателен

ключ

строка

Имя секрета.

да

секрет

строка

Значение секрета.

да

Примеры

Установка значения ключа API Datadog.

Example 5. Исходный код
set_secret("datadog_api_key", "abc122")
Example 6. Результат
null

set_semantic_meaning

Устанавливает семантический смысл для события. Обратите внимание, что эта функция задает значение при запуске Vector и не имеет поведения во время выполнения. Рекомендуется размещать все вызовы этой функции в начале функции VRL. Функцию нельзя вызывать с условием (например, нельзя предотвратить присваивание значения с использованием оператора if).

Спецификация функции

set_semantic_meaning(цель: <путь>, смысл: <строка>)
:: <пустое значение>
Аргумент Тип Описание По умолчанию Обязателен

цель

путь

Путь к значению, которому будет назначено семантическое значение.

да

смысл

строка

Имя назначаемого значения.

да

Примеры

Присваивание полю пользовательского семантического смысла

Example 7. Исходный код
set_semantic_meaning(.foo, "bar")
Example 8. Результат
null

Функции таблиц обогащения

find_enrichment_table_records

Поиск строк в таблице обогащения, соответствующих предоставленному условию.

Для файловых таблиц обогащения это условие должно быть объектом VRL, в котором ключи и значения указывают на поле для поиска и значение для поиска в этом поле. Эта функция возвращает строки, соответствующие предоставленным условиям. Все поля должны совпадать, чтобы строки были возвращены; если хотя бы одно поле не совпадает, строки не возвращаются.

В настоящее время существует две формы критериев поиска:

  1. Поиск точного совпадения. Заданное поле должно точно совпадать со значением. Чувствительность к регистру может быть указана с помощью аргумента case_sensitive. Точный поиск может использовать индекс прямо в наборе данных, что делает его менее ресурсозатратным с точки зрения производительности.

  2. Поиск по диапазону дат. Заданное поле должно быть больше или равно дате from и меньше или равно дате to. Обратите внимание, что поиск по диапазону дат включает последовательное сканирование строк, которые были найдены с помощью любых точных критериев. Такая операция может оказаться ресурсозатратной, если много строк возвращается любыми точными критериями. Рекомендуется использовать диапазоны дат как единственные критерии, когда набор данных обогащения очень мал.

Для таблиц обогащения geoip это условие должно быть объектом VRL с одной парой ключ-значение, значение которой должно быть действительным IP-адресом. Пример: {"ip": .ip }. Если ожидается поле с результатом без значения, будет использовано null. Эта таблица может возвращать следующие поля:

find_enrichment_table_records(таблица: <строка>, условие: <объект>, [select: <массив>, case_sensitive: <логическое значение>])
:: <массив>
Аргумент Тип Описание По умолчанию Обязателен

таблица

строка

Таблица обогащения для поиска.

да

условие

объект

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

да

select

массив

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

нет

case_sensitive

логическое значение

Определяет, нужно ли точное совпадение текстовых полей.

true

нет

Примеры

Точное совпадение

Example 9. Исходный код
find_enrichment_table_records!("test",
{
"surname": "smith",
},
case_sensitive: false)
Example 10. Результат
[
{
"id": 1,
"firstname": "Bob",
"surname": "Smith"
},
{
"id": 2,
"firstname": "Fred",
"surname": "Smith"
}
]

Поиск по диапазону дат

Example 11. Исходный код
find_enrichment_table_records!("test",
{
"surname": "Smith",
"date_of_birth": {
"from": t'1985-01-01T00:00:00Z',
"to": t'1985-12-31T00:00:00Z'
}
})
Example 12. Результат
[
{
"id": 1,
"firstname": "Bob",
"surname": "Smith"
},
{
"id": 2,
"firstname": "Fred",
"surname": "Smith"
}
]

get_enrichment_table_record

Функция ищет строку в таблице обогащения, которая соответствует указанному условию. Должна быть найдена одна строка. Если строка не найдена или найдено более одной строки, возвращается ошибка.

Для таблиц обогащения типа file это условие должно быть объектом VRL, в котором пары ключ-значение указывают поле для поиска, сопоставленное с искомым значением в этом поле. Эта функция возвращает строки, которые соответствуют предоставленным условиям. Все поля должны совпадать, чтобы строки были возвращены; если какие-либо поля не совпадают, строки не возвращаются.

На данный момент существует две формы критериев поиска:

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

  2. Поиск по диапазону дат. Указанное поле должно быть больше или равно дате from и меньше или равно дате to. Обратите внимание, что поиск по диапазону даты включает последовательное сканирование строк, которые были найдены с помощью любых точных критериев. Такая операция может оказаться дорогостоящей, если много строк возвращается с помощью точных критериев. Рекомендуется использовать диапазоны дат как единственные критерии, когда объем данных для обогащения очень мал.

Для таблиц обогащения geoip это условие должно быть объектом VRL с одной парой ключ-значение, значение которой должно быть допустимым IP-адресом. Пример: {"ip": .ip }. Если ожидается возвращаемое поле и оно не имеет значения, будет использовано значение null. Эта таблица может возвращать следующие поля:

  • Базы данных ISP:

    • autonomous_system_number

    • autonomous_system_organization

    • isp

    • organization

  • Базы данных City:

    • city_name

    • continent_code

    • country_code

    • country_name

    • region_code

    • region_name

    • metro_code

    • latitude

    • longitude

    • postal_code

    • timezone

  • Базы данных Connection-Type:

    • connection_type

Спецификация функции

get_enrichment_table_record(table: <строка>, condition: <объект>, [select: <массив>, case_sensitive: <логическое значение>])
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

table

строка

Таблица обогащения для поиска.

да

condition

объект

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

да

select

массив

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

нет

case_sensitive

логическое значение

Должны ли текстовые поля соответствовать регистру точно.

true

нет

Ошибки

Функция get_enrichment_table_record возвращает ошибки, для которых требуется обработка:

  • Строка не найдена

  • Найдено несколько строк, соответствующих условию

Примеры

Точное совпадение

Example 13. Исходный код
get_enrichment_table_record!("test",
{
"surname": "bob",
"firstname": "John"
},
case_sensitive: false)
Example 14. Результат
{
"id": 1,
"firstname": "Bob",
"surname": "Smith"
}

Поиск по диапазону даты

Example 15. Исходный код
get_enrichment_table_record!("test",
{
"surname": "Smith",
"date_of_birth": {
"from": t'1985-01-01T00:00:00Z',
"to": t'1985-12-31T00:00:00Z'
}
})
Example 16. Результат
{
"id": 1,
"firstname": "Bob",
"surname": "Smith"
}

Функции активных списков

add_active_record

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

Спецификация функции

add_active_record(list, key, value)
:: <логическое значение>
Аргумент Тип Описание По умолчанию Обязателен

list

строка

название активного списка, в который добавляется запись

да

key

объект

уникальный ключ для записи

да

value

любой тип

значение, ассоциированное с ключом

да

Примеры

Добавление записи в активный список

Example 17. Исходный код
add_active_record("suspicious_ips", .source_ip, true)
Example 18. Результат
true

Обновление записи в активном списке

Example 19. Исходный код
add_active_record("auth_failure_counts", .user_id, failure_count + 1)
Example 20. Результат
true

get_active_record

Извлекает значение из активного списка по указанному ключу. Возвращает значение, ассоциированное с ключом, или null, если запись отсутствует.

Спецификация функции

get_active_record(list, key)
:: <любое значение>
Аргумент Тип Описание По умолчанию Обязателен

list

строка

активный список, из которого нужно извлечь запись

да

key

объект

уникальный ключ записи

да

Примеры

Получение записи из активного списка

Example 21. Исходный код
get_active_record("allowed_ips", .source_ip)
Example 22. Результат
true

remove_active_record

Удаляет запись из активного списка. Если запись с таким ключом отсутствует, ничего не происходит.

Спецификация функции

remove_active_record(list, key)
:: <логическое значение>
Аргумент Тип Описание По умолчанию Обязателен

list

строка

активный список, из которого необходимо удалить запись

да

key

объект

уникальный ключ записи, которую необходимо удалить

да

Примеры

Удаление записи из активного списка

Example 23. Исходный код
remove_active_record("auth_failure_counts", .user_id)
Example 24. Результат
true
+7 (499) 322 80 40 sales@rvision.ru

О компании Политика конфиденциальности Пользовательское соглашение