Sammeln von Protokollen aus einer Textdatei mit dem Azure Monitor-Agent

Artikel
11/04/2024

Benutzerdefinierte Textprotokolle sind eine der Datenquellen, die in einer Datensammlungsregel (Data Collection Rule, DCR) verwendet werden. Details zur Erstellung der DCR finden Sie unter Sammeln von Daten mit dem Azure Monitor-Agent. Dieser Artikel enthält zusätzliche Details für den Textprotokolltyp.

Viele Anwendungen und Dienste protokollieren Informationen nicht in Standardprotokollierungsdiensten wie dem Windows-Ereignisprotokoll oder Syslog, sondern in Textdateien. Diese Daten können mit dem Azure Monitor-Agent gesammelt und in einem Log Analytics-Arbeitsbereich mit Daten aus anderen Quellen gespeichert werden.

Voraussetzungen

Log Analytics-Arbeitsbereich, in dem Sie mindestens über die Berechtigung „Mitwirkender“ verfügen.
Der Datensammlungsendpunkt (Data Collection Endpoint, DCE) muss sich in derselben Region befinden wie der Log Analytics-Arbeitsbereich. Weitere Informationen finden Sie unter Einrichten von Datensammlungsendpunkten basierend auf Ihrer Bereitstellung.
Entweder eine neue oder vorhandene DCR (unter Sammeln von Daten mit dem Azure Monitor-Agent beschrieben)

Grundlegender Vorgang

Das folgende Diagramm zeigt den grundlegenden Vorgang zum Sammeln von Protokolldaten aus einer Textdatei.

Der Agent überwacht alle Protokolldateien, die einem angegebenen Namensmuster auf dem lokalen Datenträger entsprechen.
Jeder Eintrag im Protokoll wird gesammelt und an Azure Monitor gesendet. Der eingehende Datenstrom enthält den gesamten Protokolleintrag in einer einzelnen Spalte.
Wenn die Standardtransformation verwendet wird, wird der gesamte Protokolleintrag an eine einzelne Spalte in der Zieltabelle gesendet.
Wenn eine benutzerdefinierte Transformation verwendet wird, kann der Protokolleintrag in mehrere Spalten in der Zieltabelle geparst werden.

Anforderungen an die Textdatei und Best Practices

Die Datei, die der Azure Monitor-Agent überwacht, muss die folgenden Anforderungen erfüllen:

Die Datei muss auf dem lokalen Laufwerk des Computers mit dem Azure Monitor-Agent im überwachten Verzeichnis gespeichert werden.
Jeder Datensatz muss mit einem Zeilenende abgegrenzt werden.
Die Datei muss die ASCII- oder UTF-8-Codierung verwenden. Andere Formate wie UTF-16 werden nicht unterstützt.
Neue Datensätze sollten am Ende der Datei angefügt werden und alte Datensätze nicht überschreiben. Das Überschreiben führt zu Datenverlusten.

Befolgen Sie diese Empfehlungen, um sicherzustellen, dass keine Datenverluste oder Leistungsprobleme auftreten:

Erstellen Sie täglich eine neue Protokolldatei, damit Sie ganz einfach alte Dateien bereinigen können.
Bereinigen Sie Protokolldateien im überwachten Verzeichnis kontinuierlich. Die Nachverfolgung vieler Protokolldateien kann die CPU- und Arbeitsspeicherauslastung des Agents erhöhen. Warten Sie mindestens 2 Tage, dass ausreichend Zeit für die Verarbeitung aller Protokolle vorhanden ist.
Ändern Sie den Namen einer Datei, der dem Dateisuchmuster entspricht, nicht in einen anderen Namen, der dem Dateisuchmuster ebenfalls entspricht. Dies führt dazu, dass doppelte Daten erfasst werden.
Benennen Sie keine großen Protokolldateien um, die dem Dateisuchmuster entsprechen, und kopieren Sie sie nicht in das überwachte Verzeichnis. Wenn Sie dies tun müssen, dürfen 50 MB pro Minute nicht überschritten werden.

Eingehender Stream

Hinweis

Die Multilineunterstützung, die einen Zeitstempel zum Trennen von Ereignissen verwendet, ist jetzt verfügbar. Sie müssen eine Bereitstellung von Ressourcenverwaltungsvorlagen verwenden, bis die Unterstützung in der Portal-Benutzeroberfläche hinzugefügt wird.

Der eingehende Datenstrom enthält die Spalten in der folgenden Tabelle.

Spalte	Type	BESCHREIBUNG
`TimeGenerated`	datetime	Dies ist der Zeitpunkt, zu dem der Datensatz generiert wurde. Dieser Wert wird automatisch mit dem Zeitpunkt aufgefüllt, zu dem der Datensatz dem Log Analytics-Arbeitsbereich hinzugefügt wird. Sie können diesen Wert mithilfe einer Transformation außer Kraft setzen, um `TimeGenerated` auf einen anderen Wert festzulegen.
`RawData`	Zeichenfolge	Dies ist der gesamte Protokolleintrag in einer einzelnen Spalte. Sie können eine Transformation verwenden, wenn Sie diese Daten vor dem Senden an die Tabelle in mehrere Spalten aufteilen möchten.
`FilePath`	Zeichenfolge	Wenn Sie diese Spalte zum eingehenden Datenstrom in der DCR hinzufügen, wird sie mit dem Pfad zur Protokolldatei aufgefüllt. Diese Spalte wird nicht automatisch erstellt und kann nicht mithilfe des Portals hinzugefügt werden. Sie müssen die vom Portal erstellte DCR manuell ändern oder die DCR mithilfe einer anderen Methode erstellen, mit der Sie den eingehenden Datenstrom explizit definieren können.
`Computer`	Zeichenfolge	Wenn Sie diese Spalte dem eingehenden Datenstrom in der DCR hinzufügen, wird sie mit dem Namen des Computers mit der Protokolldatei aufgefüllt. Diese Spalte wird nicht automatisch erstellt und kann nicht mithilfe des Portals hinzugefügt werden. Sie müssen die vom Portal erstellte DCR manuell ändern oder die DCR mithilfe einer anderen Methode erstellen, mit der Sie den eingehenden Datenstrom explizit definieren können.

Benutzerdefinierte Tabelle

Bevor Sie Protokolldaten aus einer Textdatei sammeln können, müssen Sie eine benutzerdefinierte Tabelle in Ihrem Log Analytics-Arbeitsbereich erstellen, um die Daten zu empfangen. Das Tabellenschema muss mit den Daten übereinstimmen, die Sie sammeln, oder Sie müssen eine Transformation hinzufügen, um sicherzustellen, dass das Ausgabeschema der Tabelle entspricht.

Warnung

Um Datenverluste zu vermeiden, ist es wichtig, dass Sie keine vorhandene benutzerdefinierte Protokolltabelle verwenden, die MMA-Agents derzeit verwenden. Sobald ein AMA-Agent in eine vorhandene benutzerdefinierte Protokolltabelle schreibt, können MMA-Agents nicht mehr in diese Tabelle schreiben. Stattdessen sollten Sie eine neue Tabelle speziell für AMA-Agents erstellen, um einen reibungslosen Übergang von einem Agent zum Nächsten sicherzustellen.

Sie können beispielsweise das folgende PowerShell-Skript verwenden, um eine benutzerdefinierte Tabelle mit RawData, FilePath und Computer zu erstellen. Sie benötigen keine Transformation für diese Tabelle, da das Schema dem Standardschema des eingehenden Datenstroms entspricht.

$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

Erstellen einer Datensammlungsregel für eine Textdatei

Portal
Resource Manager: Vorlage

Erstellen Sie wie unter Sammeln von Daten mit dem Azure Monitor-Agent beschrieben eine Datensammlungsregel. Wählen Sie im Schritt Sammeln und übermitteln die Option Benutzerdefinierte Textprotokolle aus der Dropdownliste Datenquellentyp aus.

Einstellung	Beschreibung
Dateimuster	Hiermit wird der Speicherort und der Namen von Protokolldateien auf dem lokalen Datenträger angegeben. Verwenden Sie variierende Platzhalter für Dateinamen (z. B. ein neuer Name, wenn täglich eine neue Datei erstellt wird). Sie können mehrere Dateimuster durch Komma getrennt eingeben. Beispiele: – C:\Logs\MyLog.txt – C:\Logs\MyLog.txt – C:\App01\AppLog.txt, C:\App02\AppLog.txt – /var/mylog.log – /var/mylog.log
Tabellenname	Dies ist der Name der Zieltabelle in Ihrem Log Analytics-Arbeitsbereich.
Datensatztrennzeichen	Dieses Element wird derzeit nicht verwendet, ist aber für die zukünftige potenzielle Verwendung reserviert, sodass andere Trennzeichen als das derzeit unterstützte Zeilenende (`/r/n`) zulässig sind.
Transformieren	Dies ist die Erfassungszeittransformation zum Filtern von Datensätzen oder zum Formatieren der eingehenden Daten für die Zieltabelle. Verwenden Sie `source`, um die eingehenden Daten unverändert zu lassen.

Verwenden Sie die folgende ARM-Vorlage, um eine Datensammlungsregel zum Sammeln von Textprotokolldateien zu erstellen. Nehmen Sie dabei die in den vorherigen Abschnitten beschriebenen Änderungen vor. In der folgenden Tabelle werden die Parameter beschrieben, die Werte erfordern, wenn Sie die Vorlage bereitstellen.

Einstellung	Beschreibung
Dateimuster	Hiermit wird der Speicherort und der Namen von Protokolldateien auf dem lokalen Datenträger angegeben. Verwenden Sie variierende Platzhalter für Dateinamen (z. B. ein neuer Name, wenn täglich eine neue Datei erstellt wird). Sie können mehrere Dateimuster durch Komma getrennt eingeben. Beispiele: – C:\Logs\MyLog.txt – C:\Logs\MyLog.txt – C:\App01\AppLog.txt, C:\App02\AppLog.txt – /var/mylog.log – /var/mylog.log
Tabellenname	Dies ist der Name der Zieltabelle in Ihrem Log Analytics-Arbeitsbereich.
Datensatztrennzeichen	Dieses Element wird derzeit nicht verwendet, ist aber für die zukünftige potenzielle Verwendung reserviert, sodass andere Trennzeichen als das derzeit unterstützte Zeilenende (`/r/n`) zulässig sind.
Transformieren	Dies ist die Erfassungszeittransformation zum Filtern von Datensätzen oder zum Formatieren der eingehenden Daten für die Zieltabelle. Verwenden Sie `source`, um die eingehenden Daten unverändert zu lassen.
TimeFormat	Die folgenden Formate werden unterstützt. Verwenden Sie die Anführungszeichenfolgen in Ihrer ARM-Vorlage. Schließen Sie nicht die Beispielzeit aus den Klammern ein. - „yyyy-MM-ddTHH:mm:ssk“ (2024-10-29T18:28:34) - „YYYY-MM-DD HH:MM:SS“ (2024-10-29 18:28:34) - „M/D/YYYY HH:MM:SS AM/PM“ (10/29/2024 06:28:34 PM) - „Mon DD, YYYY HH:MM:SS“ (Okt[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“ (Okt 29 18:28:34) - „dd/MMM/yyyy:HH:mm:ss zzz“ (14. Okt 2024:18:28:34 -000)

Verwenden Sie die folgende ARM-Vorlage, um eine DCR zum Sammeln von Textprotokolldateien zu erstellen oder zu ändern. Zusätzlich zu den Parameterwerten müssen Sie möglicherweise die folgenden Werte in der Vorlage ändern:

columns: Entfernen Sie die FilePath-Spalte, wenn Sie sie nicht sammeln möchten.
transformKql: Ändern Sie die Standardtransformation, wenn Sie den eingehenden Datenstrom ändern oder filtern möchten, um beispielsweise den Protokolleintrag in mehrere Spalten zu parsen. Das Ausgabeschema der Transformation muss mit dem Schema der Zieltabelle übereinstimmen.

Wichtig

Wenn Sie die DCR mit einer ARM-Vorlage erstellen, müssen Sie die DCR trotzdem den Agents zuordnen, die sie verwenden. Sie können die DCR im Azure-Portal bearbeiten und die Agents auswählen, wie unter Hinzufügen von Ressourcen beschrieben. Der Abschnitt der Parameter im DCR ist optional, wenn Sie sie durch Zeichenfolgen weiter unten im JSON-Code ersetzen.

{
    "$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')]"
                    }
                ]
            }
        }
    ]
}

Durch Trennzeichen getrennte Protokolldateien

Viele Textprotokolldateien enthalten Einträge, die durch ein Zeichen wie ein Komma getrennt sind. Verwenden Sie zum Parsen dieser Daten in separate Spalten eine Transformation mit der split-Funktion.

Sehen Sie sich beispielsweise eine Textdatei mit den folgenden durch Kommas getrennten Daten an. Diese Felder können wie folgt beschrieben werden: Time, Code, Severity, Module und 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.

Die folgende Transformation parst die Daten in separate Spalten. Da split dynamische Daten zurückgibt, müssen Sie Funktionen wie tostring und toint verwenden, um die Daten in den richtigen Skalartyp zu konvertieren. Sie müssen auch einen Namen für jeden Eintrag angeben, der dem Spaltennamen in der Zieltabelle entspricht. Beachten Sie, dass in diesem Beispiel ein TimeGenerated-Wert bereitgestellt wird. Wenn dieser nicht angegeben wurde, wird die Erfassungszeit verwendet.

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

Wenn Sie diese Daten mit einer Protokollabfrage abrufen, werden die folgenden Ergebnisse zurückgegeben.

Problembehandlung

Führen Sie die folgenden Schritte aus, wenn Sie nicht die erwarteten Daten aus dem Textprotokoll sammeln.

Vergewissern Sie sich, dass Daten in die erfasste Protokolldatei geschrieben werden.
Stellen Sie sicher, dass der Name und Speicherort der Protokolldatei dem von Ihnen angegebenen Dateimuster entspricht.
Überprüfen Sie, ob das Schema der Zieltabelle dem eingehenden Datenstrom entspricht oder Sie über eine Transformation verfügen, die den eingehenden Datenstrom in das richtige Schema konvertiert.
Unter Vorgang überprüfen können Sie überprüfen, ob der Agent funktioniert und Daten empfangen werden.

Nächste Schritte

Weitere Informationen:

Teilen über