Tutorial: Hinzufügen einer Transformation in einer Arbeitsbereichs-Datensammlungsregel zu Azure Monitor über Resource Manager-Vorlagen

  • Artikel

Dieses Tutorial führt Sie durch die Konfiguration eines Beispiels für eine Transformation in einer Arbeitsbereich-Datenerfassungsregel mithilfe von Resource Manager-Vorlagen. Transformationen in Azure Monitor ermöglichen es Ihnen, eingehende Daten zu filtern oder zu ändern, bevor sie an ihr Ziel gesendet werden. Arbeitsbereichsumwandlungen bieten Unterstützung für Umwandlungen zur Erfassungszeit für Workflows, die die Azure Monitor-Datenerfassungspipeline noch nicht verwenden.

Workspace-Transformationen werden zusammen in einer einzigen Datenerfassungsregel (DCR) für den Workspace gespeichert, die als Workspace-DCR bezeichnet wird. Jede Transformation ist einer bestimmten Tabelle zugeordnet. Die Transformation wird auf alle Daten angewendet, die von jedem Workflow, der keine DCR verwendet, an diese Tabelle gesendet werden.

Hinweis

Dieses Tutorial verwendet Resource Manager-Vorlagen und die REST-API, um eine Arbeitsbereichstransformation zu konfigurieren. Dasselbe Tutorial unter Verwendung des Azure Portals finden Sie hier: Tutorial: Hinzufügen einer Transformation in einer Arbeitsbereichs-Datensammlungsregel zu Azure Monitor über das Azure-Portal.

In diesem Tutorial lernen Sie Folgendes:

  • Konfigurieren Sie Workspace-Transformation für eine Tabelle in einem Log Analytics-Arbeitsbereich.
  • Schreiben Sie eine Protokollabfrage für eine Aufnahmezeittransformation.

Hinweis

In diesem Tutorial wird PowerShell aus Azure Cloud Shell verwendet, um REST-API-Aufrufe mit der Tabellen-API von Azure Monitor und dem Azure-Portal vorzunehmen, um Resource Manager-Vorlagen zu installieren. Sie können jede beliebige andere Methode verwenden, um diese Aufrufe vorzunehmen.

Voraussetzungen

Um dieses Tutorial abzuschließen, benötigen Sie Folgendes:

Übersicht über das Tutorial

In diesem Tutorial verringern Sie den Speicherbedarf für die Tabelle LAQueryLogs, indem Sie bestimmte Datensätze herausfiltern. Außerdem entfernen Sie beim Analysieren der Spaltendaten den Inhalt einer Spalte, um ein Datenelement in einer benutzerdefinierten Spalte zu speichern. Die Tabelle „LAQueryLogs“ wird erstellt, wenn Sie die Protokollabfrageüberwachung in einem Arbeitsbereich aktivieren. Dies wird jedoch nur als Beispiel für das Tutorial verwendet. Sie können denselben grundlegenden Prozess verwenden, um eine Transformation für eine beliebige unterstützte Tabelle in einem Log Analytics-Arbeitsbereich zu erstellen.

Aktivieren von Abfrageüberwachungsprotokollen

Sie müssen die Abfrageüberwachung für Ihren Arbeitsbereich aktivieren, um die Tabelle LAQueryLogs zu erstellen, mit der Sie anschließend arbeiten. Dies ist nicht für alle Erfassungszeittransformationen erforderlich. Es dient lediglich zum Generieren der Beispieldaten, die in dieser Beispieltransformation verwendet werden.

  1. Wählen Sie im Azure-Portal im Menü Log Analytics-Arbeitsbereiche die Option Diagnoseeinstellungen und dann Diagnoseeinstellung hinzufügen aus.

    Screenshot der Diagnoseeinstellungen.

  2. Geben Sie einen Namen für die Diagnoseeinstellung an, und wählen Sie den Arbeitsbereich aus, damit die Überwachungsdaten im selben Arbeitsbereich gespeichert werden. Wählen Sie die Kategorie Überwachen aus, und klicken Sie dann auf Speichern, um die Diagnoseeinstellung zu speichern und die Seite mit den Diagnoseeinstellungen zu schließen.

    Der Screenshot der neuen Diagnoseeinstellung.

  3. Wählen Sie Protokolle aus, und führen Sie dann einige Abfragen aus, um LAQueryLogs mit einigen Daten zu füllen. Diese Abfragen müssen keine Daten zurückgeben.

    Der Screenshot von Beispielprotokollabfragen.

Aktualisieren von Tabellenschemas

Bevor Sie die Transformation erstellen können, müssen die beiden folgenden Änderungen an der Tabelle vorgenommen werden:

  • Die Tabelle muss für die Workspace-Transformation aktiviert sein. Dies ist für alle Tabellen erforderlich, die eine Transformation aufweisen sollen, auch wenn die Transformation das Schema der Tabelle nicht ändert.
  • Alle zusätzlichen Spalten, die von der Transformation aufgefüllt werden, müssen der Tabelle hinzugefügt werden.

Verwenden Sie die API Tabellen – Aktualisieren, um die Tabelle mit dem unten angegebenen PowerShell-Code zu konfigurieren. Durch Aufrufen der API wird die Tabelle für Workspace-Transformationen aktiviert, unabhängig davon, ob benutzerdefinierte Spalten definiert sind oder nicht. In diesem Beispiel enthält sie eine benutzerdefinierte Spalte namens Resources_CF, die mit der Transformationsabfrage aufgefüllt wird.

Wichtig

Alle benutzerdefinierten Spalten, die einer integrierten Tabelle hinzugefügt werden, müssen mit _CF enden. Spalten, die einer benutzerdefinierten Tabelle hinzugefügt werden (eine Tabelle mit einem Namen, der auf _CL endet), müssen dieses Suffix nicht aufweisen.

  1. Klicken Sie im Azure-Portal auf die Schaltfläche Cloud Shell, und stellen Sie sicher, dass die Umgebung auf PowerShell festgelegt ist.

    Screenshot des Öffnens der Cloud Shell.

  2. Kopieren Sie den folgenden PowerShell-Code, und ersetzen Sie den Path-Parameter durch die Details für Ihren Arbeitsbereich.

    $tableParams = @'
{
    "properties": {
        "schema": {
            "name": "LAQueryLogs",
            "columns": [
                {
                    "name": "Resources_CF",
                    "description": "The list of resources, this query ran against",
                    "type": "string",
                    "isDefaultDisplay": true,
                    "isHidden": false
                }
            ]
        }
    }
}
'@

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

  3. Fügen Sie den Code in die Cloud Shell-Eingabeaufforderung ein, um ihn auszuführen.

    Screenshot des Skripts in Cloud Shell.

  4. Sie können überprüfen, ob die Spalte hinzugefügt wurde, indem Sie im Azure-Portal zum Menü Log Analytics-Arbeitsbereich navigieren. Wählen Sie Protokolle aus, um Log Analytics zu öffnen, und erweitern Sie dann die Tabelle LAQueryLogs, um die Spalten anzuzeigen.

    Der Screenshot von Log Analytics mit neuer Spalte.

Definieren der Transformationsabfrage

Verwenden Sie Log Analytics, um die Transformationsabfrage vor dem Hinzufügen zu einer Datensammlungsregel zu testen.

  1. Öffnen Sie Ihren Arbeitsbereich im Azure-Portal im Menü Log Analytics-Arbeitsbereiche, und wählen Sie Protokolle aus, um Log Analytics zu öffnen.

  2. Führen Sie die folgende Abfrage aus, um den Inhalt der Tabelle LAQueryLogs anzuzeigen. Beachten Sie den Inhalt der Spalte RequestContext. Die Transformation ruft den Arbeitsbereichsnamen aus dieser Spalte ab und entfernt die restlichen Daten in dieser Spalte.

    LAQueryLogs
| take 10

    Der Screenshot der ersten Abfrage in Log Analytics.

  3. Ändern Sie die Abfrage wie folgt:

    LAQueryLogs
| where QueryText !contains 'LAQueryLogs'
| extend Context = parse_json(RequestContext)
| extend Workspace_CF = tostring(Context['workspaces'][0])
| project-away RequestContext, Context

    Dadurch werden folgende Änderungen vorgenommen:

    • Zeilen im Zusammenhang mit dem Abfragen der Tabelle LAQueryLogs selbst werden gelöscht, um Speicherplatz zu sparen, da diese Protokolleinträge nicht nützlich sind.
    • Eine Spalte für den Namen des abgefragten Arbeitsbereichs wird hinzugefügt.
    • Daten werden aus der Spalte RequestContext entfernt, um Speicherplatz zu sparen.

    Der Screenshot der geänderten Abfrage in Log Analytics.

  4. Nehmen Sie die folgenden Änderungen an der Abfrage vor, um sie in der Transformation zu verwenden:

    • Anstatt einen Tabellennamen (in diesem Fall LAQueryLogs) als Datenquelle für diese Abfrage anzugeben, verwenden Sie das Schlüsselwort source. Dies ist eine virtuelle Tabelle, die immer die eingehenden Daten in einer Transformationsabfrage darstellt.
    • Entfernen Sie alle Operatoren, die von Transformationsabfragen nicht unterstützt werden. Eine Detailliste der unterstützten Operatoren finden Sie unter Unterstützte KQL-Features.
    • Reduzieren Sie die Abfrage auf eine einzige Zeile, damit sie in den JSON-Code der Datensammlungsregel passt.

    Nachfolgend ist die Abfrage angegeben, die Sie nach diesen Änderungen in der Transformation verwenden:

    source | where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''

Erstellen einer Datensammlungsregel

Da dies die erste Transformation im Arbeitsbereich ist, müssen Sie eine Datensammlungsregel für die Arbeitsbereichstransformation erstellen. Wenn Sie Workspace Transformationen für andere Tabellen im selben Workspace erstellen, müssen sie in demselben DCR gespeichert werden.

  1. Geben Sie im Suchfeld des Azure-Portals Vorlage ein, und wählen Sie dann Benutzerdefinierte Vorlage bereitstellen aus.

    Der Screenshot zum Bereitstellen einer benutzerdefinierten Vorlage.

  2. Klicken Sie auf Eigene Vorlage im Editor erstellen.

    Screenshot: Erstellen einer Vorlage im Editor.

  3. Fügen Sie die unten aufgeführte Resource Manager-Vorlage in den Editor ein, und klicken Sie dann auf Speichern. Diese Vorlage definiert die Datensammlungsregel und enthält die Transformationsabfrage. Sie müssen diese Vorlage nicht ändern, da Sie Werte für ihre Parameter sammelt.

    Screenshot: Bearbeiten der Resource Manager-Vorlage. 

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "westus2",
            "allowedValues": [
                "westus2",
                "eastus2",
                "eastus2euap"
            ],
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-09-01-preview",
            "kind": "WorkspaceTransforms",
            "properties": {
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "clv2ws1"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Microsoft-Table-LAQueryLogs"
                        ],
                        "destinations": [
                            "clv2ws1"
                        ],
                        "transformKql": "source |where QueryText !contains 'LAQueryLogs' | extend Context = parse_json(RequestContext) | extend Resources_CF = tostring(Context['workspaces']) |extend RequestContext = ''"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

  4. Geben Sie auf dem Bildschirm Benutzerdefinierte Bereitstellung ein Abonnement und eine Ressourcengruppe zum Speichern der Datensammlungsregel an, und geben Sie dann in der Vorlage definierte Werte an. Dies schließt einen Namen für die Datensammlungsregel und die Arbeitsbereichsressourcen-ID ein, die Sie in einem vorherigen Schritt erfasst haben. Der Speicherort sollte mit dem Speicherort des Arbeitsbereichs identisch sein. Die Region sollte bereits mit Daten aufgefüllt worden sein und wird für den Speicherort der Datensammlungsregel verwendet.

    Der Screenshot zum Bearbeiten benutzerdefinierter Bereitstellungswerte.

  5. Klicken Sie auf Überprüfen und erstellen und dann auf Erstellen, nachdem Sie die Details überprüft haben.

  6. Erweitern Sie nach Abschluss der Bereitstellung das Feld Bereitstellungsdetails, und klicken Sie auf Ihre Datensammlungsregel, um ihre Details anzuzeigen. Klicken Sie auf JSON-Ansicht.

    Der Screenshot für Details zur Datenerfassungsregel.

  7. Kopieren Sie die Ressourcen-ID für die Datensammlungsregel. Sie benötigen diesen Wert im nächsten Schritt.

    Der Screenshot für die JSON-Ansicht der Datenerfassungsregel.

Im letzten Schritt zum Aktivieren der Transformation verknüpfen Sie die Datensammlungsregel mit dem Arbeitsbereich.

Wichtig

Ein Arbeitsbereich kann nur mit einer einzigen Datensammlungsregel verbunden werden, und die verknüpfte Datensammlungsregel muss diesen Arbeitsbereich als Ziel enthalten.

Verwenden Sie die API Arbeitsbereiche – Aktualisieren, um die Tabelle mit dem unten angegebenen PowerShell-Code zu konfigurieren.

  1. Klicken Sie auf die Schaltfläche Cloud Shell, um Cloud Shell erneut zu öffnen. Kopieren Sie den folgenden PowerShell-Code, und ersetzen Sie die Parameter durch die Werte für Ihren Arbeitsbereich und Ihre Datensammlungsregel.

    $defaultDcrParams = @'
{
    "properties": {
        "defaultDataCollectionRuleResourceId": "/subscriptions/{subscription}/resourceGroups/{resourcegroup}/providers/Microsoft.Insights/dataCollectionRules/{DCR}"
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}?api-version=2021-12-01-preview" -Method PATCH -payload $defaultDcrParams

  2. Fügen Sie den Code in die Cloud Shell-Eingabeaufforderung ein, um ihn auszuführen.

    Der Screenshot des Skripts zum Verknüpfen des Workspaces mit DCR.

Testen der Transformation

Warten Sie etwa 30 Minuten, bis die Transformation wirksam wird, und testen Sie sie dann, indem Sie eine Abfrage für die Tabelle ausführen. Nur Daten, die nach dem Anwenden der Transformation an die Tabelle gesendet wurden, sind betroffen.

Führen Sie für dieses Tutorial einige Beispielabfragen aus, um Daten an die Tabelle LAQueryLogs zu senden. Schließen Sie einige Abfragen für LAQueryLogs ein, damit Sie überprüfen können, ob die Transformation diese Datensätze filtert. Beachten Sie, dass die Ausgabe die neue Spalte Workspace_CF enthält und keine Datensätze für LAQueryLogs vorhanden sind.

Problembehandlung

In diesem Abschnitt werden verschiedene Fehlerbedingungen, die auftreten können, und deren Behebung beschrieben.

IntelliSense in Log Analytics erkennt neue Spalten in der Tabelle nicht

Die Aktualisierung des Caches, der IntelliSense steuert, kann bis zu 24 Stunden dauern.

Die Transformation für eine dynamische Spalte funktioniert nicht

Es gibt derzeit ein bekanntes Problem, das dynamische Spalten betrifft. Eine vorübergehende Problemumgehung besteht darin, dynamische Spaltendaten mithilfe von parse_json() explizit zu analysieren, bevor Vorgänge dafür ausgeführt werden.

Nächste Schritte