Sammeln von Protokollen aus einer JSON-Datei mit dem Azure Monitor-Agent

Benutzerdefinierte JSON-Protokolle 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 Text- und JSON-Protokolltyp.

Viele Anwendungen und Dienste protokollieren Informationen nicht in Standardprotokollierungsdiensten wie dem Windows-Ereignisprotokoll oder Syslog, sondern in JSON-Dateien. 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 JSON-Datei.

1. Der Agent überwacht alle Protokolldateien, die einem angegebenen Namensmuster auf dem lokalen Datenträger entsprechen.
2. Jeder Eintrag im Protokoll wird gesammelt und an Azure Monitor gesendet. Der vom Benutzer definierte eingehende Datenstrom wird verwendet, um die Protokolldaten in Spalten zu parsen.
3. Eine Standardtransformation wird verwendet, wenn das Schema des eingehenden Datenstroms mit dem Schema der Zieltabelle übereinstimmt.

Anforderungen an die JSON-Datei 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.
• JSON-Text muss in einer einzelnen Zeile enthalten sein. Das JSON-Textformat wird nicht unterstützt. Siehe Beispiel unten.

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.

Benutzerdefinierte Tabelle

Bevor Sie Protokolldaten aus einer JSON-Datei 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 Spalten im eingehenden Datenstrom übereinstimmen, oder Sie müssen eine Transformation hinzufügen, um sicherzustellen, dass das Ausgabeschema der Tabelle entspricht. Sie können beispielsweise das folgende PowerShell-Skript verwenden, um eine benutzerdefinierte Tabelle mit mehreren Spalten zu erstellen.

$tableParams = @'
{
    "properties": {
        "schema": {
               "name": "{TableName}_CL",
               "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "DateTime"
                    }, 
                    {
                        "name": "MyStringColumn",
                        "type": "string"
                    },
                    {
                        "name": "MyIntegerColumn",
                        "type": "int"
                    },
                    {
                        "name": "MyRealColumn",
                        "type": "real"
                    },
                    {
                        "name": "MyBooleanColumn",
                        "type": "bool"
                    },
                    {
                        "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 JSON-Datei

Hinweis

Die Agent-basierte Erfassung der benutzerdefinierten JSON-Datei befindet sich derzeit in der Vorschau und bietet noch keine vollständige Benutzeroberfläche im Portal. Sie können die DCR zwar über das Portal erstellen, aber Sie müssen sie ändern, um die Spalten im eingehenden Datenstrom zu definieren. Ausführliche Informationen zum Erstellen der erforderlichen DCR finden Sie unter Resource Manager-Vorlage.

Eingehender Stream

JSON-Dateien enthalten einen Eigenschaftsnamen mit jedem Wert, und der eingehende Datenstrom in der DCR muss eine Spalte enthalten, die dem Namen jeder Eigenschaft entspricht. Wenn Sie die DCR mithilfe des Azure-Portals erstellen, sind die Spalten in der folgenden Tabelle im eingehenden Datenstrom enthalten, und Sie müssen die DCR manuell ändern oder mithilfe einer anderen Methode erstellen, mit der Sie den eingehenden Datenstrom explizit definieren können.

Spalte	Type	BESCHREIBUNG
TimeGenerated	datetime	Dies ist der Zeitpunkt, zu dem der Datensatz generiert wurde.
RawData	Zeichenfolge	Diese Spalte ist für ein JSON-Protokoll leer.
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.

Portal

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 JSON-Protokolle 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.json – C:\Logs\MyLog*.json – C:\App01\AppLog.json, C:\App02\AppLog.json – /var/mylog.json – /var/mylog*.json
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.

Resource Manager: Vorlage

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

• columns: Ändern Sie diesen Wert mithilfe der Liste der Spalten im JSON-Protokoll, das Sie sammeln.
• transformKql: Ändern Sie die Standardtransformation, wenn das Schema des eingehenden Datenstroms nicht mit dem Schema der Zieltabelle übereinstimmt. 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-JSONLog-stream": {
                        "columns": [
                            {
                                "name": "TimeGenerated",
                                "type": "datetime"
                            },
                            {
                                "name": "FilePath",
                                "type": "String"
                            },
                            {
                                "name": "Computer",
                                "type": "String"
                            },
                            {
                                "name": "MyStringColumn",
                                "type": "string"
                            },
                            {
                                "name": "MyIntegerColumn",
                                "type": "int"
                            },
                            {
                                "name": "MyRealColumn",
                                "type": "real"
                            },
                            {
                                "name": "MyBooleanColumn",
                                "type": "bool"
                            }
                        ]
                    }
                },
                "dataSources": {
                    "logFiles": [
                        {
                            "streams": [
                                "Custom-Json-stream"
                            ],
                            "filePatterns": [
                                "[parameters('filePatterns')]"
                            ],
                            "format": "json",
                            "name": "Custom-Json-dataSource"
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId":  "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-Json-dataSource"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
            }
        }
    ]
}

Problembehandlung

Führen Sie die folgenden Schritte aus, wenn Sie nicht die erwarteten Daten aus dem JSON-Protokoll 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.
• Vergewissern Sie sich, dass das Schema des eingehenden Datenstroms in der DCR mit dem Schema in der Protokolldatei übereinstimmt.
• Ü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:

• Azure Monitor-Agent
• Datensammlungsregeln
• Bewährte Methoden für die Kostenverwaltung in Azure Monitor