Struktura transformacji w usłudze Azure Monitor

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ę extend przy użyciu operatora .
• Formatuje dane wyjściowe w celu dopasowania kolumn tabeli docelowej przy użyciu project operatora .

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.

Przeanalizuj polecenie

Polecenie analizy w transformacji jest ograniczone do 10 kolumn na instrukcję ze względu na wydajność. Jeśli transformacja wymaga analizowania więcej niż 10 kolumn, podziel ją na wiele instrukcji zgodnie z opisem w artykule Podział dużych poleceń analizy.

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! Tworzenie lub aktualizowanie kontrolera DOMENY bez TimeGenerated w danych wyjściowych przekształcenia prowadzi do 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

parse_json Użyj funkcji 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

Instrukcja let

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żeń tabelarycznych

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
  

• print operator, który zawsze tworzy pojedynczy wiersz. Na przykład:

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

Operatory tabelaryczne

• extend
• project
• print
• where
• parse
• project-away
• project-rename
• datatable
• columnifexists (użyj kolumnifexists 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 .

• ==
• !=
• =~
• !~
• contains
• !contains
• contains_cs
• !contains_cs
• has
• !has
• has_cs
• !has_cs
• startswith
• !startswith
• startswith_cs
• !startswith_cs
• endswith
• !endswith
• endswith_cs
• !endswith_cs
• matches regex
• in
• !in

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

• binary_and
• binary_or
• binary_not
• binary_shift_left
• binary_shift_right
• binary_xor

Funkcje konwersji

• tobool
• todatetime
• todouble/toreal
• toguid
• toint
• tolong
• tostring
• totimespan

Funkcje DateTime i TimeSpan

• ago
• datetime_add
• datetime_diff
• datetime_part
• dayofmonth
• dayofweek
• dayofyear
• endofday
• endofmonth
• endofweek
• endofyear
• getmonth
• getyear
• hourofday
• make_datetime
• make_timespan
• now
• startofday
• startofmonth
• startofweek
• startofyear
• todatetime
• totimespan
• weekofyear

Funkcje dynamiczne i tablicowe

• array_concat
• array_length
• pack_array
• pack
• parse_json
• parse_xml
• zip

Funkcje matematyczne

• abs
• bin/floor
• ceiling
• exp
• exp10
• exp2
• isfinite
• isinf
• isnan
• log
• log10
• log2
• pow
• round
• sign

Funkcje warunkowe

• case
• iif
• max_of
• min_of

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
• extract
• extract_all
• indexof
• isempty
• isnotempty
• parse_json
• replace
• split
• strcat
• strcat_delim
• strlen
• substring
• tolower
• toupper
• hash_sha256

Funkcje typów

• gettype
• isnotnull
• isnull

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.