Condividi tramite

Creare una 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 indicazioni sulla creazione e il test di una query di trasformazione e sull'aggiunta a un record di dominio.

Nota

Se non si ha familiarità con KQL o la creazione di query di log per i dati di Monitoraggio di Azure, iniziare con Panoramica di Log Analytics in Monitoraggio di Azure e query di log in Monitoraggio di Azure.

Struttura di query di base

Tutte le query di trasformazione iniziano con source, ovvero una tabella virtuale che rappresenta il flusso di input. È quindi possibile usare qualsiasi operatore KQL supportato per filtrare, modificare o aggiungere colonne ai dati come si farebbe con qualsiasi altra tabella. La query viene applicata singolarmente a ogni voce inviata dall'origine dati.

L'output della query deve corrispondere allo schema della tabella di destinazione con le considerazioni seguenti:

  • È possibile omettere tutte le colonne che non devono essere popolate. La colonna sarà vuota per il record nella tabella di destinazione.
  • Assicurarsi di escludere tutte le colonne non incluse nella tabella di output. I dati verranno accettati senza errori, ma verranno addebitati i costi per l'inserimento dei dati aggiuntivi anche se non sono archiviati.
  • L'output di ogni trasformazione deve contenere un timestamp valido in una colonna denominata TimeGenerated di tipo datetime. Se l'origine dati non include questa proprietà, è possibile aggiungerla nella trasformazione con extend o project.

Di seguito è riportato un esempio di trasformazione che esegue diverse funzioni:

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

Nota

Vedere Esempi e scenari di regole di raccolta dati (DCR) in Monitoraggio di Azure per vari esempi per diversi scenari.

Creare la query di trasformazione

Prima di creare o modificare il record di controllo di dominio che includerà la trasformazione, è necessario creare e testare la query di trasformazione. Questa operazione verrà in genere eseguita eseguendo query di test su dati o dati di test esistenti. Quando si ottengono i risultati desiderati, è possibile sostituire il nome della tabella con source e incollarlo nel record di controllo di dominio come illustrato di seguito in Aggiungi trasformazione a DCR.

Importante

Le trasformazioni non supportano tutte le funzionalità KQL. Vedere Funzionalità KQL supportate nelle trasformazioni di Monitoraggio di Azure per le funzionalità e le limitazioni supportate.

Ad esempio, se si sta creando una trasformazione per filtrare gli eventi Syslog, è possibile iniziare con la query seguente che è possibile eseguire in Log Analytics.

Syslog | where SeverityLevel != 'info'

È possibile incollare questa query nel Registro Azure Container e quindi modificare il nome della tabella in source.

source | where SeverityLevel != 'info'

Usare una delle strategie seguenti per i dati da usare per testare la query.

  • Se si raccolgono già i dati da trasformare, è possibile usare Log Analytics per scrivere una query che filtra o modifica i dati in base alle esigenze. Copiare il testo della query e incollarlo nel Registro Azure Container.
  • Usare Log Analytics per scrivere la query usando l'operatore datatable per creare un set di dati di esempio che rappresenta i dati in ingresso. Copiare il testo della query senza l'operatore datatable e incollarlo nel Registro Azure Container.
  • Usare il processo per creare una nuova tabella nel portale di Azure e fornire dati di esempio. Usare l'interfaccia inclusa per creare e testare la query di trasformazione. Copiare il testo della query e incollarlo nel DCR oppure completare il processo e quindi modificare il record di controllo di dominio per copiare la query di trasformazione. È quindi possibile eliminare la nuova tabella se non è necessaria.

Aggiungere una trasformazione a DCR

Dopo aver creato la query di trasformazione, è possibile aggiungerla a un record di dominio. Usare il materiale sussidiario in Creare e modificare le regole di raccolta dati in Monitoraggio di Azure per creare o modificare il Record di dominio DCR usando le informazioni contenute in questa sezione per includere la query di trasformazione nella definizione del record di controllo di dominio.

Nota

Alcune origini dati forniranno un metodo usando il portale di Azure per aggiungere una trasformazione a un record di controllo di dominio. Ad esempio, la raccolta di testo da una macchina virtuale consente di specificare una query di trasformazione nella portale di Azure. La maggior parte degli scenari di raccolta dati, anche se attualmente richiede l'uso diretto della definizione DCR per aggiungere una trasformazione. Questo è il processo descritto in questa sezione.

La query di trasformazione viene specificata nella transformKql proprietà nella sezione Flusso di dati s del Registro Azure Container. Questa è la sezione che associa un'origine dati a una destinazione. La trasformazione viene applicata al flusso in ingresso del flusso di dati prima dell'invio alla destinazione. Si applica solo a tale flusso di dati anche se lo stesso flusso o destinazione viene usato in altri flussi di dati.

Se la transformKql proprietà viene omessa o se il relativo valore è semplicemente source, non viene applicata alcuna trasformazione e i dati in ingresso vengono inviati alla destinazione senza modifiche.

Importante

La query di trasformazione deve trovarsi in una singola riga del Registro Azure Container. Se si sta creando la trasformazione nella portale di Azure, è possibile usare più righe per la leggibilità e \n verranno incluse nella query per ogni nuova riga.

Nell'esempio seguente non esiste alcuna transformKql proprietà, quindi i dati in ingresso vengono inviati alla destinazione senza alcuna modifica.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
]

Nell'esempio seguente è transformKql presente una semplice query di source, in modo che i dati in ingresso vengano inviati alla destinazione senza modifiche. La sua funzionalità è identica all'esempio precedente.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
]

Nell'esempio seguente è transformKql presente una query che filtra i dati, quindi solo i messaggi di errore vengono inviati alla destinazione.

"dataFlows": [ 
    { 
        "streams": [ 
        "Microsoft-Syslog" 
        ], 
        "transformKql": "source | where message has 'error'", 
        "destinations": [ 
        "centralWorkspace" 
        ] 
    } 
]

Creare un DCR per la trasformazione dell'area di lavoro

La regola di raccolta dati (DCR) della trasformazione dell'area di lavoro è una DCR speciale applicata direttamente a un'area di lavoro Log Analytics. Può esistere una sola trasformazione dell'area di lavoro DCR per ogni area di lavoro, ma può includere trasformazioni per un numero qualsiasi di tabelle.

Usare uno dei metodi seguenti per creare un record di dominio di trasformazione dell'area di lavoro per l'area di lavoro e aggiungervi una o più trasformazioni.

È possibile creare un DCR di trasformazione dell'area di lavoro nel portale di Azure aggiungendo una trasformazione a una tabella supportata.

  1. Nel menu Aree di lavoro Log Analytics della portale di Azure selezionare Tabelle. Fare clic a destra della tabella a cui si è interessati e selezionare Crea trasformazione.

    Screenshot che mostra l'opzione per creare una trasformazione per una tabella nel portale di Azure.

  2. Se il DCR della trasformazione dell'area di lavoro non è già stato creato per questa area di lavoro, selezionare l'opzione per crearne una. Se è già stato creato, il DCR sarà già selezionato. Ogni area di lavoro può avere un solo controller di dominio di trasformazione dell'area di lavoro.

    Il ritaglio di schermata mostra la creazione di una nuova regola di raccolta dati.

  3. Selezionare Avanti per visualizzare i dati di esempio della tabella. Fare clic su Editor trasformazione per definire la query di trasformazione.

    Screenshot che mostra i dati di esempio della tabella di log.

  4. È quindi possibile modificare ed eseguire la query di trasformazione per visualizzare i risultati rispetto ai dati effettivi della tabella. Continuare a modificare e testare la query finché non si ottengono i risultati desiderati.

  5. Quando si è soddisfatti della query, fare clic su Applica e quindi su Avanti e crea per salvare il record di controllo di dominio con la nuova trasformazione.

    Screenshot che mostra il salvataggio della trasformazione.

Ottimizzare e monitorare le trasformazioni

Le trasformazioni eseguono una query KQL su ogni record raccolto con il DCR, quindi è importante che vengano eseguite in modo efficiente. Il tempo di esecuzione della trasformazione contribuisce alla latenza complessiva di inserimento dei dati e alle trasformazioni che richiedono tempo eccessivo per l'esecuzione possono influire sulle prestazioni della pipeline di raccolta dati e comportano una perdita di dati. L'esecuzione delle trasformazioni ottimali non deve richiedere più di 1 secondo. Vedere Ottimizzare le query di log in Monitoraggio di Azure per indicazioni sul test della query prima di implementarla come trasformazione e per consigli sull'ottimizzazione delle query che non vengono eseguite in modo efficiente.

Importante

È possibile che si verifichi una perdita di dati se una trasformazione richiede più di 20 secondi.

Poiché le trasformazioni non vengono eseguite in modo interattivo, è importante monitorarle continuamente per assicurarsi che vengano eseguite correttamente e non impiegano tempo eccessivo per elaborare i dati. Per informazioni dettagliate sui log e sulle metriche che monitorano l'integrità e le prestazioni delle trasformazioni, vedere Monitorare e risolvere i problemi di raccolta dei dati DCR in Monitoraggio di Azure. Ciò include l'identificazione di eventuali errori che si verificano nel KQL e nelle metriche per tenere traccia della durata di esecuzione.

Le metriche seguenti vengono raccolte automaticamente per le trasformazioni e devono essere esaminate regolarmente per verificare che le trasformazioni siano ancora in esecuzione come previsto. Creare regole di avviso per le metriche per ricevere una notifica automatica quando una di queste metriche supera una soglia.

  • Durata della trasformazione dei log al minuto
  • Errori di trasformazione dei log al minuto

Abilitare i log degli errori del Registro Azure Container per tenere traccia di eventuali errori che si verificano nelle trasformazioni o in altre query. Creare una regola di avviso del log per ricevere automaticamente una notifica quando viene scritta una voce in questa tabella.

Indicazioni

Esistono più metodi per creare trasformazioni a seconda del metodo di raccolta dati. Nella tabella seguente sono elencate le linee guida per diversi metodi per la creazione di trasformazioni.

Raccolta dati Riferimento
API di inserimento dei log Inviare dati ai log di Monitoraggio di Azure usando l'API REST (portale di Azure)
Inviare dati ai log di Monitoraggio di Azure usando l'API REST (modelli di Azure Resource Manager)
Macchina virtuale con l'agente di Monitoraggio di Azure Aggiungere trasformazione al log di Monitoraggio di Azure
Cluster Kubernetes con Informazioni dettagliate sui contenitori Trasformazioni dei dati in Container Insights
Hub eventi di Azure Esercitazione: Inserire eventi da Hub eventi di Azure nei log di Monitoraggio di Azure (anteprima pubblica)

Passaggi successivi