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

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

Neste tutorial, você aprenderá a:

• Aproveitar a funcionalidade do portal existente para pré-criar DCRs
• Obter o conteúdo de uma regra de coleta de dados usando a chamada à API do ARM
• Aplicar alterações a uma regra de coleta de dados usando a chamada à API do ARM
• Automatizar o processo de atualização do DCR usando scripts do PowerShell

Observação

Este tutorial descreve um método para editar uma DCR existente. Consulte Criar e editar DCRs (regras de coleta de dados) no Azure Monitor para outros métodos.

Pré-requisitos

Para concluir este tutorial, você precisará de:

• Workspace do Log Analytics em que você tem pelo menos direitos de colaborador.
• Permissões para criar objetos de Regra de Coleta de Dados no workspace.
• Versão atualizada do PowerShell. Recomendamos usar o Azure Cloud Shell.

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, talvez seja aconselhável atualizar sua regra de coleta de dados mais tarde para:

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

Neste tutorial você deve, em primeiro lugar, configurar a ingestão de um log personalizado. A seguir, você deve modificar a transformação KQL do seu log personalizado de modo a incluir uma filtragem adicional e aplicar as alterações à sua DCR. Para terminar, 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 logs do Azure Monitor usando o portal do Azure (versão prévia). Observe a ID do recurso do DCR criado.

Recuperar o conteúdo do DCR

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

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

   

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

Agora, quando o conteúdo do DCR é armazenado como um arquivo JSON, você pode usar um editor de sua escolha para fazer alterações no DCR. Talvez você prefira baixar o arquivo a partir 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 salvou o DCR em um arquivo nomeado temp.dcr em seu Cloud Drive, você poderá 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 da DCR de modo a descartar as linhas em que o RequestType pode ser 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 o atributo ”transformKql”, que, se você seguiu o tutorial para criação de log personalizado, deverá 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.

Aplique as alterações

Nossa etapa final é atualizar o DCR de volta no sistema. Isso é feito por meio de uma chamada HTTP PUT à API do ARM, com o conteúdo da DCR atualizada enviado no corpo da solicitação HTTP.

1. Se estiver usando o Azure Cloud Shell, salve o arquivo e feche o editor incorporado, ou carregue novamente o arquivo da DCR modificada no ambiente do Cloud Shell.

2. Execute os comandos a seguir para carregar o conteúdo do DCR do arquivo e fazer uma 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 uma chamada bem-sucedida, você deve obter a resposta com o código de status 200, indicando que sua DCR agora está atualizada.

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

Juntando tudo

Agora, quando soubermos ler e atualizar o conteúdo de um DCR, vamos colocar tudo em um script 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 esse utilitário

Supondo que você tenha salvado o script como um arquivo, nomeado DCREditor.ps1 e precisa modificar uma Regra de Coleta de Dados com a ID do 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 da DCR será aberto no editor de código integrado. Após a edição ter sido concluída, a inserção de um "Y" no prompt do script aplicará as alterações à DCR.

Próximas etapas

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