Install and manage Azure Monitor Agent

This article details the different methods to install, uninstall, update, and configure Azure Monitor Agent on Azure virtual machines, scale sets, and Azure Arc-enabled servers.

Important

Azure Monitor Agent requires at least one data collection rule (DCR) to begin collecting data after it's installed on the client machine. Depending on the installation method you use, a DCR may or may not be created automatically. If not, then you need to configure data collection following the guidance at Collect data with Azure Monitor Agent.

Prerequisites

See the following articles for prerequisites and other requirements for Azure Monitor Agent:

• Azure Monitor Agent supported operating systems and environments
• Azure Monitor Agent requirements
• Azure Monitor Agent network configuration

Important

Installing, upgrading, or uninstalling Azure Monitor Agent won't require a machine restart.

Installation options

The following table lists the different options for installing Azure Monitor Agent on Azure VMs and Azure Arc-enabled servers. The Azure Arc agent must be installed on any machines not in Azure before Azure Monitor Agent can be installed.

Installation method	Description
VM extension	Use any of the methods below to use the Azure extension framework to install the agent. This method does not create a DCR, so you must create at least one and associate it with the agent before data collection will begin.
Create a DCR	When you create a DCR in the Azure portal, Azure Monitor Agent is installed on any machines that are added as resources for the DCR. The agent will begin collecting data defined in the DCR immediately.
VM insights	When you enable VM insights on a machine, Azure Monitor Agent is installed, and a DCR is created that collects a predefined set of data. You shouldn't modify this DCR, but you can create additional DCRs to collect other data.
Container insights	When you enable Container insights on a Kubernetes cluster, a containerized version of Azure Monitor Agent is installed in the cluster, and a DCR is created that immediately begins collecting data. You can modify this DCR using guidance at Configure data collection and cost optimization in Container insights using data collection rule.
Client installer	Installs the agent by using a Windows MSI installer for Windows 10 and Windows 11 clients.
Azure Policy	Use Azure Policy to automatically install the agent on Azure virtual machines and Azure Arc-enabled servers and automatically associate them with required DCRs.

Note

To send data across tenants, you must first enable Azure Lighthouse. Cloning a machine with Azure Monitor Agent installed is not supported. The best practice for these situations is to use Azure Policy or an Infrastructure as a code tool to deploy AMA at scale.

Install agent extension

This section provides details on installing Azure Monitor Agent using the VM extension.

Portal

Use the guidance at Collect data with Azure Monitor Agent to install the agent using the Azure portal and create a DCR to collect data.

PowerShell

You can install Azure Monitor Agent on Azure virtual machines and on Azure Arc-enabled servers by using the PowerShell command for adding a virtual machine extension.

Azure virtual machines

Use the following PowerShell commands to install Azure Monitor Agent on Azure virtual machines. Choose the appropriate command based on your chosen authentication method.

• Windows

  ## User-assigned managed identity
  Set-AzVMExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion <version-number> -EnableAutomaticUpgrade $true -SettingString '{"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
  Set-AzVMExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion <version-number> -EnableAutomaticUpgrade $true
  

• Linux

  ## User-assigned managed identity
  Set-AzVMExtension -Name AzureMonitorLinuxAgent -ExtensionType AzureMonitorLinuxAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion <version-number> -EnableAutomaticUpgrade $true -SettingString '{"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
  Set-AzVMExtension -Name AzureMonitorLinuxAgent -ExtensionType AzureMonitorLinuxAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Location <location> -TypeHandlerVersion <version-number> -EnableAutomaticUpgrade $true
  

Azure virtual machines scale set

Use the Add-AzVmssExtension PowerShell cmdlet to install Azure Monitor Agent on Azure virtual machines scale sets.

Azure Arc-enabled servers

Use the following PowerShell commands to install Azure Monitor Agent on Azure Arc-enabled servers.

• Windows

  New-AzConnectedMachineExtension -Name AzureMonitorWindowsAgent -ExtensionType AzureMonitorWindowsAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -MachineName <arc-server-name> -Location <arc-server-location> -EnableAutomaticUpgrade
  

• Linux

  New-AzConnectedMachineExtension -Name AzureMonitorLinuxAgent -ExtensionType AzureMonitorLinuxAgent -Publisher Microsoft.Azure.Monitor -ResourceGroupName <resource-group-name> -MachineName <arc-server-name> -Location <arc-server-location> -EnableAutomaticUpgrade
  

Azure CLI

You can install Azure Monitor Agent on Azure virtual machines and on Azure Arc-enabled servers by using the Azure CLI command for adding a virtual machine extension.

Azure virtual machines

Use the following CLI commands to install Azure Monitor Agent on Azure virtual machines. Choose the appropriate command based on your chosen authentication method.

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 CLI cmdlet to install Azure Monitor Agent on Azure virtual machines scale sets.

Azure Arc-enabled servers

Use the following CLI commands to install Azure Monitor Agent on Azure Arc-enabled servers.

• Windows

  az connectedmachine extension create --name AzureMonitorWindowsAgent --publisher Microsoft.Azure.Monitor --type AzureMonitorWindowsAgent --machine-name <arc-server-name> --resource-group <resource-group-name> --location <arc-server-location> --enable-auto-upgrade true
  

• Linux

  az connectedmachine extension create --name AzureMonitorLinuxAgent --publisher Microsoft.Azure.Monitor --type AzureMonitorLinuxAgent --machine-name <arc-server-name> --resource-group <resource-group-name> --location <arc-server-location> --enable-auto-upgrade true
  

Resource Manager template

You can use Resource Manager templates to install Azure Monitor Agent on Azure virtual machines and on Azure Arc-enabled servers and to create an association with data collection rules. You must create any data collection rule prior to creating the association.

Get sample templates for installing the agent and creating the association from the following resources:

• Template to install Azure Monitor Agent (Azure and Azure Arc)
• Template to create association with data collection rule

Install the templates by using any deployment method for Resource Manager templates, such as the following commands.

• PowerShell

  New-AzResourceGroupDeployment -ResourceGroupName "<resource-group-name>" -TemplateFile "<template-filename.json>" -TemplateParameterFile "<parameter-filename.json>"
  

• Azure CLI

  az deployment group create --resource-group "<resource-group-name>" --template-file "<path-to-template>" --parameters "@<parameter-filename.json>"
  

Uninstall

Portal

To uninstall 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 select AzureMonitorWindowsAgent or AzureMonitorLinuxAgent. In the dialog that opens, select Uninstall.

PowerShell

Uninstall on Azure virtual machines

Use the following PowerShell commands to uninstall Azure Monitor Agent on Azure virtual machines.

• Windows

  Remove-AzVMExtension -Name AzureMonitorWindowsAgent -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> 
  

• Linux

  Remove-AzVMExtension -Name AzureMonitorLinuxAgent -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> 
  

Uninstall on Azure virtual machines scale set

Use the Remove-AzVmssExtension PowerShell cmdlet to uninstall Azure Monitor Agent on Azure virtual machines scale sets.

Uninstall on Azure Arc-enabled servers

Use the following PowerShell commands to uninstall Azure Monitor Agent on Azure Arc-enabled servers.

• Windows

  Remove-AzConnectedMachineExtension -MachineName <arc-server-name> -ResourceGroupName <resource-group-name> -Name AzureMonitorWindowsAgent
  

• Linux

  Remove-AzConnectedMachineExtension -MachineName <arc-server-name> -ResourceGroupName <resource-group-name> -Name AzureMonitorLinuxAgent
  

Azure CLI

Uninstall on Azure virtual machines

Use the following CLI commands to uninstall Azure Monitor Agent on Azure virtual machines.

• 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 Azure virtual machines scale set

Use the az vmss extension delete CLI cmdlet to uninstall Azure Monitor Agent on Azure virtual machines scale sets.

Uninstall on Azure Arc-enabled servers

Use the following CLI commands to uninstall Azure Monitor Agent on Azure Arc-enabled servers.

• 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>
  

Resource Manager template

N/A

Update

Note

The recommendation is to enable Automatic Extension Upgrade which may take up to 5 weeks after a new extension version is released for it to update installed extensions to the released (latest) version across all regions. Upgrades are issued in batches, so you may see some of your virtual machines, scale-sets or Arc-enabled servers get upgraded before others. If you need to upgrade an extension immediately, you may use the manual instructions below.

Portal

To perform 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 the Automatic Extension Upgrade feature. Go to your virtual machine or scale set, select the Extensions tab and select AzureMonitorWindowsAgent or AzureMonitorLinuxAgent. In the dialog that opens, select Enable automatic upgrade.

PowerShell

Update on Azure virtual machines

To perform 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 the Automatic Extension Upgrade feature by using the following PowerShell commands.

• Windows

  Set-AzVMExtension -ExtensionName AzureMonitorWindowsAgent -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Publisher Microsoft.Azure.Monitor -ExtensionType AzureMonitorWindowsAgent -TypeHandlerVersion <version-number> -Location <location> -EnableAutomaticUpgrade $true
  

• Linux

  Set-AzVMExtension -ExtensionName AzureMonitorLinuxAgent -ResourceGroupName <resource-group-name> -VMName <virtual-machine-name> -Publisher Microsoft.Azure.Monitor -ExtensionType AzureMonitorLinuxAgent -TypeHandlerVersion <version-number> -Location <location> -EnableAutomaticUpgrade $true
  

Update on Azure Arc-enabled servers

To perform a one-time upgrade of the agent, use the following PowerShell commands.

• Windows

  $target = @{"Microsoft.Azure.Monitor.AzureMonitorWindowsAgent" = @{"targetVersion"=<target-version-number>}}
  Update-AzConnectedExtension -ResourceGroupName $env.ResourceGroupName -MachineName <arc-server-name> -ExtensionTarget $target
  

• Linux

  $target = @{"Microsoft.Azure.Monitor.AzureMonitorLinuxAgent" = @{"targetVersion"=<target-version-number>}}
  Update-AzConnectedExtension -ResourceGroupName $env.ResourceGroupName -MachineName <arc-server-name> -ExtensionTarget $target
  

We recommend that you enable automatic update of the agent by enabling the Automatic Extension Upgrade feature by using the following PowerShell commands.

• Windows

  Update-AzConnectedMachineExtension -ResourceGroup <resource-group-name> -MachineName <arc-server-name> -Name AzureMonitorWindowsAgent -EnableAutomaticUpgrade
  

• Linux

  Update-AzConnectedMachineExtension -ResourceGroup <resource-group-name> -MachineName <arc-server-name> -Name AzureMonitorLinuxAgent -EnableAutomaticUpgrade
  

Azure CLI

Update on Azure virtual machines

To perform 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 the Automatic Extension Upgrade feature by using the following 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 perform a one-time upgrade of the agent, use the following 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>
  

We recommend that you enable automatic update of the agent by enabling the Automatic Extension Upgrade feature by using the following PowerShell commands.

• Windows

  az connectedmachine extension update --name AzureMonitorWindowsAgent --machine-name <arc-server-name> --resource-group <resource-group-name> --enable-auto-upgrade true
  

• Linux

  az connectedmachine extension update --name AzureMonitorLinuxAgent --machine-name <arc-server-name> --resource-group <resource-group-name> --enable-auto-upgrade true
  

Resource Manager template

N/A

Configure

Data Collection Rules (DCRs) serve as a management tool for Azure Monitor Agent (AMA) on your machine. The AgentSettings DCR can be used to configure AMA parameters like DisQuotaInMb, ensuring your agent is tailored to your specific monitoring needs.

Note

Important considerations to keep in mind when working with the AgentSettings DCR:

• The AgentSettings DCR can only be configured via template deployment.
• AgentSettings is always it's own DCR and can't be added an existing one.
• For proper functionality, both the machine and the AgentSettings DCR must be located in the same region.

Supported parameters

The AgentSettings DCR currently supports configuring the following parameters:

Parameter	Description	Valid values
DiscQuotaInMb	Defines the amount of disk space used by the Azure Monitor Agent log files and cache.	1000-5000 (in MB)
TimeReceivedForForwardedEvents	Changes WEF column in the Sentinel WEF table to use TimeReceived instead of TimeGenerated data	0 or 1

Setting up AgentSettings DCR

Portal

Currently not supported.

PowerShell

N/A

Azure CLI

N/A

Resource Manager template

1. Prepare the environment:

   Install AMA on your VM.

2. Create a DCR via template deployment:

   The following example changes the maximum amount of disk space used by AMA cache to 5 GB.

   {
   "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
   "contentVersion": "1.0.0.0",
   "parameters": {},
   "resources": [
       {
       "type": "Microsoft.Insights/dataCollectionRules",
       "name": "dcr-contoso-01",
       "apiVersion": "2023-03-11",
       "properties": 
           {
           "description": "A simple agent settings",
           "agentSettings": 
               {
               "logs": [
                   {
                   "name": "MaxDiskQuotaInMB",
                   "value": "5000"
                   }
               ]
               }
           },
       "kind": "AgentSettings",
       "location": "eastus"
       }
   ]
   }
   

   Note

   You can use the Get DataCollectionRule API to get the DCR payload you created with this template.

3. Associate DCR with your machine:

   This can be done with a template or by using the Create API with the following details:

   • AssociationName: agentSettings
   • ResourceUri: Full ARM ID of the VM
   • api-version: 2023-03-11 (Old API version is also fine)
   • Body:

         {
         "properties": {
             "dataCollectionRuleId": “Full ARM ID for agent setting DCR”
             }
         }
     

4. Activate the settings:

   Restart AMA to apply changes.

Next steps

Create a data collection rule to collect data from the agent and send it to Azure Monitor.