Set up the Azure Monitor agent on Windows client devices - Azure Monitor (2023)

This article provides instructions and guidance for using the client installer for Azure Monitor Agent. It also explains how to leverage Data Collection Rules on Windows client devices.

Using the new client installer described here, you can now collect telemetry data from your Windows client devices in addition to servers and virtual machines.Both the extension and this installer use Data Collection rules to configure the same underlying agent.

Comparison with virtual machine extension

Here is a comparison between client installer and VM extension for Azure Monitor agent:

Supported device types

Prerequisites

1. The machine must be running Windows client OS version 10 RS4 or higher.
2. To download the installer, the machine should have C++ Redistributable version 2015) or higher
3. The machine must be domain joined to an Azure AD tenant (AADj or Hybrid AADj machines), which enables the agent to fetch Azure AD device tokens used to authenticate and fetch data collection rules from Azure.
4. You may need tenant admin permissions on the Azure AD tenant.
5. The device must have access to the following HTTPS endpoints:
   • global.handler.control.monitor.azure.com
   • <virtual-machine-region-name>.handler.control.monitor.azure.com (example: westus.handler.control.azure.com)
   • <log-analytics-workspace-id>.ods.opinsights.azure.com (example: 12345a01-b1cd-1234-e1f2-1234567g8h99.ods.opinsights.azure.com)(If using private links on the agent, you must also add the data collection endpoints)
6. A data collection rule you want to associate with the devices. If it doesn't exist already, create a data collection rule. Do not associate the rule to any resources yet.

Install the agent

1. Download the Windows MSI installer for the agent using this link. You can also download it from Monitor > Data Collection Rules > Create experience on Azure portal (shown below):

2. Open an elevated admin command prompt window and update path to the location where you downloaded the installer.

3. To install with default settings, run the following command:

    msiexec /i AzureMonitorAgentClientSetup.msi /qn

4. To install with custom file paths or network proxy settings, use the command below with the values from the following table:

    msiexec /i AzureMonitorAgentClientSetup.msi /qn DATASTOREDIR="C:\example\folder"

   Parameter	Description
   INSTALLDIR	Directory path where the agent binaries are installed
   DATASTOREDIR	Directory path where the agent stores its operational logs and data
   PROXYUSE	Must be set to "true" to use proxy
   PROXYADDRESS	Set to Proxy Address. PROXYUSE must be set to "true" to be correctly applied
   PROXYUSEAUTH	Set to "true" if proxy requires authentication
   PROXYUSERNAME	Set to Proxy username. PROXYUSE and PROXYUSEAUTH must be set to "true"
   PROXYPASSWORD	Set to Proxy password. PROXYUSE and PROXYUSEAUTH must be set to "true"

5. Verify successful installation:

   • Open Control Panel -> Programs and Features OR Settings -> Apps -> Apps & Features and ensure you see ‘Azure Monitor Agent’ listed
   • Open Services and confirm ‘Azure Monitor Agent’ is listed and shows as Running.

6. Proceed to create the monitored object that you'll associate data collection rules to, for the agent to actually start operating.

Create and associate a 'Monitored Object'

You need to create a 'Monitored Object' (MO) that creates a representation for the Azure AD tenant within Azure Resource Manager (ARM). This ARM entity is what Data Collection Rules are then associated with.Currently this association is only limited to the Azure AD tenant scope, which means configuration applied to the tenant will be applied to all devices that are part of the tenant and running the agent.The image below demonstrates how this works:

Then, proceed with the instructions below to create and associate them to a Monitored Object, using REST APIs or PowerShell commands.

Permissions required

Since MO is a tenant level resource, the scope of the permission would be higher than a subscription scope. Therefore, an Azure tenant admin may be needed to perform this step. Follow these steps to elevate Azure AD Tenant Admin as Azure Tenant Admin. It will give the Azure AD admin 'owner' permissions at the root scope. This is needed for all methods described below in this section.

Using REST APIs

1. Assign ‘Monitored Object Contributor’ role to the operator

This step grants the ability to create and link a monitored object to a user.

Request URI

PUT https://management.azure.com/providers/microsoft.insights/providers/microsoft.authorization/roleassignments/{roleAssignmentGUID}?api-version=2021-04-01-preview

URI Parameters

Headers

• Authorization: ARM Bearer Token (using ‘Get-AzAccessToken’ or other method)
• Content-Type: Application/json

Request Body

{"properties":{"roleDefinitionId":"/providers/Microsoft.Authorization/roleDefinitions/56be40e24db14ccf93c37e44c597135b","principalId":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}}

Body parameters

After this step is complete, reauthenticate your session and reacquire your ARM bearer token.

2. Create Monitored Object

This step creates the Monitored Object for the Azure AD Tenant scope. It will be used to represent client devices that are signed with that Azure AD Tenant identity.

Permissions required: Anyone who has 'Monitored Object Contributor' at an appropriate scope can perform this operation, as assigned in step 1.

Request URI

PUT https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/{AADTenantId}?api-version=2021-09-01-preview

URI Parameters

Headers

• Authorization: ARM Bearer Token
• Content-Type: Application/json

Request Body

{ "properties":{ "location":"eastus" }}

Body parameters

3. Associate DCR to Monitored Object

Now we associate the Data Collection Rules (DCR) to the Monitored Object by creating Data Collection Rule Associations.

Permissions required: Anyone who has ‘Monitored Object Contributor’ at an appropriate scope can perform this operation, as assigned in step 1.

Request URI

PUT https://management.azure.com/{MOResourceId}/providers/microsoft.insights/datacollectionruleassociations/{associationName}?api-version=2021-09-01-preview

Sample Request URI

PUT https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/{AADTenantId}/providers/microsoft.insights/datacollectionruleassociations/{associationName}?api-version=2021-09-01-preview

URI Parameters

Headers

• Authorization: ARM Bearer Token
• Content-Type: Application/json

Request Body

{"properties":{"dataCollectionRuleId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Insights/dataCollectionRules/{DCRName}"}}

Body parameters

Using PowerShell for onboarding

$TenantID = "xxxxxxxxx-xxxx-xxx" #Your Tenant ID$SubscriptionID = "xxxxxx-xxxx-xxxxx" #Your Subscription ID$ResourceGroup = "rg-yourResourseGroup" #Your resroucegroupConnect-AzAccount -Tenant $TenantID#Select the subscriptionSelect-AzSubscription -SubscriptionId $SubscriptionID#Grant Access to User at root scope "/"$user = Get-AzADUser -UserPrincipalName (Get-AzContext).AccountNew-AzRoleAssignment -Scope '/' -RoleDefinitionName 'Owner' -ObjectId $user.Id#Create Auth Token$auth = Get-AzAccessToken$AuthenticationHeader = @{ "Content-Type" = "application/json" "Authorization" = "Bearer " + $auth.Token }#1. Assign ‘Monitored Object Contributor’ Role to the operator$newguid = (New-Guid).Guid$UserObjectID = $user.Id$body = @"{ "properties": { "roleDefinitionId":"/providers/Microsoft.Authorization/roleDefinitions/56be40e24db14ccf93c37e44c597135b", "principalId": `"$UserObjectID`" }}"@$requestURL = "https://management.azure.com/providers/microsoft.insights/providers/microsoft.authorization/roleassignments/$newguid`?api-version=2021-04-01-preview"Invoke-RestMethod -Uri $requestURL -Headers $AuthenticationHeader -Method PUT -Body $body###########################2. Create Monitored Object# "location" property value under the "body" section should be the Azure region where the MO object would be stored. It should be the "same region" where you created the Data Collection Rule. This is the location of the region from where agent communications would happen.$Location = "eastus" #Use your own loacation$requestURL = "https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/$TenantID`?api-version=2021-09-01-preview"$body = @"{ "properties":{ "location":`"$Location`" }}"@$Respond = Invoke-RestMethod -Uri $requestURL -Headers $AuthenticationHeader -Method PUT -Body $body -Verbose$RespondID = $Respond.id###########################3. Associate DCR to Monitored Object#See reference documentation https://learn.microsoft.com/en-us/rest/api/monitor/data-collection-rule-associations/create?tabs=HTTP$associationName = "assoc01" #You can define your custom associationname, must change the association name to a unique name, if you want to associate multiple DCR to monitored object$DCRName = "dcr-WindowsClientOS" #Your Data collection rule name$requestURL = "https://management.azure.com$RespondId/providers/microsoft.insights/datacollectionruleassociations/$associationName`?api-version=2021-09-01-preview"$body = @" { "properties": { "dataCollectionRuleId": "/subscriptions/$SubscriptionID/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/dataCollectionRules/$DCRName" } }"@Invoke-RestMethod -Uri $requestURL -Headers $AuthenticationHeader -Method PUT -Body $body#(Optional example). Associate another DCR to Monitored Object#See reference documentation https://learn.microsoft.com/en-us/rest/api/monitor/data-collection-rule-associations/create?tabs=HTTP$associationName = "assoc02" #You must change the association name to a unique name, if you want to associate multiple DCR to monitored object$DCRName = "dcr-PAW-WindowsClientOS" #Your Data collection rule name$requestURL = "https://management.azure.com$RespondId/providers/microsoft.insights/datacollectionruleassociations/$associationName`?api-version=2021-09-01-preview"$body = @" { "properties": { "dataCollectionRuleId": "/subscriptions/$SubscriptionID/resourceGroups/$ResourceGroup/providers/Microsoft.Insights/dataCollectionRules/$DCRName" } }"@Invoke-RestMethod -Uri $requestURL -Headers $AuthenticationHeader -Method PUT -Body $body#4. (Optional) Get all the associatation.$requestURL = "https://management.azure.com$RespondId/providers/microsoft.insights/datacollectionruleassociations?api-version=2021-09-01-preview"(Invoke-RestMethod -Uri $requestURL -Headers $AuthenticationHeader -Method get).value

Using PowerShell for offboarding

#This will remove the monitor object$TenantID = "xxxxxxxxx-xxxx-xxx" #Your Tenant ID$SubscriptionID = "xxxxxx-xxxx-xxxxx" #Your Subscription ID$ResourceGroup = "rg-yourResourseGroup" #Your resroucegroupConnect-AzAccount -Tenant $TenantID#Select the subscriptionSelect-AzSubscription -SubscriptionId $SubscriptionID#Delete monitored object$requestURL = "https://management.azure.com/providers/Microsoft.Insights/monitoredObjects/$TenantID`?api-version=2021-09-01-preview"#Invoke-RestMethod -Uri $requestURL -Headers $AuthenticationHeader -Method Delete

Verify successful setup

Check the ‘Heartbeat’ table (and other tables you configured in the rules) in the Log Analytics workspace that you specified as a destination in the data collection rule(s).The SourceComputerId, Computer, ComputerIP columns should all reflect the client device information respectively, and the Category column should say 'Azure Monitor Agent'. See example below:

Manage the agent

Check the agent version

You can use any of the following options to check the installed version of the agent:

• Open Control Panel > Programs and Features > Azure Monitor Agent and see the 'Version' listed
• Open Settings > Apps > Apps and Features > Azure Monitor Agent and see the 'Version' listed

Uninstall the agent

You can use any of the following options to check the installed version of the agent:

• Open Control Panel > Programs and Features > Azure Monitor Agent and click 'Uninstall'
• Open Settings > Apps > Apps and Features > Azure Monitor Agent and click 'Uninstall'

If you face issues during 'Uninstall', refer to troubleshooting guidance below

Update the agent

In order to update the version, install the new version you wish to update to.

Troubleshoot

View agent diagnostic logs

1. Rerun the installation with logging turned on and specify the log file name:Msiexec /I AzureMonitorAgentClientSetup.msi /L*V <log file name>
2. Runtime logs are collected automatically either at the default location C:\Resources\Azure Monitor Agent\ or at the file path mentioned during installation.
   • If you can't locate the path, the exact location can be found on the registry as AMADataRootDirPath on HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AzureMonitorAgent.
3. The 'ServiceLogs' folder contains log from AMA Windows Service, which launches and manages AMA processes
4. 'AzureMonitorAgent.MonitoringDataStore' contains data/logs from AMA processes.

Common installation issues

Missing DLL

• Error message: "There's a problem with this Windows Installer package. A DLL required for this installer to complete could not be run. …"
• Ensure you have installed C++ Redistributable (>2015) before installing AMA:

Not AAD joined

Error message: "Tenant and device ids retrieval failed"

1. Run the command dsregcmd /status. This should produce the output as AzureAdJoined : YES in the 'Device State' section. If not, join the device with an AAD tenant and try installation again.

Silent install from command prompt fails

Make sure to start the installer on administrator command prompt. Silent install can only be initiated from the administrator command prompt.

Uninstallation fails due to the uninstaller being unable to stop the service

• If There's an option to try again, do try it again
• If retry from uninstaller doesn't work, cancel the uninstall and stop Azure Monitor Agent service from Services (Desktop Application)
• Retry uninstall

Force uninstall manually when uninstaller doesn't work

• Stop Azure Monitor Agent service. Then try uninstalling again. If it fails, then proceed with the following steps
• Delete AMA service with "sc delete AzureMonitorAgent" from admin cmd
• Download this tool and uninstall AMA
• Delete AMA binaries. They're stored in Program Files\Azure Monitor Agent by default
• Delete AMA data/logs. They're stored in C:\Resources\Azure Monitor Agent by default
• Open Registry. Check HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Azure Monitor Agent. If it exists, delete the key.

Post installation/Operational issues

Once the agent is installed successfully (i.e. you see the agent service running but don't see data as expected), you can follow standard troubleshooting steps listed here for Windows VM and Windows Arc-enabled server respectively.

Questions and feedback

Take this quick survey or share your feedback/questions regarding the client installer.