教程:使用资源管理器模板将工作区数据收集规则中的转换添加到 Azure Monitor

本教程将指导你使用资源管理器模板在工作区数据收集规则中配置示例转换。 Azure Monitor 中的转换可用于在传入数据发送到目标之前对其进行筛选或修改。 工作区转换为尚未使用 Azure Monitor 数据引入管道的工作流提供引入时间转换支持。

工作区转换将一起存储在工作区的单个数据收集规则 (DCR) 中,称为“工作区 DCR”。 每个转换都与特定表相关联。 转换会应用于从任何不使用 DCR 的工作流发送到此表的所有数据。

注意

本教程使用资源管理器模板和 REST API 来配置工作区转换。 有关使用 Azure 门户的相同教程,请参阅教程:使用 Azure 门户将工作区数据收集规则中的转换添加到 Azure Monitor

在本教程中,学习:

  • 为 Log Analytics 工作区中的表配置工作区转换
  • 编写用于引入时间转换的日志查询。

注意

本教程使用 PowerShell 通过 Azure Monitor API 和 Azure 门户进行 REST API 调用,以安装资源管理器模板。 可以使用任何其他方法进行这些调用。

先决条件

若要完成本教程,需要以下各项:

教程概述

在本教程中,你将通过筛选出某些记录来减少LAQueryLogs表的存储要求。 你还将在分析列数据时删除列的内容,以在自定义列中存储数据片段。 当你在工作区中启用日志查询审核时,将创建LAQueryLogs 表,但这仅用作本教程的示例。 你可以使用此相同的基本过程为 Log Analytics 工作区中任何受支持的表创建转换。

启用查询审核日志

需要为你的工作区启用查询审核,以创建你将使用的LAQueryLogs表。 这不是所有引入时间转换所必需的。 它只是生成此示例转换将使用的示例数据。

  1. 从 Azure 门户中的 “Log Analytics 工作区”菜单中,选择“诊断设置”,然后单击“添加诊断设置”。

    诊断设置的屏幕截图。

  2. 提供诊断设置的名称,并选择工作区,以便审核数据存储在同一工作区中。 选择“审核”类别,然后单击“保存”以保存诊断设置并关闭诊断设置页。

    新诊断设置的屏幕截图。

  3. 选择“日志”,然后运行一些查询以对LAQueryLogs进行数据填充。 这些查询不需要实际返回任何数据。

    示例日志查询的屏幕截图。

更新表架构

创建转换之前,必须先对表进行以下两项更改:

  • 必须为工作区转换启用该表。 这对于任何将要转换的表都是必需的,即使转换不修改表的架构也是如此。
  • 必须将转换填充的任何其他列添加到该表中。

使用“表-更新” API 通过以下 PowerShell 代码配置该表。 如果调用 API,则表可以进行工作区转换,无论自定义列是否已定义。 在此示例中,它包括一个名为 “Resources_CF” 的自定义列,该列将使用转换查询进行填充。

重要

添加到内置表中的任何自定义列必须以 “_CF” 结尾。 添加到自定义表(名称以 “_CF”结尾的表)中的列,无需具有此后缀。

  1. 复制以下 PowerShell 代码,并将 “Path” 参数替换为工作区的详细信息。

    $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
    
  2. 将代码粘贴到本地 PowerShell 提示符下以运行。

  3. 可以通过转到 Azure 门户中的 “Log Analytics 工作区”菜单来验证是否已添加该列。 选择“日志”打开 Log Analytics 然后展开LAQueryLogs表以查看其列。

    包含新列的 Log Analytics 的屏幕截图。

定义转换查询

使用 Log Analytics 测试转换查询,然后将其添加到数据收集规则。

  1. 在 Azure 门户的 “Log Analytics 工作区”菜单中打开工作区,并选择“日志”打开 Log Analytics。

  2. 运行以下查询以查看LAQueryLogs表的内容。 注意RequestContext列的内容。 转换将检索此列的工作区名称,并删除其中的其余数据。

    LAQueryLogs
    | take 10
    

    Log Analytics 中初始查询的屏幕截图。

  3. 将查询修改为以下内容:

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

    这将进行以下更改:

    • 删除与查询LAQueryLogs表本身相关的行,以节省空间,因为这些日志项不起作用。
    • 为所查询的工作区名称添加一列。
    • 删除RequestContext列中的数据以节省空间。

    Log Analytics 中已修改查询的屏幕截图。

  4. 对查询进行以下更改以在转换中使用它:

    • 请使用source关键字,而不是指定表名称(如此示例中的LAQueryLogs)作为此查询的数据源。 这是一个在转换查询中始终显示传入数据的虚拟表。
    • 删除不受转换查询支持的所有运算符。 请参阅支持的 KQL 功能,获取受支持的运算符的详细列表。
    • 将查询平展到单个行,使其适合 DCR JSON。

    下面是在修改后将在转换中使用的查询:

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

创建数据收集规则 (DCR)

由于这是工作区中的第一个转换,因此需要创建工作区转换 DCR。 如果在同一工作区中为其他表创建工作区转换,则它们必须存储在此同一 DCR 中。

  1. 在 Azure 门户的搜索框中,输入“模板”,然后选择“部署自定义模板”。

    部署自定义模板的屏幕截图。

  2. 单击“在编辑器中生成自己的模板”。

    在编辑器中生成模板的屏幕截图。

  3. 将以下资源管理器模板粘贴到编辑器中,然后单击“保存”。 此模板定义 DCR 并包含转换查询。 不需要修改此模板,因为它将收集其参数的值。

    编辑资源管理器模板的屏幕截图。

    {
        "$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": "chinanorth2",
                "allowedValues": [
                    "chinanorth2",
                    "chinanorth2",
                    "chinanorth2euap"
                ],
                "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. 在“自定义部署”屏幕上,指定用于存储数据收集规则的“订阅”和“资源组”,然后提供在模板中定义的值。 这包括数据收集规则的“名称”和在上一步中收集的“工作区资源 ID”。 该“位置”应与工作区位于同一位置。 该“区域”已填充,并用作数据收集规则的位置。

    编辑自定义部署值的屏幕截图。

  5. 查看详细信息时,单击“查看+创建”,然后单击“创建”。

  6. 部署完成后,展开“部署详细信息”框,并单击数据收集规则以查看其详细信息。 单击“JSON 视图”。

    数据收集规则详细信息的屏幕截图。

  7. 复制数据收集规则的“资源 ID”。 将在下一个步骤中使用此内容。

    数据收集规则 JSON 视图的屏幕截图。

启用转换的最后一步是将 DCR 链接到工作区。

重要

一个工作区只能连接到单个 DCR,并且链接的 DCR 必须将此工作区包含为目标。

使用“工作区-更新” API 通过以下 PowerShell 代码配置该表。

  1. 复制以下 PowerShell 代码,并将参数替换为工作区和 DCR 的值。

    $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. 将代码粘贴到本地 PowerShell 提示符下以运行。

测试转换

大约 30 分钟后,转换才会生效,你可以通过对表运行查询来对测试转换。 只有应用转换后发送到表的数据才会受到影响。

对于本教程,请运行一些示例查询,将数据发送到LAQueryLogs表。 包括一些对LAQueryLogs的查询,以便验证转换是否筛选这些记录。 请注意,输出包含新Workspace_CF列,并且没有记录LAQueryLogs

疑难解答

本部分介绍你可能会遇到的不同错误情况,以及如何更正它们。

Log Analytics 中的 IntelliSense 无法识别表中的新列

用于驱动 IntelliSense 的缓存可能需要长达 24 小时的时间才能更新。

动态列上的转换不起作用

当前存在影响动态列的已知问题。 临时的解决方法是在对动态列数据执行任何操作之前,使用 parse_json() 显式分析这些数据。

后续步骤