Condividi tramite

Struttura della trasformazione in Monitoraggio di Azure

  • Articolo

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

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

Funzioni Dinamiche e matrice

Funzioni matematiche

Funzioni condizionali

Funzioni di stringa

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

Output di esempio della funzione parse_cef_dictionary.

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")

Screenshot dell'output di esempio della funzione geo_location.

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