教程:编辑数据收集规则 (DCR)

本教程介绍如何编辑已使用命令行工具预配的数据收集规则 (DCR) 的定义。

在本教程中,你将了解如何执行以下操作:

  • 利用现有门户功能预先创建 DCR
  • 使用 ARM API 调用获取数据收集规则的内容
  • 使用 ARM API 调用将更改应用于数据收集规则
  • 使用 PowerShell 脚本自动执行 DCR 更新过程

注意

本教程逐步讲解用于编辑现有 DCR 的一种方法。 有关其他方法,请参阅在 Azure Monitor 中创建和编辑数据收集规则 (DCR)

先决条件

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

教程概述

虽然在门户上完成向导中的所有步骤是设置如何将自定义数据引入 Log Analytics 的最简单方法,但在某些情况下,你可能希望稍后更新数据收集规则以实现以下目的:

  • 更改数据收集设置(例如,与 DCR 关联的数据收集终结点)
  • 更新数据流的数据分析或筛选逻辑
  • 更改数据目标(例如,将数据发送到 Azure 表,因为此选项不直接作为基于 DCR 的自定义日志向导的一部分提供)

在本教程中,将首先设置自定义日志的引入。 然后,将修改自定义日志的 KQL 转换以包含其他筛选,并将更改应用于 DCR。 最后,我们要将所有编辑操作合并到单个 PowerShell 脚本中,你可以出于上述任何原因而使用该脚本来编辑任何 DCR。

设置新的自定义日志

首先设置新的自定义日志。 按照教程:使用 Azure 门户将自定义日志发送到 Azure Monitor 日志(预览版)执行操作。 记下创建的 DCR 的资源 ID。

检索 DCR 内容

为了更新 DCR,我们将要检索其内容并将其保存为文件,该文件可供进一步编辑。

  1. 执行以下命令以检索 DCR 内容并将其保存到文件中。 将 <ResourceId> 替换为 DCR ResourceID,将 <FilePath> 替换为用于存储 DCR 的文件的名称。

    $ResourceId = "<ResourceId>" # Resource ID of the DCR to edit
    $FilePath = "<FilePath>" # Store DCR content in this file
    $DCR = Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method GET
    $DCR.Content | ConvertFrom-Json | ConvertTo-Json -Depth 20 | Out-File -FilePath $FilePath
    

编辑 DCR

现在,当 DCR 内容存储为 JSON 文件时,可以使用所选编辑器在 DCR 中进行更改。

你也可以使用随环境提供的代码编辑器。 例如,如果将 DCR 保存在 Cloud Drive 上名为 temp.dcr 的文件中,则可以使用以下命令直接在 PowerShell 窗口中打开 DCR 以进行编辑:

code "temp.dcr"

让我们修改 DCR 中的 KQL 转换,以删除 RequestType 为“GET”以外的任何内容的行。

  1. 打开在上一部分中创建的文件,以便使用你选择的编辑器进行编辑。
  2. 找到包含 ”transformKql” 属性的行,如果遵循自定义日志创建教程,则应如下所示:
    "transformKql": "  source\n    | extend TimeGenerated = todatetime(Time)\n    | parse RawData with \n    ClientIP:string\n    ' ' *\n    ' ' *\n    ' [' * '] \"' RequestType:string\n    \" \" Resource:string\n    \" \" *\n    '\" ' ResponseCode:int\n    \" \" *\n    | where ResponseCode != 200\n    | project-away Time, RawData\n"
    
  3. 修改 KQL 转换以包括按 RequestType 的其他筛选器
    "transformKql": "  source\n    | where RawData contains \"GET\"\n     | extend TimeGenerated = todatetime(Time)\n    | parse RawData with \n    ClientIP:string\n    ' ' *\n    ' ' *\n    ' [' * '] \"' RequestType:string\n    \" \" Resource:string\n    \" \" *\n    '\" ' ResponseCode:int\n    \" \" *\n    | where ResponseCode != 200\n    | project-away Time, RawData\n"
    
  4. 保存带有已修改的 DCR 内容的文件。

应用更改

最后一步是将 DCR 更新回系统中。 这是通过对 ARM API 的“PUT”HTTP 调用完成的,已更新的 DCR 内容会在 HTTP 请求正文中发送。

  1. 执行以下命令,以从文件中加载 DCR 内容并发出 HTTP 调用以更新系统中的 DCR。 将 <ResourceId> 替换为 DCR ResourceID,将 <FilePath> 替换为在本教程上一部分中修改的文件的名称。 如果在同一 PowerShell 会话中读取和写入 DCR,则可以省略前两行。
    $ResourceId = "<ResourceId>" # Resource ID of the DCR to edit
    $FilePath = "<FilePath>" # Store DCR content in this file
    $DCRContent = Get-Content $FilePath -Raw 
    Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method PUT -Payload $DCRContent 
    
  2. 成功调用后,应收到状态代码为“200”的响应,指示 DCR 现已更新。
  3. 现在,可以通过“JSON 视图”功能在门户中导航到 DCR 并检查其内容,也可以重复本教程的第一部分,将 DCR 内容检索到文件中。

将所有内容放在一起

现在,当我们知道如何读取和更新 DCR 的内容后,让我们把所有操作全都放在实用工具脚本中,该脚本可用于将这两个操作一起执行。

param ([Parameter(Mandatory=$true)] $ResourceId)

# get DCR content and put into a file
$FilePath = "temp.dcr"
$DCR = Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method GET
$DCR.Content | ConvertFrom-Json | ConvertTo-Json -Depth 20 | Out-File $FilePath

# Open DCR in code editor
code $FilePath | Wait-Process

#Wait for confirmation to apply changes
$Output = Read-Host "Apply changes to DCR (Y/N)? "
if ("Y" -eq $Output.toupper())
{ 
	#write DCR content back from the file
	$DCRContent = Get-Content $FilePath -Raw
	Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method PUT -Payload $DCRContent		
}

#Delete temporary file
Remove-Item $FilePath

如何使用此实用工具

假设已将脚本保存为文件(名为 DCREditor.ps1)并需要修改资源 ID 为 /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.Insights/dataCollectionRules/bar 的数据收集规则,则可以通过运行以下命令来实现此目的:

.\DCREditor.ps1 "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.Insights/dataCollectionRules/bar"

DCR 内容在嵌入式代码编辑器中打开。 编辑完成后,在出现脚本提示时输入“Y”会将更改应用回 DCR。

后续步骤