Struttura della trasformazione in Monitoraggio di Azure

Articolo
10/29/2024

Le trasformazioni in Monitoraggio di Azure consentono di filtrare o modificare i dati in ingresso prima che vengano archiviati 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 consentono di filtrare o modificare i dati in ingresso prima che vengano archiviati 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.

Comando Parse

Il comando parse in una trasformazione è limitato a 10 colonne per istruzione per motivi di prestazioni. Se la trasformazione richiede l'analisi di più di 10 colonne, suddividerla in più istruzioni, come descritto in Suddividere i comandi di analisi di grandi dimensioni.

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 un record di dominio senza TimeGenerated nell'output di una trasformazione comporta 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 parse_json funzione 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

print operatore, che produce sempre una singola riga. Ad esempio:
```
print x = 2 + 2, y = 5 | extend z = exp2(x) + exp2(y)
```

Operatori tabulari

extend
project
print
where
parse
project-away
project-rename
datatable
columnifexists (usare columnifexists invece di 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
endswith
!endswith
endswith_cs
!endswith_cs
matches 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

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. 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.

Condividi tramite