Структура преобразования в Azure Monitor

Статья
06/09/2023

Преобразования в Azure Monitor позволяют фильтровать или изменять входящие данные до того, как они будут сохранены в рабочей области Log Analytics. Они реализованы как оператор язык запросов Kusto (KQL) в правиле сбора данных (DCR). В этой статье подробно рассказывается о структуре этого запроса и допустимых ограничениях языка KQL.

Структура преобразования

Оператор KQL применяется по отдельности к каждой записи в источнике данных. Инструкция должна определить формат входящих данных и создать выходные данные в структуре целевой таблицы. Виртуальная таблица с именем source представляет входной поток. source Столбцы таблиц соответствуют определению входного потока данных. Ниже приведен типичный пример преобразования. В этом примере выполняются следующие действия:

фильтрация входящих данных с помощью инструкции where;
добавление нового столбца с помощью оператора extend;
форматирование выходных данных в соответствии со столбцами целевой таблицы с помощью оператора project.

source  
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

Ограничения KQL

Поскольку преобразование применяется к каждой записи по отдельности, оно не может использовать операторы KQL, которые применяются к нескольким записям. Поддерживаются только те операторы, которые принимают одну строку в качестве входных данных и возвращают не более одной строки. Например, функция summarize не поддерживается, поскольку она суммирует несколько записей. Полный список поддерживаемых функций см. в разделе Поддерживаемые функции KQL.

Преобразования в правиле сбора данных (DCR) позволяют отфильтровать или изменять входящие данные перед их сохранением в рабочей области Log Analytics. В этой статье описывается, как создавать преобразования в правиле сбора данных, включая сведения и ограничения языка запросов Kusto (KQL), используемого для инструкции преобразования.

Обязательные столбцы

Выходные данные каждого преобразования должны содержать допустимую метку времени в столбце, называемом TimeGenerated типом datetime. Обязательно включите его в окончательный extend или project блок! Создание или обновление DCR без TimeGenerated выходных данных преобразования приведет к ошибке.

Обработка динамических данных

Рассмотрим следующие входные данные с использованием динамических данных:

{
    "TimeGenerated" : "2021-11-07T09:13:06.570354Z",
    "Message": "Houston, we have a problem",
    "AdditionalContext": {
        "Level": 2,
        "DeviceID": "apollo13"
    }
}

Чтобы получить доступ к свойствам в AdditionalContext, определите его как столбец динамического типа в входном потоке:

"columns": [
    {
        "name": "TimeGenerated",
        "type": "datetime"
    },
    {
        "name": "Message",
        "type": "string"
    }, 
    {
        "name": "AdditionalContext",
        "type": "dynamic"
    }
]

Теперь содержимое столбца AdditionalContext можно проанализировать и использовать в преобразовании KQL:

source
| extend parsedAdditionalContext = parse_json(AdditionalContext)
| extend Level = toint (parsedAdditionalContext.Level)
| extend DeviceId = tostring(parsedAdditionalContext.DeviceID)

Динамические литералы

Используйте функцию parse_json для управления динамическими литералами.

Например, следующие запросы имеют одинаковую функциональность.

print d=dynamic({"a":123, "b":"hello", "c":[1,2,3], "d":{}})

print d=parse_json('{"a":123, "b":"hello", "c":[1,2,3], "d":{}}')

Поддерживаемые функции KQL

Поддерживаемые инструкции

Оператор let

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

Инструкции табличных выражений

Единственными поддерживаемыми источниками данных для инструкции KQL являются следующие:

source, представляющий исходные данные. Например:

source
| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"
| project PreciseTimeStamp, Message

Оператор print, который всегда создает одну запись. Например:

print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)

Табличные операторы

extend
project
print
where
parse
project-away
project-rename
Datatable
columnifexists (используйте columnifexists вместо column_ifexists).

Скалярные операторы

Числовые операторы

Поддерживаются все числовые операторы.

Арифметические операторы DateTime и TimeSpan

Поддерживаются все арифметические операторы DateTime и TimeSpan.

Строковые операторы

Поддерживаются перечисленные ниже строковые операторы.

==
!=
=~
!~
содержит
!Содержит
contains_cs
!contains_cs
Hsa
!Hsa
has_cs
!has_cs
startswith
!startswith
startswith_cs
!startswith_cs
заканчивается на
!endswith
endswith_cs
!endswith_cs
соответствует regex
in
!in

битовые операторы;

Поддерживаются перечисленные ниже битовые операторы.

binary_and()
binary_or()
binary_xor()
binary_not()
binary_shift_left()
binary_shift_right()

Скалярные функции

Битовые функции

Функции преобразования

Функции DateTime и TimeSpan

Динамические функции и массивы

Математические функции

Условные функции

Строковые функции

base64_encodestring (используйте base64_encodestring вместо base64_encode_tostring)
base64_decodestring (используйте base64_decodestring вместо base64_decode_tostring)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
hash_sha256

Функции типа

Специальные функции

parse_cef_dictionary

Если строка, содержащая сообщение CEF, parse_cef_dictionary анализирует свойство Extension сообщения в динамический объект key/value. Точка с запятой — это зарезервированный символ, который необходимо заменить перед передачей необработанного сообщения в метод, как показано в примере.

| extend cefMessage=iff(cefMessage contains_cs ";", replace(";", " ", cefMessage), cefMessage) 
| extend parsedCefDictionaryMessage =parse_cef_dictionary(cefMessage) 
| extend parsecefDictionaryExtension = parsedCefDictionaryMessage["Extension"]
| project TimeGenerated, cefMessage, parsecefDictionaryExtension

geo_location

Учитывая, что поддерживается строка, содержащая IP-адрес (IPv4 и IPv6), geo_location функция возвращает приблизительное географическое расположение, включая следующие атрибуты:

Страна/регион
Область/регион
State
Город
Широта
Долгота

| extend GeoLocation = geo_location("1.0.0.5")

Внимание

Из-за характера службы геолокации IP, используемой этой функцией, она может привести к задержке приема данных при чрезмерном использовании. Соблюдайте осторожность при использовании этой функции более нескольких раз на преобразование.

Заключение идентификаторов в кавычки

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

Следующие шаги

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

Структура преобразования в Azure Monitor