Struktura transformacji w usłudze Azure Monitor

Artykuł
02/28/2024

Przekształcenia w usłudze Azure Monitor umożliwiają filtrowanie lub modyfikowanie danych przychodzących przed ich zapisaniem w obszarze roboczym usługi Log Analytics. Są one implementowane jako instrukcja język zapytań Kusto (KQL) w regule zbierania danych (DCR). Ten artykuł zawiera szczegółowe informacje na temat sposobu, w jaki to zapytanie ma strukturę i ograniczenia dotyczące dozwolonego języka KQL.

Struktura przekształcania

Instrukcja KQL jest stosowana indywidualnie do każdego wpisu w źródle danych. Musi on zrozumieć format danych przychodzących i utworzyć dane wyjściowe w strukturze tabeli docelowej. Tabela wirtualna o nazwie source reprezentuje strumień wejściowy. source kolumny tabeli są zgodne z definicją wejściowego strumienia danych. Poniżej przedstawiono typowy przykład przekształcenia. Ten przykład obejmuje następujące funkcje:

Filtruje dane przychodzące za pomocą instrukcji where
Dodaje nową kolumnę przy użyciu operatora extend
Formatuje dane wyjściowe w celu dopasowania kolumn tabeli docelowej przy użyciu operatora projektu

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

Ograniczenia języka KQL

Ponieważ transformacja jest stosowana do każdego rekordu indywidualnie, nie może używać żadnych operatorów KQL działających na wielu rekordach. Obsługiwane są tylko operatory, które przyjmują jeden wiersz jako dane wejściowe i zwracają nie więcej niż jeden wiersz. Na przykład funkcja summarize nie jest obsługiwana, ponieważ podsumowuje wiele rekordów. Aby uzyskać pełną listę obsługiwanych funkcji, zobacz Obsługiwane funkcje języka KQL.

Przekształcenia w regule zbierania danych (DCR) umożliwiają filtrowanie lub modyfikowanie danych przychodzących przed ich zapisaniem w obszarze roboczym usługi Log Analytics. W tym artykule opisano sposób tworzenia przekształceń w kontrolerze domeny, w tym szczegółowe informacje i ograniczenia język zapytań Kusto (KQL) używane na potrzeby instrukcji transform.

Wymagane kolumny

Dane wyjściowe każdej transformacji muszą zawierać prawidłowy znacznik czasu w kolumnie o nazwie TimeGenerated typu datetime. Pamiętaj, aby uwzględnić go w finale extend lub project bloku! Utworzenie lub zaktualizowanie kontrolera DCR bez TimeGenerated w danych wyjściowych przekształcenia spowoduje wystąpienie błędu.

Obsługa danych dynamicznych

Rozważ następujące dane wejściowe z danymi dynamicznymi:

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

Aby uzyskać dostęp do właściwości w obiekcie AdditionalContext, zdefiniuj ją jako kolumnę typu dynamicznego w strumieniu wejściowym:

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

Zawartość kolumny AdditionalContext może być teraz analizowana i używana w przekształceniu KQL:

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

Literały dynamiczne

Użyj funkcji parse_json do obsługi literałów dynamicznych.

Na przykład następujące zapytania zapewniają te same funkcje:

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":{}}')

Obsługiwane funkcje języka KQL

Obsługiwane instrukcje

let, instrukcja

Prawa strona let może być wyrażeniem skalarnym, wyrażeniem tabelarycznym lub funkcją zdefiniowaną przez użytkownika. Obsługiwane są tylko funkcje zdefiniowane przez użytkownika z argumentami skalarnymi.

Instrukcje wyrażenia tabelarycznego

Jedynymi obsługiwanymi źródłami danych dla instrukcji KQL są następujące:

źródło, które reprezentuje dane źródłowe. Na przykład:

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

operator drukowania , który zawsze tworzy jeden wiersz. Na przykład:

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

Operatory tabelaryczne

Rozszerzyć
Projektu
Drukowania
Gdzie
Przeanalizować
odchodzi od projektu
zmiana nazwy projektu
Datatable
columnifexists (użyj wartości columnifexists zamiast column_ifexists)

Operatory skalarne

Operatory liczbowe

Obsługiwane są wszystkie operatory liczbowe.

Operatory arytmetyczne daty/godziny i przedziału czasu

Obsługiwane są wszystkie operatory arytmetyczne daty/godziny i przedziału czasu.

Operatory ciągów

Obsługiwane są następujące operatory ciągów .

==
!=
=~
!~
zawiera
!Zawiera
contains_cs
!contains_cs
Hsa
!Hsa
has_cs
!has_cs
startswith
!Startswith
startswith_cs
!startswith_cs
kończy się na
!Endswith
endswith_cs
!endswith_cs
dopasowanie wyrażeń regularnych
w
!Cala

Operatory bitowe

Obsługiwane są następujące operatory bitowe.

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

Funkcje skalarne

Funkcje bitowe

Funkcje konwersji

Funkcje DateTime i TimeSpan

Funkcje dynamiczne i tablicowe

Funkcje matematyczne

Funkcje warunkowe

Funkcje ciągów

base64_encodestring (użyj base64_encodestring zamiast base64_encode_tostring)
base64_decodestring (użyj base64_decodestring zamiast base64_decode_tostring)
countof
Wyodrębnić
extract_all
Indexof
Isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
Strlen
Podciąg
Tolower
Toupper
hash_sha256

Funkcje typów

Funkcje specjalne

parse_cef_dictionary

Biorąc pod uwagę ciąg zawierający komunikat CEF, parse_cef_dictionary analizuje właściwość Extension komunikatu w obiekcie dynamicznego klucza/wartości. Średnik to zastrzeżony znak, który należy zastąpić przed przekazaniem nieprzetworzonego komunikatu do metody, jak pokazano w przykładzie.

| 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

Biorąc pod uwagę ciąg zawierający adres IP (obsługiwane są protokoły IPv4 i IPv6), geo_location funkcja zwraca przybliżoną lokalizację geograficzną, w tym następujące atrybuty:

Kraj
Region (Region)
Stan
City
Szerokość
Długość

| extend GeoLocation = geo_location("1.0.0.5")

Ważne

Ze względu na charakter usługi geolokalizacji IP używanej przez tę funkcję może ona wprowadzać opóźnienie pozyskiwania danych, jeśli jest używane nadmiernie. Zachowaj ostrożność podczas korzystania z tej funkcji więcej niż kilka razy na przekształcenie.

Identyfikator cudzysłów

Użyj identyfikatora cudzysłów zgodnie z potrzebami.

Następne kroki

Utwórz regułę zbierania danych i skojarzenie z nią z maszyny wirtualnej przy użyciu agenta usługi Azure Monitor.

Share via