Raccogliere log da un file di testo con l'agente di Monitoraggio di Azure

Articolo
10/31/2024

I log di testo personalizzati sono una delle origini dati usate in una regola di raccolta dati (DCR). Ulteriori dettagli sulla creazione di DCR sono disponibili in Raccogliere dati con l'agente di Monitoraggio di Azure. Questo articolo fornisce dettagli aggiuntivi per il tipo di log di testo.

Molte applicazioni e servizi registreranno le informazioni in file di testo invece di servizi di registrazione standard, ad esempio registro eventi di Windows o Syslog. Questi dati possono essere raccolti con l'agente di Monitoraggio di Azure e archiviati in un'area di lavoro Log Analytics con i dati raccolti da altre origini.

Prerequisiti

Un'area di lavoro Log Analytics in cui si dispone almeno dei diritti di collaboratore.
L'endpoint di raccolta dei dati (DCE) deve trovarsi nella stessa area dell'area di lavoro Log Analytics. Per informazioni dettagliate, vedere Come configurare gli endpoint di raccolta dati in base alla distribuzione.
Un record di controllo di dominio nuovo o esistente descritto in Raccogliere dati con l'agente di Monitoraggio di Azure.

Operazione di base

Il diagramma seguente illustra l'operazione basilare di raccolta dei dati di log da un file di testo.

L'agente controlla tutti i file di log che corrispondono a un pattern di nomi specificato nel disco locale.
Ogni voce nel log viene raccolta e inviata a Monitoraggio di Azure. Il flusso in ingresso include l'intera voce di log in una singola colonna.
Se la trasformazione predefinita è in uso, l'intera voce di log viene inviata a una singola colonna nella tabella di destinazione.
Se una trasformazione personalizzata è in uso, la voce di log può essere analizzata in più colonne nella tabella di destinazione.

Requisiti e procedure consigliate per file di testo

Il file monitorato dall'agente di Monitoraggio di Azure deve soddisfare i requisiti seguenti:

Il file deve essere archiviato nell'unità locale del computer con l'agente di Monitoraggio di Azure nella directory monitorata.
Ogni record deve essere delineato con una fine riga.
Il file deve usare la codifica ASCII o UTF-8. Non sono supportati altri formati, ad esempio UTF-16.
I nuovi record devono essere aggiunti alla fine del file e non sovrascrivere i record precedenti. La sovrascrittura causerà la perdita di dati.

Attenersi alle raccomandazioni seguenti per assicurarsi che non si verifichino perdite di dati o problemi di prestazioni:

Creare un nuovo file di log ogni giorno in modo da poter pulire facilmente i file obsoleti.
Pulire continuamente i file di log nella directory monitorata. Il rilevamento di molti file di log può aumentare l'utilizzo della CPU e della memoria dell'agente. Attendere almeno 2 giorni per consentire l'elaborazione di tutti i log.
Non rinominare un file che corrisponde al modello di analisi dei file con un altro nome che corrisponde anche al modello di analisi dei file. Ciò potrebbe causare l’inserimento di dati duplicati.
Non rinominare o copiare file di log di grandi dimensioni che corrispondono al modello di analisi dei file nella directory monitorata. Se necessario, non superare i 50 MB al minuto.

Flusso in ingresso

Nota

È ora disponibile il supporto multilinea che usa un timestamp per gli eventi delimitati. È necessario usare una distribuzione di modelli di gestione delle risorse fino a quando non viene aggiunto il supporto nell'interfaccia utente del portale.

Il flusso di dati in ingresso include le colonne nella tabella seguente.

Column	Type	Descrizione
`TimeGenerated`	datetime	Ora in cui è stato generato il record. Questo valore verrà popolato automaticamente con l'ora in cui il record viene aggiunto all'area di lavoro Log Analytics. È possibile eseguire l'override di questo valore usando una trasformazione per impostare `TimeGenerated` su un altro valore.
`RawData`	string	L'intera voce di log in una singola colonna. Se si desidera suddividere questi dati in più colonne prima dell'invio alla tabella, è possibile usare una trasformazione.
`FilePath`	string	Se si aggiunge questa colonna al flusso in ingresso nella regola di raccolta dati, verrà popolata con il percorso del file di log. Questa colonna non viene creata automaticamente e non può essere aggiunta tramite il portale. È necessario modificare manualmente la regola di raccolta dati creata dal portale o creare la regola di raccolta dati usando un altro metodo in cui è possibile definire in modo esplicito il flusso in ingresso.
`Computer`	string	Se si aggiunge questa colonna al flusso in ingresso nella DCR, verrà popolata con il nome del computer con il file di log. Questa colonna non viene creata automaticamente e non può essere aggiunta tramite il portale. È necessario modificare manualmente il DCR creato dal portale o creare il DCR usando un altro metodo in cui è possibile definire in modo esplicito il flusso in ingresso.

Tabella personalizzata

Prima di poter raccogliere dati di log da un file di testo, è necessario creare una tabella personalizzata nell'area di lavoro Log Analytics per ricevere i dati. Lo schema della tabella deve corrispondere ai dati raccolti, oppure è necessario aggiungere una trasformazione per assicurarsi che lo schema di output corrisponda alla tabella.

Avviso

Per evitare la perdita di dati, è importante non usare una tabella di log personalizzata esistente attualmente utilizzata da agenti MMA. Dopo che qualsiasi agente AMA scrive in una tabella di log personalizzata esistente, gli agenti MMA non potranno più scrivere in tale tabella. È invece necessario creare una nuova tabella specifica per gli agenti AMA per garantire una transizione uniforme da un agente a quello successivo.

Ad esempio, è possibile usare lo script di PowerShell seguente per creare una tabella personalizzata con RawData, FilePath e Computer. Non sarebbe necessaria una trasformazione per questa tabella, poiché lo schema corrisponde allo schema predefinito del flusso in ingresso.

$tableParams = @'
{
    "properties": {
        "schema": {
               "name": "{TableName}_CL",
               "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "DateTime"
                    }, 
                    {
                        "name": "RawData",
                        "type": "String"
                    },
                    {
                        "name": "FilePath",
                        "type": "String"
                    },
                    {
                        "name": "Computer",
                        "type": "String"
                    }
              ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{WorkspaceName}/tables/{TableName}_CL?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

Creare una regola di raccolta dati per un file di testo

Portale
Modello di Resource Manager

Creare una regola di raccolta dati, come descritto in Raccogliere dati con l'agente di Monitoraggio di Azure. Nel passaggio Raccogli e recapita, selezionare Log di testo personalizzati dall'elenco a discesa Tipo di origine dati.

Impostazione	Descrizione
Pattern di file	Identifica il percorso e il nome di file di log nel disco locale. Usare un carattere jolly per nomi di file che variano, ad esempio quando viene creato un nuovo file ogni giorno con un nuovo nome. È possibile immettere più pattern di file separati da virgole. Esempi: - C:\Logs\MyLog.txt - C:\Logs\MyLog.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog.log
Nome tabella	Nome della tabella di destinazione nell'area di lavoro Log Analytics.
Delimitatore di record	Non attualmente usato, ma è riservato per potenziali usi futuri che consentiranno delimitatori diversi dalla fine riga attualmente supportata (`/r/n`).
Trasformazione	Trasformazione in fase di inserimento per filtrare i record o per formattare i dati in ingresso per la tabella di destinazione. Usare `source` per lasciare invariati i dati in ingresso.

Usare il modello ARM seguente per creare un DCR per la raccolta di file di log di testo, apportando le modifiche descritte nelle sezioni precedenti. Nella tabella seguente vengono descritti i parametri che richiedono valori quando si distribuisce il modello.

Impostazione	Descrizione
Pattern di file	Identifica il percorso e il nome di file di log nel disco locale. Usare un carattere jolly per nomi di file che variano, ad esempio quando viene creato un nuovo file ogni giorno con un nuovo nome. È possibile immettere più pattern di file separati da virgole. Esempi: - C:\Logs\MyLog.txt - C:\Logs\MyLog.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog.log
Nome tabella	Nome della tabella di destinazione nell'area di lavoro Log Analytics.
Delimitatore di record	Non attualmente usato, ma è riservato per potenziali usi futuri che consentiranno delimitatori diversi dalla fine riga attualmente supportata (`/r/n`).
Trasformazione	Trasformazione in fase di inserimento per filtrare i record o per formattare i dati in ingresso per la tabella di destinazione. Usare `source` per lasciare invariati i dati in ingresso.
timeFormat	Sono supportati i formati seguenti. Usare le virgolette nel modello di Resource Manager. Non includere l'ora di esempio racchiusa tra parentesi. - "aaaa-MM-ggTHH:mm:ssk" (2024-10-29T18:28:34) - "AAAA-MM-GG HH:MM:SS" (2024-10-29 18:28:34) - "M/D/AAAA HH:MM:SS AM/PM" (10/29/2024 06:28:34 PM) - "Mon DD, AAAA HH:MM:SS" (oct[ober] 29, 2024 18:28:34) - "yyMMdd HH:mm:ss" (241029 18:28:34) - "ddMMyy HH:mm:ss" (291024 18:28:34) - "MMM d HH:mm:ss" (29 ottobre 18:28:34) - "dd/MMM/aaaa:HH:mm:ss zzz" (14/ottobre/2024:18:28:34 -000)

Usare il modello di Resource Manager seguente per creare o modificare un DCR per la raccolta di file di log di testo. Oltre ai valori dei parametri, potrebbe essere necessario modificare i valori seguenti nel modello:

columns: rimuovere la colonna FilePath se non la si vuole raccogliere.
transformKql: modificare la trasformazione predefinita se si desidera modificare o filtrare il flusso in ingresso, ad esempio per analizzare la voce di log in più colonne. Lo schema di output della trasformazione deve corrispondere allo schema della tabella di destinazione.

Importante

Se si crea la regola di raccolta dati usando un modello di Resource Manager, è comunque necessario associare la regola di raccolta dati agli agenti che la useranno. È possibile modificare il DCR nella portale di Azure e selezionare gli agenti come descritto in Aggiungere risorse. La sezione parameters in DCR è facoltativa se le si sostituisce con stringhe inferiori nel codice JSON.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
              "description": "Unique name for the DCR. "
            }
        },
        "dataCollectionEndpointResourceId": {
            "type": "string",
            "metadata": {
              "description": "Resource ID of the data collection endpoint (DCE)."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
              "description": "Region for the DCR. Must be the same location as the Log Analytics workspace. "
            }
        },
        "filePatterns": {
            "type": "string",
            "metadata": {
              "description": "Path on the local disk for the log file to collect. May include wildcards.Enter multiple file patterns separated by commas (AMA version 1.26 or higher required for multiple file patterns on Linux)."
            }
        },
        "tableName": {
            "type": "string",
            "metadata": {
              "description": "Name of destination table in your Log Analytics workspace. "
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
              "description": "Resource ID of the Log Analytics workspace with the target table."
            }
        },
        "timeFormat": {
            "type": "string"
            "metadata": {
                "discription": "The time format that you would like to use to split multi line imput"
            }
      }
    },
    "variables": {
      "tableOutputStream": "[concat('Custom-', parameters('tableName'))]"
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2022-06-01",
            "properties": {
                "dataCollectionEndpointId": "[parameters('dataCollectionEndpointResourceId')]",
                "streamDeclarations": {
                    "Custom-Text-stream": {
                        "columns": [
                            {
                                "name": "TimeGenerated",
                                "type": "datetime"
                            },
                            {
                                "name": "RawData",
                                "type": "string"
                            },
                            {
                                "name": "FilePath",
                                "type": "string"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            }
                        ]
                    }
                },
                "dataSources": {
                    "logFiles": [
                        {
                            "streams": [
                                "Custom-Text-stream"
                            ],
                            "filePatterns": [
                                "[parameters('filePatterns')]"
                            ],
                            "format": "text",
                            "name": "Custom-Text-dataSource",
                            "settings": {
                               "text": {
                                      "recordStartTimestampFormat": "[parameters('timeFormat')]"
                               }
                            }
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-Text-dataSource"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
            }
        }
    ]
}

File di log delimitati

Molti file di log di testo hanno voci delimitate da un carattere, ad esempio una virgola. Per analizzare questi dati in colonne separate, usare una trasformazione con la funzione di divisione.

Si consideri ad esempio un file di testo con i dati delimitati da virgole seguenti. Questi campi possono essere descritti come: Time, Code, Severity, Module e Message.

2024-06-21 19:17:34,1423,Error,Sales,Unable to connect to pricing service.
2024-06-21 19:18:23,1420,Information,Sales,Pricing service connection established.
2024-06-21 21:45:13,2011,Warning,Procurement,Module failed and was restarted.
2024-06-21 23:53:31,4100,Information,Data,Nightly backup complete.

La trasformazione seguente analizza i dati in colonne separate. Poiché split restituisce dati dinamici, è necessario usare funzioni come tostring e toint per convertire i dati nel tipo scalare corretto. È anche necessario specificare un nome per ogni voce corrispondente al nome della colonna nella tabella di destinazione. Notare che questo esempio fornisce un valore TimeGenerated. Se non è stato specificato, verrà usato il tempo di inserimento.

source | project d = split(RawData,",") | project TimeGenerated=todatetime(d[0]), Code=toint(d[1]), Severity=tostring(d[2]), Module=tostring(d[3]), Message=tostring(d[4])

Il recupero di questi dati con una query di log restituirà i risultati seguenti.

Risoluzione dei problemi

Seguire questa procedura se non si stanno raccogliendo dati dal log di testo previsto.

Verificare che i dati vengano scritti nel file di log da raccogliere.
Verificare che il nome e il percorso del file di log corrispondano al pattern di file specificato.
Verificare che lo schema della tabella di destinazione corrisponda al flusso in ingresso o che sia presente una trasformazione che converta il flusso in ingresso nello schema corretto.
Vedere Verificare l'operazione per verificare se l'agente sia operativo e i dati vengano ricevuti.

Passaggi successivi

Altre informazioni su:

Condividi tramite