Struttura della trasformazione in Monitoraggio di Azure
Le trasformazioni in Monitoraggio di Azure consentono di filtrare o modificare i dati in ingresso prima di archiviarli in un’area di lavoro Log Analytics. Vengono implementati come un'istruzione KQL (Kusto Query Language) in una regola di raccolta dati (DCR). Questo articolo fornisce informazioni dettagliate su come questa query è strutturata e le limitazioni nel linguaggio KQL consentito.
Struttura di trasformazione
L'istruzione KQL viene applicata singolarmente a ogni voce nell'origine dati. Deve comprendere il formato dei dati in ingresso e creare l'output nella struttura della tabella di destinazione. Una tabella virtuale denominata source
rappresenta il flusso di input. source
colonne di tabella corrispondono alla definizione del flusso di dati di input. Di seguito è riportato un esempio tipico di trasformazione. Questo esempio include le funzionalità seguenti:
- Filtra i dati in ingresso con un’istruzione where
- Aggiunge una nuova colonna utilizzando l'operatore extend
- Formatta l'output in modo che corrisponda alle colonne della tabella di destinazione usando l'operatore project
source
| where severity == "Critical"
| extend Properties = parse_json(properties)
| project
TimeGenerated = todatetime(["time"]),
Category = category,
StatusDescription = StatusDescription,
EventName = name,
EventId = tostring(Properties.EventId)
Limiti KQL
Poiché la trasformazione viene applicata singolarmente a ogni record, non può usare operatori KQL che agiscono su più record. Sono supportati solo gli operatori che accettano una singola riga come input e non restituiscono più righe. Ad esempio, summarize non è supportato perché riepiloga più record. Per un elenco completo delle caratteristiche supportate, vedere funzionalità KQL supportate.
Le trasformazioni in una regola di raccolta dati (DCR) consentono di filtrare o modificare i dati in ingresso prima di archiviarli in un’area di lavoro Log Analytics. Questo articolo descrive come compilare trasformazioni in una regola di raccolta dati, inclusi dettagli e limitazioni del linguaggio di query Kusto (KQL) usato per l'istruzione transform.
Colonne obbligatorie
L'output di ogni trasformazione deve contenere un timestamp valido in una colonna denominata TimeGenerated
di tipo datetime
. Assicurarsi di includerlo nel blocco finale extend
o project
! La creazione o l'aggiornamento di una regola di raccolta dati senza TimeGenerated
nell'output di una trasformazione comporterà un errore.
Gestione di dati dinamici
Si consideri il seguente input con dati dinamici:
{
"TimeGenerated" : "2021-11-07T09:13:06.570354Z",
"Message": "Houston, we have a problem",
"AdditionalContext": {
"Level": 2,
"DeviceID": "apollo13"
}
}
Per accedere alle proprietà in AdditionalContext, definirlo come colonna di tipo dinamico nel flusso di input:
"columns": [
{
"name": "TimeGenerated",
"type": "datetime"
},
{
"name": "Message",
"type": "string"
},
{
"name": "AdditionalContext",
"type": "dynamic"
}
]
Il contenuto della colonna AdditionalContext può ora essere analizzato e usato nella trasformazione KQL:
source
| extend parsedAdditionalContext = parse_json(AdditionalContext)
| extend Level = toint (parsedAdditionalContext.Level)
| extend DeviceId = tostring(parsedAdditionalContext.DeviceID)
Valori letterali dinamici
Usare la funzione parse_json per gestire valori letterali dinamici.
Ad esempio, le query seguenti forniscono la medesima funzionalità:
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":{}}')
Funzionalità KQL supportate
Istruzioni supportate
Istruzione let
Il lato destro di let può essere un'espressione scalare, un'espressione tabulare o una funzione definita dall'utente. Sono supportate solo le funzioni definite dall'utente con argomenti scalari.
Istruzioni di espressione tabulare
Le uniche origini dati supportate per l'istruzione KQL sono le seguenti:
- source, che rappresenta i dati di origine. Ad esempio:
source
| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"
| project PreciseTimeStamp, Message
- Operatore print, che produce sempre una singola riga. Ad esempio:
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)
Operatori tabulari
- extend
- project
- where
- parse
- project-away
- project-rename
- datatable
- columnifexists (usare columnifexists anziché column_ifexists)
Operatori scalari
Operatori numerici
Sono supportati tutti gli Operatori numerici.
Operatori aritmetici Datetime e Timespan
Sono supportati tutti gli operatori aritmetici Datetime e Timespan.
Operatori di stringa
Sono supportati i seguenti operatori Stringa.
- ==
- !=
- =~
- !~
- contains
- !contains
- contains_cs
- !contains_cs
- has
- !has
- has_cs
- !has_cs
- startswith
- !startswith
- startswith_cs
- !startswith_cs
- finisce con
- !endswith
- endswith_cs
- !endswith_cs
- corrisponde a regex
- in
- !in
Operatori bit per bit
Sono supportati i seguenti operatori Bitwise.
- binary_and()
- binary_or()
- binary_xor()
- binary_not()
- binary_shift_left()
- binary_shift_right()
Funzioni scalari
Funzioni Bitwise
Funzioni di conversione
Funzioni DateTime e 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
Funzioni Dinamiche e matrice
Funzioni matematiche
Funzioni condizionali
Funzioni di stringa
- base64_encodestring (usare base64_encodestring anziché base64_encode_tostring)
- base64_decodestring (usare base64_decodestring anziché base64_decode_tostring)
- countof
- extract
- extract_all
- indexof
- isempty
- isnotempty()
- parse_json
- replace
- split
- strcat
- strcat_delim
- strlen
- substring
- tolower
- toupper
- hash_sha256
Funzioni per i tipi
Funzioni speciali
parse_cef_dictionary
Data una stringa contenente un messaggio CEF, parse_cef_dictionary
analizza la proprietà Extension del messaggio in un oggetto chiave/valore dinamico. Il punto e virgola è un carattere riservato che deve essere sostituito prima di passare il messaggio non elaborato nel metodo, come illustrato nell'esempio.
| 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
Data una stringa contenente l'indirizzo IP (sono supportati IPv4 e IPv6), la funzione geo_location
restituisce una posizione geografica approssimativa, inclusi gli attributi seguenti:
- Country
- Paese
- Provincia
- Città
- Latitude
- Longitude
| extend GeoLocation = geo_location("1.0.0.5")
Importante
A causa della natura del servizio di georilevazione dell’IP utilizzato da questa funzione, può introdurre una latenza di inserimento dati se usata in modo eccessivo. Prestare attenzione quando si usa questa funzione più volte per ogni trasformazione.
Virgolette identificatore
Usare le virgolette identificatore in base alle esigenze.
Passaggi successivi
- Creare una regola di raccolta dati e un'associazione da una macchina virtuale usando l'agente di Monitoraggio di Azure.