How to use the Windows operating system (OS) Azure Monitor Agent Troubleshooter

The Azure Monitor Agent (AMA) Troubleshooter is designed to help identify issues with the agent and perform general health assessments. It can perform various checks to ensure that the agent is properly installed and connected, and can also gather AMA-related logs from the machine being diagnosed.

Note

The Windows AMA Troubleshooter is a command line executable that is shipped with the agent for all versions newer than 1.12.0.0.

Prerequisites

Troubleshooter existence check

Check for the existence of the AMA Agent Troubleshooter directory on the machine to be diagnosed to confirm the installation of the agent troubleshooter:

AMA Extension - PowerShell

To verify the Agent Troubleshooter is present, copy the following command and run in PowerShell as administrator:

Test-Path -Path "C:/Packages/Plugins/Microsoft.Azure.Monitor.AzureMonitorWindowsAgent"

If the directory exists, the Test-Path cmdlet returns True.

AMA Extension - Command Prompt

To verify the Agent Troubleshooter is present, copy the following command and run in Command Prompt as administrator:

cd "C:/Packages/Plugins/Microsoft.Azure.Monitor.AzureMonitorWindowsAgent"

If the directory exists, the cd command changes directories successfully.

AMA Standalone - PowerShell

To verify the Agent Troubleshooter is present, copy the following command and run in PowerShell as administrator:

$installPath = (Get-ItemProperty -Path "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AzureMonitorAgent").AMAInstallPath
Test-Path -Path $installPath\Troubleshooter

If the directory exists, the Test-Path cmdlet returns True.

AMA Standalone - Command Prompt

To verify the Agent Troubleshooter is present, copy the following command and run in Command Prompt as administrator:

Note

If you have customized the AMAInstallPath, you'll need to adjust the below path to your custom path.

cd "C:\Program Files\Azure Monitor Agent\Troubleshooter"

If the directory exists, the cd command changes directories successfully.

If directory doesn't exist or the installation is failed, follow Basic troubleshooting steps.

Yes, the directory exists. Proceed to Run the Troubleshooter.

Run the Troubleshooter

On the machine to be diagnosed, run the Agent Troubleshooter.

AMA Extension - PowerShell

To start the Agent Troubleshooter, copy the following command and run in PowerShell as administrator:

$currentVersion = ((Get-ChildItem -Path "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Azure\HandlerState\" `
    | where Name -like "*AzureMonitorWindowsAgent*" `
    | ForEach-Object {$_ | Get-ItemProperty} `
    | where InstallState -eq "Enabled").PSChildName -split('_'))[1]

$troubleshooterPath = "C:\Packages\Plugins\Microsoft.Azure.Monitor.AzureMonitorWindowsAgent\$currentVersion\Troubleshooter"
Set-Location -Path $troubleshooterPath
Start-Process -FilePath $troubleshooterPath\AgentTroubleshooter.exe -ArgumentList "--ama"
Invoke-Item $troubleshooterPath

It runs a series of activities that could take up to 15 minutes to complete. Be patient until the process completes.

AMA Extension - Command Prompt

To start the Agent Troubleshooter, copy the following command and run in Command Prompt as administrator:

Note

Note: You'll need to update the {version} to match your installed version number. In the following example, the version is 1.20.0.0.

cd C:/Packages/Plugins/Microsoft.Azure.Monitor.AzureMonitorWindowsAgent/{version}/Troubleshooter/
AgentTroubleshooter.exe --ama

It runs a series of activities that could take up to 15 minutes to complete. Be patient until this process completes.

AMA Standalone - PowerShell

To start the Agent Troubleshooter, copy the following command and run in PowerShell as administrator:

$installPath = (Get-ItemProperty -Path "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AzureMonitorAgent").AMAInstallPath
Set-Location -Path $installPath\Troubleshooter
Start-Process -FilePath $installPath\Troubleshooter\AgentTroubleshooter.exe -ArgumentList "--ama"
Invoke-Item $installPath\Troubleshooter

It runs a series of activities that could take up to 15 minutes to complete. Be patient until the process completes.

AMA Standalone - Command Prompt

To start the Agent Troubleshooter, copy the following command and run in Command Prompt as administrator:

Note

If you have customized the AMAInstallPath, you'll need to adjust the below path to your custom path.

cd "C:\Program Files\Azure Monitor Agent\Troubleshooter"
AgentTroubleshooter.exe --ama

It runs a series of activities that could take up to 15 minutes to complete. Be patient until this process completes.

Log file is created in the directory where the AgentTroubleshooter.exe is located.

Example for extension-based install:

Example for standalone install:

Frequently Asked Questions

Can I copy the Troubleshooter from a newer agent to an older agent and run it on the older agent to diagnose issues with the older agent?

It isn't possible to use the Troubleshooter to diagnose an older version of the agent by copying it. You must have an up-to-date version of the agent for the Troubleshooter to work properly.

Next Steps

• Troubleshooting guidance for the Azure Monitor agent on Windows virtual machines and scale sets
• Troubleshooting guidance for the Azure Monitor agent on Windows Arc-enabled server