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

Artikel
07/23/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.
Datensammlungsendpunkt (Data Collection Endpoint, DCE), wenn Sie beabsichtigen, private Azure Monitor-Links zu verwenden. Der Datensammlungsendpunkt 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

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 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: Sie sollten keine vorhandene benutzerdefinierte Protokolltabelle verwenden, die von MMA-Agents verwendet wird. Ihre MMA-Agents können nicht mehr in die Tabelle schreiben, sobald der erste AMA-Agent in die Tabelle schreibt. Sie sollten eine neue Tabelle für AMA erstellen, um MMA-Datenverluste zu verhindern.

Sie können beispielsweise das folgende PowerShell-Skript verwenden, um eine benutzerdefinierte Tabelle mit RawData und FilePath 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 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).

{
    "$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. "
            },
        },
        "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."
            },
        }
    },
    "variables": {
      "tableOutputStream": "['Custom-',concat(parameters('tableName'))]"
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2022-06-01",
            "properties": {
                "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"
                        }
                    ]
                },
                "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:

Freigeben über