Struktur von Transformationen in Azure Monitor

Artikel
03/06/2024

Mit Transformationen in Azure Monitor können Sie eingehende Daten filtern oder modifizieren, bevor sie in einem Log Analytics-Arbeitsbereich gespeichert werden. Sie werden als KQL-Anweisung (Kusto Query Language, Kusto-Abfragesprache) in einer Datensammlungsregel (Data Collection Rule, DCR) implementiert. Dieser Artikel enthält Details zur Strukturierung dieser Abfrage sowie zu zulässigen Einschränkungen für die KQL-Sprache.

Transformationsstruktur

Die KQL-Anweisung wird einzeln auf jeden Eintrag in der Datenquelle angewendet. Sie muss das Format der eingehenden Daten erfassen können und die Ausgabe in der Struktur der Zieltabelle erstellen. Eine virtuelle Tabelle mit dem Namen source stellt den Eingabedatenstrom dar. source Tabellenspalten entsprechen der Definition des Eingabedatenstroms. Das folgende Beispiel ist typisch für eine Transformation. Dieses Beispiel umfasst die folgenden Funktionen:

Filtern der eingehenden Daten mit einer where-Anweisung
Hinzufügen einer neuen Spalte mithilfe des extend-Operators
Formatieren der Ausgabe mithilfe des project-Operators, sodass sie mit den Spalten der Zieltabelle übereinstimmt

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

Einschränkungen von KQL

Da die Transformation auf jeden Datensatz einzeln angewendet wird, können keine KQL-Operatoren verwendet werden, die auf mehrere Datensätze angewendet werden. Nur Operatoren, die eine einzelne Zeile als Eingabe verwenden und nicht mehr als eine Zeile zurückgeben, werden unterstützt. Beispielsweise wird summarize nicht unterstützt, da damit mehrere Datensätze zusammengefasst werden. Eine vollständige Liste der unterstützten Features finden Sie unter Unterstützte KQL-Features.

Mit Transformationen in einer Datensammlungsregel (Data Collection Rule, DCR) können Sie eingehende Daten filtern oder modifizieren, bevor sie in einem Log Analytics-Arbeitsbereich gespeichert werden. In diesem Artikel wird beschrieben, wie Transformationen in einer DCR erstellt werden. Dazu gehören auch Details zu und Einschränkungen der Kusto-Abfragesprache (Kusto Query Language, KQL), die für die Transformationsanweisung verwendet wird.

Erforderliche Spalten

Die Ausgabe jeder Transformation muss einen gültigen Zeitstempel in einer Spalte mit dem Namen TimeGenerated vom Typ datetimeenthalten. Stellen Sie sicher, dass Sie ihn in den finalen extend- oder project-Block einschließen! Das Erstellen oder Aktualisieren von DCRs ohne TimeGenerated in der Ausgabe einer Transformation führt zu einem Fehler.

Verarbeiten dynamischer Daten

Betrachten Sie die folgende Eingabe mit dynamischen Daten:

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

Um auf die Eigenschaften in AdditionalContext zuzugreifen, definieren Sie die Spalte im Eingabestream als Spalte des dynamischen Typs:

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

Der Inhalt der AdditionalContext-Spalte kann jetzt analysiert und in der KQL-Transformation verwendet werden:

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

Dynamische Literale

Verwenden Sie die parse_json-Funktion zum Verarbeiten dynamischer Literale.

So ergeben beispielsweise die folgenden Abfragen die gleiche Funktionalität:

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

Unterstützte KQL-Features

Unterstützte Anweisungen

let-Anweisung

Die rechte Seite von let kann ein Skalarausdruck, ein tabellarischer Ausdruck oder eine von den Benutzer*innen definierte Funktion sein. Nur benutzerdefinierte Funktionen mit Skalarargumenten werden unterstützt.

Anweisungen für „tabular expression“

Die einzigen unterstützten Datenquellen für die KQL-Anweisung sind:

source, die die Quelldaten darstellt. Beispiel:

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

print-Operator, der immer eine einzelne Zeile erzeugt. Beispiel:

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

Tabellarische Operatoren

extend
project
print
where
parse
project-away
project-rename
datatable
columnifexists (Verwenden Sie „columnifexists“ anstelle von „column_ifexists“.)

Skalar-Operatoren

Numerische Operatoren

Alle numerischen Operatoren werden unterstützt.

Arithmetische Operatoren „Datetime“ und „Timespan“

Alle arithmetischen Operatoren „Datetime“ und „Timespan“ werden unterstützt.

Zeichenfolgenoperatoren

Folgende Zeichenfolgenoperatoren werden unterstützt.

==
!=
=~
!~
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

Bitweise Operatoren

Folgende bitweise Operatoren werden unterstützt.

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

Skalarfunktionen

Bitweise Funktionen

Konvertierungsfunktionen

Funktionen für „DateTime“ und „TimeSpan“

Dynamische Funktionen und Arrayfunktionen

Mathematische Funktionen

Bedingte Funktionen

Zeichenfolgenfunktionen

base64_encodestring (Verwenden Sie „base64_encodestring“ anstelle von „base64_encode_tostring“.)
base64_decodestring (Verwenden Sie „base64_decodestring“ anstelle von „base64_decode_tostring“.)
countof
extract
extract_all
indexof
isempty
isnotempty
parse_json
replace
split
strcat
strcat_delim
strlen
substring
tolower
toupper
hash_sha256

Typfunktionen

Sonderfunktionen

parse_cef_dictionary

Bei einer Zeichenfolge, die eine CEF-Nachricht enthält, parst parse_cef_dictionary die Erweiterungseigenschaft der Nachricht in ein dynamisches Schlüssel/Wert-Objekt. Das Semikolon ist ein reserviertes Zeichen, das vor dem Übergeben der unformatierten Nachricht an die Methode ersetzt werden muss (siehe folgendes Beispiel).

| 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

Bei einer Zeichenfolge, die eine IP-Adresse enthält (IPv4 und IPv6 werden unterstützt), gibt die Funktion geo_location den ungefähren geografischen Standort zurück, einschließlich der folgenden Attribute:

Country
Region
Zustand
Ort
Breitengrad
Längengrad

| extend GeoLocation = geo_location("1.0.0.5")

Wichtig

Aufgrund der Art des von dieser Funktion genutzten IP-Geolokalisierungsdienstes kann es bei übermäßiger Nutzung zu Latenzzeiten bei der Datenaufnahme kommen. Seien Sie vorsichtig, wenn Sie diese Funktion mehr als ein paar Mal pro Transformation verwenden.

Anführungszeichen bei Bezeichnern

Verwenden Sie nach Bedarf Anführungszeichen bei Bezeichnern.

Nächste Schritte

Erstellen Sie eine Datensammlungsregel und eine entsprechende Zuordnung von einem virtuellen Computer aus, indem Sie den Azure Monitor-Agent verwenden.