Struktur von Transformationen in Azure Monitor
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 datetime
enthalten. 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
- 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“
- 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
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.
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für