Azure Performance Diagnostics (PerfInsights) VM Extension for Windows

Applies to: ✔️ Windows VMs

Azure Performance Diagnostics VM Extension helps collect performance diagnostic data from Windows VMs. The extension performs analysis, and provides a report of findings and recommendations to identify and resolve performance issues on the virtual machine. This extension installs a troubleshooting tool called PerfInsights.

Prerequisites

This extension can be installed on:

• Windows Server 2019
• Windows Server 2016
• Windows Server 2012 R2
• Windows Server 2012
• Windows Server 2008 R2
• Windows 10
• Windows 8.1
• Windows 8

Extension schema

The following JSON shows the schema for Azure Performance Diagnostics VM Extension. This extension requires the name and key for a storage account to store the diagnostics output and report. These values are sensitive. Storage account key should be stored inside a protected setting configuration. Azure VM extension protected setting data is encrypted, and it is only decrypted on the target virtual machine. Note that storageAccountName and storageAccountKey are case-sensitive. Other required parameters are listed in the following section.

{
     "name": "[concat(parameters('vmName'),'/AzurePerformanceDiagnostics')]",
     "type": "Microsoft.Compute/virtualMachines/extensions",
     "location": "[parameters('location')]",
     "apiVersion": "2015-06-15",
     "properties": {
       "publisher": "Microsoft.Azure.Performance.Diagnostics",
       "type": "AzurePerformanceDiagnostics",
       "typeHandlerVersion": "1.0",
       "autoUpgradeMinorVersion": true,
       "settings": {
         "storageAccountName": "[parameters('storageAccountName')]",
         "performanceScenario": "[parameters('performanceScenario')]",
         "enableContinuousDiagnostics": "[parameters('enableContinuousDiagnostics')]",
         "traceDurationInSeconds": "[parameter('traceDurationInSeconds')]",
         "perfCounterTrace": "[parameters('perfCounterTrace')]",
         "networkTrace": "[parameters('networkTrace')]",
         "xperfTrace": "[parameters('xperfTrace')]",
         "storPortTrace": "[parameters('storPortTrace')]",         
         "requestTimeUtc":  "[parameters('requestTimeUtc')]",
         "resourceId": "[resourceId('Microsoft.Compute/virtualMachines', parameters('vmName'))]"
       },
       "protectedSettings": {
           "storageAccountKey": "[parameters('storageAccountKey')]"       
       }
     }
   }

Property values

Install the extension

Follow these instructions to install the extension on Windows virtual machines:

1. Sign in to the Azure portal.

2. Select the virtual machine where you want to install this extension.

   

3. Select the Extensions + applications blade, and select Add.

   

4. Search for Azure Performance Diagnostics, click the extension, review the terms and conditions, and select Next.

   

5. Provide the parameter values for the installation, and then install the extension. For more information about supported scenarios, see How to use PerfInsights.

   

6. When the installation is successful, the status of the extension shows Provisioning succeeded.

   

   Note

   The extension runs when the provisioning has succeeded. It takes two minutes or less to complete for the basic scenario. For other scenarios, it runs through the duration specified during the installation.

Remove the extension

To remove the extension from a virtual machine, follow these steps:

1. Sign in to the Azure portal, select the virtual machine from which you want to remove this extension, and then select the Extensions + applications blade.

2. Select the Performance Diagnostics Extension, and then select Uninstall.

   

Template deployment

Azure virtual machine extensions can be deployed with Azure Resource Manager templates. The JSON schema detailed in the previous section can be used in an Azure Resource Manager template. This runs the Azure Performance Diagnostics VM extension during an Azure Resource Manager template deployment. Here is a sample template:

{
 "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
 "contentVersion": "1.0.0.0",
 "parameters": {
   "vmName": {
     "type": "string",
     "defaultValue": "yourVMName"
   },
   "location": {
     "type": "string",
     "defaultValue": "southcentralus"
   },
   "storageAccountName": {
     "type": "securestring",
     "defaultValue": "yourStorageAccount"
   },
   "storageAccountKey": {
     "type": "securestring",
     "defaultValue": "yourStorageAccountKey"
   },
   "performanceScenario": {
     "type": "string",
     "defaultValue": "basic"
   },
 
"enableContinuousDiagnostics": {
     "type": "boolean",
     "defaultValue": "false"
  },
  "traceDurationInSeconds": {
   "type": "int",
   "defaultValue": 300
 },
   "perfCounterTrace": {
     "type": "string",
     "defaultValue": "p"
   },
   "networkTrace": {
     "type": "string",
     "defaultValue": ""
   },
   "xperfTrace": {
     "type": "string",
     "defaultValue": ""
   },
   "storPortTrace": {
     "type": "string",
     "defaultValue": ""
   },
   "requestTimeUtc": {
     "type": "string",
     "defaultValue": "10/2/2017 11:06:00 PM"
   }       
 },
 "resources": [
   {
     "name": "[concat(parameters('vmName'),'/AzurePerformanceDiagnostics')]",
     "type": "Microsoft.Compute/virtualMachines/extensions",
     "location": "[parameters('location')]",
     "apiVersion": "2015-06-15",
     "properties": {
       "publisher": "Microsoft.Azure.Performance.Diagnostics",
       "type": "AzurePerformanceDiagnostics",
       "typeHandlerVersion": "1.0",
       "autoUpgradeMinorVersion": true,
       "settings": {
         "storageAccountName": "[parameters('storageAccountName')]",
         "performanceScenario": "[parameters('performanceScenario')]",
"enableContinuousDiagnostics" : "[parameters('enableContinuousDiagnostics')]",
         "traceDurationInSeconds": "[parameters('traceDurationInSeconds')]",
         "perfCounterTrace": "[parameters('perfCounterTrace')]",
         "networkTrace": "[parameters('networkTrace')]",
         "xperfTrace": "[parameters('xperfTrace')]",
         "storPortTrace": "[parameters('storPortTrace')]",         
         "requestTimeUtc":  "[parameters('requestTimeUtc')]",
         "resourceId": "[resourceId('Microsoft.Compute/virtualMachines', parameters('vmName'))]"
       },
       "protectedSettings": {
           "storageAccountKey": "[parameters('storageAccountKey')]"
       }
     }
   }
 ]
}

PowerShell deployment

Use the Set-AzVMExtension command to deploy Azure Performance Diagnostics VM Extension to an existing virtual machine:

$PublicSettings = @{ "storageAccountName"="mystorageaccount";"performanceScenario"="basic"; "enableContinuousDiagnostics" : $False;"traceDurationInSeconds"=300;"perfCounterTrace"="p";"networkTrace"="";"xperfTrace"="";"storPortTrace"="";"srNumber"="";"requestTimeUtc"="2017-09-28T22:08:53.736Z";"resourceId"="VMResourceId" }
$ProtectedSettings = @{"storageAccountKey"="mystoragekey" }
 
Set-AzVMExtension -ExtensionName "AzurePerformanceDiagnostics" -ResourceGroupName "myResourceGroup" -VMName "myVM" -Publisher "Microsoft.Azure.Performance.Diagnostics" -ExtensionType "AzurePerformanceDiagnostics" -TypeHandlerVersion 1.0 -Settings $PublicSettings -ProtectedSettings $ProtectedSettings -Location WestUS

Information on the data captured

The PerfInsights tool collects various logs, configuration, and diagnostic data, depending on the selected scenario. For more information, see the PerfInsights documentation.

View and share the results

Output from the extension can be found in a zip file that uploaded to the storage account specified during the installation and is shared for 30 days by using Shared Access Signatures (SAS). This zip file contains diagnostic logs and a report with findings and recommendations. A SAS link to the output zip file can be found inside a text file named zipfilename_saslink.txt under the folder C:\Packages\Plugins\Microsoft.Azure.Performance.Diagnostics.AzurePerformanceDiagnostics\<version>. Anyone who has this link is able to download the zip file.

To assist the support engineer working on your support ticket, Microsoft might use this SAS link to download the diagnostics data.

To view the report, extract the zip file and open the PerfInsights Report.html file.

You should also be able to download the zip file directly from the portal by selecting the extension.

Troubleshoot and support

• Extension deployment status (in the notification area) might show "Deployment in progress" even though the extension is successfully provisioned.

  This issue can be safely ignored, as long as the extension status indicates that the extension is successfully provisioned.

• You can address some issues during installation by using the extension logs. Extension execution output is logged to files found in the following directory:

  C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.Performance.Diagnostics.AzurePerformanceDiagnostics\<version>

• If you see the following errors in the Azure portal or Performance Diagnostics extension logs (AzPerfDiagExtension.log or PerfInsights.log), this usually means the HTTPS certificate chain is broken:

  • Provisioning Failed - message: Failed to upload the PerfInsights result to Azure storage account.

  • PerfInsights process exited with code 1700.

  • Could not establish trust relationship for the SSL/TLS secure channel. The remote certificate is invalid according to the validation procedure.

  To resolve the errors, ensure that you don't have a Network Security Group (NSG) blocking access to the Certificate Authority URLs described in this list. Or ensure that you don't have any SSL inspection tool in your Network Virtual Appliance or firewall.

Contact us for help

If you have questions or need help, create a support request, or ask Azure community support. You can also submit product feedback to Azure feedback community.