Eseguire la migrazione dall'API dell'agente di raccolta dati HTTP all'API di inserimento log per inviare dati ai log di Monitoraggio di Azure
L'API di inserimento log di Monitoraggio di Azure offre maggiore potenza di elaborazione e maggiore flessibilità nell'inserimento di log e la gestione delle tabelle rispetto all'API dell'agente di raccolta dati HTTP legacy. Questo articolo descrive le differenze tra l'API dell'agente di raccolta dati e l'API di inserimento log e fornisce indicazioni e procedure consigliate per la migrazione alla nuova API di inserimento log.
Nota
In qualità di MVP Microsoft, Morten Waltorp Knudsen contribuito e fornito feedback materiale per questo articolo. Per un esempio di come è possibile automatizzare l'installazione e l'uso continuativo dell'API di inserimento log, vedere Morten disponibile pubblicamente modulo di PowerShell AzLogDcrIngestPS.
Vantaggi dell'API di inserimento log
L'API di inserimento log offre i vantaggi seguenti rispetto all'API dell'agente di raccolta dati:
- Supporta trasformazioni, che consentono di modificare i dati prima dell'inserimento nella tabella di destinazione, inclusi i filtri e la modifica dei dati.
- Consente di inviare dati a più destinazioni.
- Consente di gestire lo schema della tabella di destinazione, inclusi i nomi delle colonne e se aggiungere nuove colonne alla tabella di destinazione quando lo schema dei dati di origine cambia.
Prerequisiti
La procedura di migrazione descritta in questo articolo presuppone che siano disponibili:
- Un'area di lavoro Log Analytics in cui si dispone almeno dei diritti di collaboratore.
- Autorizzazioni per creare regole di raccolta dati nell'area di lavoro Log Analytics.
- Un'applicazione Microsoft Entra per autenticare le chiamate API o qualsiasi altro schema di autenticazione di Resource Manager.
Autorizzazioni obbligatorie
| Azione | Autorizzazioni obbligatorie |
|---|---|
| Creare un endpoint di raccolta dati. | Le autorizzazioni Microsoft.Insights/dataCollectionEndpoints/write, come specificato dal ruolo predefinito Collaboratore per il monitoraggio, ad esempio. |
| Creare o modificare una regola di raccolta dati. | Le autorizzazioni Microsoft.Insights/DataCollectionRules/Write, come specificato dal ruolo predefinito Collaboratore per il monitoraggio, ad esempio. |
| Convertire una tabella che usa l'API dell'agente di raccolta dati in regole di raccolta dati e l'API di inserimento log. | Le autorizzazioni Microsoft.OperationalInsights/workspaces/tables/migrate/action, come specificato dal ruolo predefinito Collaboratore per Log Analytics, ad esempio. |
| Creare nuove tabelle o modificare gli schemi di tabella. | Le autorizzazioni microsoft.operationalinsights/workspaces/tables/write, come specificato dal ruolo predefinito Collaboratore per Log Analytics, ad esempio. |
| Chiamare l'API di inserimento log. | Vedere Assegnare le autorizzazioni a un DCR. |
Creare nuove risorse necessarie per l'API di inserimento log
L'API di inserimento log richiede di creare due nuovi tipi di risorse, che l'API dell'agente di raccolta dati HTTP non richiede:
- Endpoint di raccolta dati, da cui i dati raccolti vengono inseriti nella pipeline per l'elaborazione.
- Regole di raccolta dati, che definiscono trasformazioni dei dati e la tabella di destinazione in cui vengono inseriti i dati.
Eseguire la migrazione di tabelle personalizzate esistenti o creare nuove tabelle
Se si dispone di una tabella personalizzata esistente a cui si inviano dati usando l'API dell'agente di raccolta dati, è possibile:
Eseguire la migrazione della tabella per continuare a inserire i dati nella stessa tabella usando l'API di inserimento log.
Gestire la tabella e i dati esistenti e configurare una nuova tabella in cui inserire i dati usando l'API inserimento log. È quindi possibile eliminare la tabella precedente quando si è pronti.
Questa è l'opzione preferita, soprattutto se è necessario apportare modifiche alla tabella esistente. Le modifiche apportate ai tipi di dati esistenti e a più modifiche dello schema alle tabelle personalizzate dell'API dell'agente di raccolta dati esistenti possono causare errori.
Suggerimento
Per identificare le tabelle che usano l'API dell'agente di raccolta dati, visualizzare le proprietà della tabella. La proprietà Tipo delle tabelle che usano l'API dell'agente di raccolta dati è impostata su Tabella personalizzata (versione classica). Si noti che le tabelle che inseriscono dati usando l'agente di Log Analytics legacy (MMA) hanno anche la proprietà Tipo impostata su tabella personalizzata (classica). Assicurarsi di eseguire la migrazione dall'agente di Log Analytics all'agente di Monitoraggio di Azure prima di convertire le tabelle MMA. In caso contrario, si interromperà l'inserimento di dati in campi personalizzati in queste tabelle dopo la conversione della tabella.
Questa tabella riepiloga le considerazioni da tenere presenti per ogni opzione:
| Migrazione di tabelle | Implementazione affiancata | |
|---|---|---|
| Denominazione di tabella e colonne | Riutilizzare il nome della tabella esistente. Opzioni di denominazione della colonna: - Usare nuovi nomi di colonna e definire una trasformazione per indirizzare i dati in ingresso alla colonna appena denominata. - Continuare a usare i nomi precedenti. |
Impostare liberamente il nome della nuova tabella. È necessario modificare le integrazioni, i dashboard e gli avvisi prima di passare alla nuova tabella. |
| Procedura di migrazione | Migrazione una tantum della tabella. Non è possibile eseguire il rollback di una tabella migrata. | La migrazione può essere eseguita gradualmente, per tabella. |
| Post-migrazione | È possibile continuare a inserire dati usando l'API dell'agente di raccolta dati HTTP con colonne esistenti, ad eccezione delle colonne personalizzate. Inserire dati in nuove colonne usando solo l'API di inserimento log. |
I dati nella tabella precedente sono disponibili fino alla fine del periodo di conservazione. Quando si configura una nuova tabella o si apportano modifiche allo schema, possono essere necessari 10-15 minuti prima che le modifiche ai dati inizino a essere visualizzate nella tabella di destinazione. |
Per convertire una tabella che usa l'API dell'agente di raccolta dati in regole di raccolta dati e l'API di inserimento log, eseguire questa chiamata API alla tabella:
POST https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/tables/{tableName}/migrate?api-version=2021-12-01-preview
Questa chiamata è idempotente, quindi non ha alcun effetto se la tabella è già stata convertita.
La chiamata API abilita tutte le funzionalità dei log personalizzati basate su DCR nella tabella. L'API dell'agente di raccolta dati continuerà a inserire dati in colonne esistenti, ma non creerà nuove colonne. Qualsiasi campo personalizzato definito in precedenza non continuerà a essere popolato. Un altro modo per eseguire la migrazione di una tabella esistente all'uso delle regole di raccolta dati, ma non necessariamente l'API di inserimento log applica una trasformazione dell'area di lavoro alla tabella.
Importante
- I nomi delle colonne devono iniziare con una lettera e possono essere costituiti da un massimo di 45 caratteri alfanumerici e caratteri di sottolineatura (
_). _ResourceId,id,_ResourceId,_SubscriptionId,TenantId,Type,UniqueIdeTitlesono nomi di colonna riservati.- Le colonne personalizzate aggiunte a una tabella di Azure devono avere il suffisso
_CF. - Se si aggiorna lo schema della tabella nell'area di lavoro Log Analytics, è necessario aggiornare anche la definizione del flusso di input nella regola di raccolta dati per inserire i dati in colonne nuove o modificate.
Chiamare l'API di inserimento log
L'API di inserimento log consente di inviare fino a 1 MB di dati compressi o non compressi per ogni chiamata. Se è necessario inviare più di 1 MB di dati, è possibile inviare più chiamate in parallelo. Si tratta di una modifica rispetto all'API dell'agente di raccolta dati, che consente di inviare fino a 32 MB di dati per ogni chiamata.
Per informazioni su come chiamare l'API di inserimento log, vedere Chiamata all'API REST di inserimento log.
Modificare regole di raccolta dati e schemi di tabella in base alle modifiche apportate all'oggetto dati di origine
Anche se l'API dell'agente di raccolta dati regola automaticamente lo schema della tabella di destinazione quando lo schema dell'oggetto dati di origine cambia, l'API di inserimento log non viene modificata. In questo modo non si raccolgono nuovi dati in colonne che non si intende creare.
Quando lo schema dei dati di origine viene modificato, è possibile:
- Modificare gli schemi della tabella di destinazione e le regole di raccolta dati per allinearsi alle modifiche dello schema dei dati di origine.
- Definire una trasformazione nella regola di raccolta dati per inviare i nuovi dati alle colonne esistenti nella tabella di destinazione.
- Lasciare invariata la tabella di destinazione e la regola di raccolta dati. In questo caso, non verranno inseriti i nuovi dati.
Nota
Non è possibile riutilizzare un nome di colonna con un tipo di dati diverso dal tipo di dati originale definito per la colonna.