This article describes the different methods you can use to install, uninstall, update, and configure the Azure Monitor Agent on Azure virtual machines, virtual machine scale sets, and Azure Arc-enabled servers.
Important
The Azure Monitor Agent requires at least one data collection rule (DCR) to begin collecting data after it's installed on a client machine. Your installation method determines whether a DCR is created automatically. If a DCR isn't created automatically during installation, you must configure data collection by following the guidance in Collect data with the Azure Monitor Agent.
Prerequisites
For prerequisites and other requirements for using the Azure Monitor Agent, see these articles:
Installing, upgrading, or uninstalling the Azure Monitor Agent doesn't require a machine restart.
Installation options
The following table lists the options for installing the Azure Monitor Agent on Azure VMs and Azure Arc-enabled servers.
For any machine that isn't in Azure, the Azure Arc agent must be installed on the machine before the Azure Monitor Agent can be installed.
Installation method
Description
Virtual machine (VM) extension
Use any of the methods described in this article to install the agent via the Azure extension framework. This method doesn't create a DCR, so you must create at least one DCR and associate it with the agent before data collection begins.
When you create a DCR in the Azure portal, the Azure Monitor Agent is installed on any machine that's added as a resource for the DCR. The agent immediately begins to collect data as defined in the DCR.
When you enable VM insights on a machine, the Azure Monitor Agent is installed and a DCR is created to collect a predefined set of data. You shouldn't modify this DCR, but you can create more DCRs to collect more data.
Use Azure Policy to automatically install the agent on Azure virtual machines and Azure Arc-enabled servers, and to automatically associate them with required DCRs.
Note
To send data across tenants, you must first enable Azure Lighthouse.
Cloning a machine that has Azure Monitor Agent installed isn't supported. The best practice for this scenario is to use Azure Policy or an infrastructure as a code (IaaC) tool to deploy the Azure Monitor Agent at scale.
You can install the Azure Monitor Agent on an Azure virtual machine or on an Azure Arc-enabled server by using the PowerShell command for adding a virtual machine extension.
Azure virtual machines
Use the following PowerShell commands to install the Azure Monitor Agent on an Azure virtual machine. Choose the appropriate command based on the authentication method you use.
You can install the Azure Monitor Agent on an Azure virtual machine or on an Azure Arc-enabled server by using the Azure CLI command for adding a virtual machine extension.
Azure virtual machines
Use the following Azure CLI commands to install the Azure Monitor Agent on an Azure virtual machine. Choose the appropriate command based on the authentication method you use.
User-assigned managed identity
Windows
az vm extension set --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --ids <vm-resource-id> --enable-auto-upgrade true --settings '{"authentication":{"managedIdentity":{"identifier-name":"mi_res_id","identifier-value":"/subscriptions/<my-subscription-id>/resourceGroups/<my-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<my-user-assigned-identity>"}}}'
Linux
az vm extension set --name AzureMonitorLinuxAgent --publisher Microsoft.Azure.Monitor --ids <vm-resource-id> --enable-auto-upgrade true --settings '{"authentication":{"managedIdentity":{"identifier-name":"mi_res_id","identifier-value":"/subscriptions/<my-subscription-id>/resourceGroups/<my-resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<my-user-assigned-identity>"}}}'
System-assigned managed identity
Windows
az vm extension set --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --ids <vm-resource-id> --enable-auto-upgrade true
Linux
az vm extension set --name AzureMonitorLinuxAgent --publisher Microsoft.Azure.Monitor --ids <vm-resource-id> --enable-auto-upgrade true
Azure virtual machines scale set
Use the az vmss extension set Azure CLI cmdlet to install the Azure Monitor Agent on an Azure virtual machines scale set.
Azure Arc-enabled servers
Use the following Azure CLI commands to install the Azure Monitor Agent on an Azure Arc-enabled server:
You can use an Azure Resource Manager template to install the Azure Monitor Agent on an Azure virtual machine or on an Azure Arc-enabled server, and to create an association with DCRs. You must create any DCR before you create the association for the DCR.
Get sample templates to install the agent and to create the association from the following resources:
To uninstall the Azure Monitor Agent by using the Azure portal, go to your virtual machine, scale set, or Azure Arc-enabled server. Select the Extensions tab, and then select AzureMonitorWindowsAgent or AzureMonitorLinuxAgent. In the dialog that opens, select Uninstall.
Uninstall on an Azure virtual machine
Use the following PowerShell commands to uninstall the Azure Monitor Agent on an Azure virtual machine:
Use the following Azure CLI commands to uninstall the Azure Monitor Agent on an Azure virtual machine:
Windows
az vm extension delete --resource-group <resource-group-name> --vm-name <virtual-machine-name> --name AzureMonitorWindowsAgent
Linux
az vm extension delete --resource-group <resource-group-name> --vm-name <virtual-machine-name> --name AzureMonitorLinuxAgent
Uninstall on an Azure virtual machine scale set
Use the az vmss extension delete Azure CLI cmdlet to uninstall the Azure Monitor Agent on an Azure virtual machine scale set.
Uninstall on an Azure Arc-enabled server
Use the following Azure CLI commands to uninstall the Azure Monitor Agent on an Azure Arc-enabled server:
Windows
az connectedmachine extension delete --name AzureMonitorWindowsAgent --machine-name <arc-server-name> --resource-group <resource-group-name>
Linux
az connectedmachine extension delete --name AzureMonitorLinuxAgent --machine-name <arc-server-name> --resource-group <resource-group-name>
Not applicable.
Update
Note
We strongly recommend that you always update to the latest version of the agent or opt in to automatic extension upgrade.
Automatic extension rollout follows standard Azure deployment practices to safely deploy the latest version of the agent. You should expect automatic updates to take weeks to roll out the latest version.
Upgrades are issued in batches, so some of your virtual machines, scale sets, or Azure Arc-enabled servers might be upgraded before others.
If you need to upgrade an extension immediately, you can use the manual instructions that are described in this article. Only agents released in the past year are supported.
To do a one-time update of the agent, you must first uninstall the existing agent version. Then install the new version as described.
We recommend that you enable automatic update of the agent by enabling automatic extension upgrade. Go to your virtual machine or scale set, select the Extensions tab, and then select AzureMonitorWindowsAgent or AzureMonitorLinuxAgent. In the dialog that opens, select Enable automatic upgrade.
Update on Azure virtual machines
To do a one-time update of the agent, you must first uninstall the existing agent version. Then install the new version as described.
To do a one-time update of the agent, you must first uninstall the existing agent version. Then install the new version as described in this article.
We recommend that you enable automatic update of the agent by opting in to automatic extension upgrade feature by using the following Azure CLI commands:
Windows
az vm extension set --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --vm-name <virtual-machine-name> --resource-group <resource-group-name> --enable-auto-upgrade true
Linux
az vm extension set --name AzureMonitorLinuxAgent --publisher Microsoft.Azure.Monitor --vm-name <virtual-machine-name> --resource-group <resource-group-name> --enable-auto-upgrade true
Update on Azure Arc-enabled servers
To do a one-time upgrade of the agent, use the following Azure CLI commands:
Windows
az connectedmachine upgrade-extension --extension-targets "{\"Microsoft.Azure.Monitor.AzureMonitorWindowsAgent\":{\"targetVersion\":\"<target-version-number>\"}}" --machine-name <arc-server-name> --resource-group <resource-group-name>
Linux
az connectedmachine upgrade-extension --extension-targets "{\"Microsoft.Azure.Monitor.AzureMonitorLinuxAgent\":{\"targetVersion\":\"<target-version-number>\"}}" --machine-name <arc-server-name> --resource-group <resource-group-name>
Data collection rules (DCRs) serve as a management tool for the Azure Monitor Agent on your machine. The AgentSettings DCR can be used to configure certain Azure Monitor Agent parameters to configure the agent to your specific monitoring needs.
Note
Important considerations when you work with the AgentSettings DCR:
Currently, the AgentSettings DCR can be configured only by using an Azure Resource Manager template.
AgentSettings must be a single DCR with no other settings.
The virtual machine and the AgentSettings DCR must be in the same region.
Supported parameters
The AgentSettings DCR currently supports setting the following parameters:
Parameter
Description
Valid values
MaxDiskQuotaInMB
To provide resiliency, the agent collects data in a local cache when the agent can't send data. The agent sends the data in the cache after the connection is restored. This parameter is the amount of disk space used (in MB) by the Azure Monitor Agent log files and cache.
Linux: 1025 to 51199 Windows: 4000 to 51199
UseTimeReceivedForForwardedEvents
Changes the WEF column in the Microsoft Sentinel Windows Event Forwarding (WEF) table to use TimeReceived instead of TimeGenerated data
Associate the DCR with your machine. Use the following Resource Manager files.
Template file:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"vmName": {
"type": "string",
"metadata": {
"description": "The name of the virtual machine."
}
},
"dataCollectionRuleId": {
"type": "string",
"metadata": {
"description": "The resource ID of the data collection rule."
}
}
},
"resources": [
{
"type": "Microsoft.Insights/dataCollectionRuleAssociations",
"apiVersion": "2021-09-01-preview",
"scope": "[format('Microsoft.Compute/virtualMachines/{0}', parameters('vmName'))]",
"name": "agentSettings",
"properties": {
"description": "Association of data collection rule. Deleting this association will break the data collection for this virtual machine.",
"dataCollectionRuleId": "[parameters('dataCollectionRuleId')]"
}
}
]
}