Create and edit data collection rules (DCRs) in Azure Monitor

There are multiple methods for creating a data collection rule (DCR) in Azure Monitor. In some cases, Azure Monitor will create and manage the DCR according to settings that you configure in the Azure portal. In other cases, you might need to create your own DCRs to customize particular scenarios.

This article describes the different methods for creating and editing a DCR. For the contents of the DCR itself, see Structure of a data collection rule in Azure Monitor.

Permissions

You require the following permissions to create DCRs and associations:

Built-in role Scopes Reason
Monitoring Contributor
  • Subscription and/or
  • Resource group and/or
  • An existing DCR
Create or edit DCRs, assign rules to the machine, deploy associations).
Virtual Machine Contributor
Azure Connected Machine Resource Administrator
  • Virtual machines, virtual machine scale sets
  • Azure Arc-enabled servers
Deploy agent extensions on the VM.
Any role that includes the action Microsoft.Resources/deployments/*
  • Subscription and/or
  • Resource group and/or
  • An existing DCR
Deploy Azure Resource Manager templates.

Automated methods to create a DCR

The following table lists methods to create data collection scenarios using the Azure portal where the DCR is created for you. In these cases you don't need to interact directly with the DCR itself.

Scenario Resources Description
Azure Monitor Agent Configure data collection for Azure Monitor Agent Use the Azure portal to create a DCR that specifies events and performance counters to collect from a machine with Azure Monitor Agent. Then associate that rule with one or more virtual machines. Azure Monitor Agent will be installed on any machines that don't currently have it.
Enable VM insights overview When you enable VM insights on a VM, the Azure Monitor agent is installed, and a DCR is created that collects a predefined set of performance counters. You shouldn't modify this DCR.
Container insights Enable Container insights When you enable Container insights on a Kubernetes cluster, a containerized version of the Azure Monitor agent is installed, and a DCR is created that collects data according to the configuration you selected. You may need to modify this DCR to add a transformation.
Text or JSON logs Collect logs from a text or JSON file with Azure Monitor Agent Use the Azure portal to create a DCR to collect entries from a text log on a machine with Azure Monitor Agent.
Workspace transformation Add a transformation in a workspace data collection rule using the Azure portal Create a transformation for any supported table in a Log Analytics workspace. The transformation is defined in a DCR that's then associated with the workspace. It's applied to any data sent to that table from a legacy workload that doesn't use a DCR.

Manually create a DCR

To manually create a DCR, create a JSON file using the appropriate configuration for the data collection that you're configuring. Start with one of the sample DCRs and use information in Structure of a data collection rule in Azure Monitor to modify the JSON file for your particular environment and requirements.

Once you have the JSON file created, you can use any of the following methods to create the DCR:

Use the az monitor data-collection rule create command to create a DCR from your JSON file using the Azure CLI as shown in the following example.

az monitor data-collection rule create --location 'eastus' --resource-group 'my-resource-group' --name 'myDCRName' --rule-file 'C:\MyNewDCR.json' --description 'This is my new DCR'

The following tutorials include examples of manually creating DCRs.

Edit a DCR

To edit a DCR, you can use any of the methods described in the previous section to create a DCR using a modified version of the JSON.

If you need to retrieve the JSON for an existing DCR, you can copy it from the JSON View for the DCR in the Azure portal. You can also retrieve it using an API call as shown in the following PowerShell example.

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

For a tutorial that walks through the process of retrieving and then editing an existing DCR, see Tutorial: Edit a data collection rule (DCR).

Next steps