Tutorial: Editar uma regra de coleta de dados (DCR)

Este tutorial descreve como editar a definição de DCRs (Regras de Coleta de Dados) que já foram provisionadas usando ferramentas de linha de comando.

Neste tutorial, irá aprender a:

Pré-requisitos

Para concluir este tutorial, precisa de:

Visão geral do tutorial

Embora passar pelo assistente no portal seja a maneira mais simples de configurar a ingestão de seus dados personalizados para o Log Analytics, em alguns casos, você pode querer atualizar sua Regra de Coleta de Dados mais tarde para:

• Alterar as configurações de coleta de dados (por exemplo, Ponto de Extremidade de Coleta de Dados, associado ao DCR)
• Atualizar a lógica de análise ou filtragem de dados para seu fluxo de dados
• Alterar o destino dos dados (por exemplo, enviar dados para uma tabela do Azure, pois essa opção não é oferecida diretamente como parte do assistente de log personalizado baseado em DCR)

Neste tutorial, você primeiro configura a ingestão de um log personalizado. Em seguida, modifique a transformação KQL para seu log personalizado para incluir filtragem adicional e aplicar as alterações ao seu DCR. Finalmente, vamos combinar todas as operações de edição em um único script do PowerShell, que pode ser usado para editar qualquer DCR por qualquer um dos motivos mencionados acima.

Configurar novo log personalizado

Comece configurando um novo log personalizado. Siga o Tutorial: Enviar logs personalizados para os Logs do Azure Monitor usando o portal do Azure (visualização). Observe a ID do recurso do DCR criado.

Recuperar conteúdo DCR

Para atualizar o DCR, vamos recuperar seu conteúdo e salvá-lo como um arquivo, que pode ser editado posteriormente.

1. Clique no botão Cloud Shell no portal do Azure e verifique se o ambiente está definido como PowerShell.

   

2. Execute os seguintes comandos para recuperar o conteúdo DCR e salvá-lo em um arquivo. Substitua <ResourceId> por DCR ResourceID e <FilePath> pelo nome do arquivo para armazenar 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
   

Editar DCR

Agora, quando o conteúdo DCR é armazenado como um arquivo JSON, você pode usar um editor de sua escolha para fazer alterações no DCR. Você pode preferir baixar o arquivo do ambiente do Cloud Shell, se estiver usando um.

Como alternativa, você pode usar editores de código fornecidos com o ambiente. Por exemplo, se você salvou seu DCR em um arquivo nomeado temp.dcr em seu Cloud Drive, você pode usar o seguinte comando para abrir o DCR para edição diretamente na janela do Cloud Shell:

code "temp.dcr"

Vamos modificar a transformação KQL dentro do DCR para soltar linhas onde RequestType é qualquer coisa, menos GET.

1. Abra o arquivo criado na parte anterior para edição usando um editor de sua escolha.

2. Localize a linha que contém ”transformKql” o atributo que, se você seguiu o tutorial para criação de log personalizado, deve ser semelhante a esta:

   "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. Modificar a transformação KQL para incluir filtro adicional por 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. Salve o arquivo com conteúdo DCR modificado.

Aplicar alterações

Nosso passo final é atualizar o DCR de volta ao sistema. Isso é feito por PUT chamada HTTP para API ARM, com conteúdo DCR atualizado enviado no corpo da solicitação HTTP.

1. Se você estiver usando o Azure Cloud Shell, salve o arquivo e feche o editor incorporado ou carregue o arquivo DCR modificado de volta para o ambiente do Cloud Shell.

2. Execute os seguintes comandos para carregar o conteúdo DCR do arquivo e fazer chamada HTTP para atualizar o DCR no sistema. Substitua <ResourceId> por DCR ResourceID e <FilePath> pelo nome do arquivo modificado na parte anterior do tutorial. Você pode omitir as duas primeiras linhas se ler e gravar no DCR na mesma sessão do PowerShell.

   $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 
   

3. Após a chamada bem-sucedida, você deve obter a resposta com o código de 200status, indicando que seu DCR está atualizado.

4. Agora você pode navegar até o DCR e examinar seu conteúdo no portal por meio da função JSON View , ou pode repetir a primeira parte do tutorial para recuperar conteúdo DCR em um arquivo.

Juntando tudo

Agora, quando soubermos como ler e atualizar o conteúdo de um DCR, vamos juntar tudo em um script de utilitário, que pode ser usado para executar ambas as operações juntas.

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

Como usar este utilitário

Supondo que você salvou o script como um arquivo, nomeado DCREditor.ps1 e precisa modificar uma Regra de Coleta de Dados com ID de recurso de /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.Insights/dataCollectionRules/bar, isso pode ser feito executando o seguinte comando:

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

O conteúdo DCR é aberto no editor de código incorporado. Quando a edição estiver concluída, digitar "Y" no prompt de script aplicará as alterações de volta ao DCR.

Próximos passos

• Leia mais sobre as regras de coleta de dados e as opções para criá-las.