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 essere archiviati in un'area di lavoro Log Analytics. Vengono implementati come istruzione Linguaggio di query Kusto (KQL) in una regola di raccolta dati (DCR). Questo articolo fornisce informazioni dettagliate sul modo in cui questa query è strutturata e 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. Il flusso di input è rappresentato da una tabella virtuale denominata source con colonne corrispondenti alla definizione del flusso di dati di input. Di seguito è riportato un esempio tipico di una trasformazione. Questo esempio include le funzionalità seguenti:

  • Filtra i dati in ingresso con un'istruzione where
  • Aggiunge una nuova colonna usando l'operatore di estensione
  • Formatta l'output in modo che corrisponda alle colonne della tabella di destinazione usando l'operatore di progetto
source  
| where severity == "Critical" 
| extend Properties = parse_json(properties)
| project
    TimeGenerated = todatetime(["time"]),
    Category = category,
    StatusDescription = StatusDescription,
    EventName = name,
    EventId = tostring(Properties.EventId)

Limitazioni KQL

Poiché la trasformazione viene applicata a ogni record singolarmente, non può usare gli operatori KQL che agiscono su più record. Sono supportati solo gli operatori che accettano una singola riga come input e non restituiscono più di una riga. Ad esempio, il riepilogo non è supportato perché riepiloga più record. Per un elenco completo delle funzionalità supportate, vedere Funzionalità KQL supportate.

Le trasformazioni in una regola di raccolta dati (DCR) 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 un registro di dominio, inclusi i dettagli e le limitazioni della Linguaggio di query Kusto (KQL) usata 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 o project finaleextend! La creazione o l'aggiornamento di un registro di dominio senza TimeGenerated nell'output di una trasformazione comportano un errore.

Gestione dei dati dinamici

Prendere in considerazione l'input seguente 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, definirla 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 le stesse 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 funzioni definite dall'utente con argomenti scalari.

Istruzioni di espressione tabulari

L'unica origine dati supportata per l'istruzione KQL è la seguente:

  • origine, che rappresenta i dati di origine. Ad esempio:
source
| where ActivityId == "383112e4-a7a8-4b94-a701-4266dfc18e41"
| project PreciseTimeStamp, Message
  • Operatore di stampa, 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

Tutti gli operatori numerici sono supportati.

Operatori aritmetici datetime e Timespan

Sono supportati tutti gli operatori aritmetici Datetime e Timespan .

Operatori di stringa

Sono supportati gli operatori String seguenti.

  • ==
  • !=
  • =~
  • !~
  • contains
  • !contains
  • contains_cs
  • !contains_cs
  • has
  • !ha
  • has_cs
  • !has_cs
  • startswith
  • !startswith
  • startswith_cs
  • !startswith_cs
  • endswith
  • !endswith
  • endswith_cs
  • !endswith_cs
  • corrisponde a regex
  • in
  • !Pollici

Operatori bit per bit

Sono supportati gli operatori Bitwise seguenti.

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

Funzioni scalari

Funzioni bit per bit

Funzioni di conversione

Funzioni DateTime e TimeSpan

Funzioni dinamiche e di matrice

Funzioni matematiche

Funzioni condizionali

Funzioni per i valori 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. Punto e virgola è un carattere riservato che deve essere sostituito prima di passare il messaggio non elaborato nel metodo , come illustrato nell'esempio seguente.

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

Virgolette identificatore

Usare le virgolette identificatore come richiesto.

Passaggi successivi