Enable diagnostics in Azure Cloud Services (classic) using PowerShell

You can collect diagnostic data like application logs, performance counters etc. from a Cloud Service using the Azure Diagnostics extension. This article describes how to enable the Azure Diagnostics extension for a Cloud Service using PowerShell. See How to install and configure Azure PowerShell for the prerequisites needed for this article.

Enable diagnostics extension as part of deploying a Cloud Service

This approach is applicable to continuous integration type of scenarios, where the diagnostics extension can be enabled as part of deploying the cloud service. When creating a new Cloud Service deployment, you can enable the diagnostics extension by passing in the ExtensionConfiguration parameter to the New-AzureDeployment cmdlet. The ExtensionConfiguration parameter takes an array of diagnostics configurations that can be created using the New-AzureServiceDiagnosticsExtensionConfig cmdlet.

The following example shows how you can enable diagnostics for a cloud service with a WebRole and WorkerRole, each having a different diagnostics configuration.

$service_name = "MyService"
$service_package = "CloudService.cspkg"
$service_config = "ServiceConfiguration.Cloud.cscfg"
$webrole_diagconfigpath = "MyService.WebRole.PubConfig.xml"
$workerrole_diagconfigpath = "MyService.WorkerRole.PubConfig.xml"

$webrole_diagconfig = New-AzureServiceDiagnosticsExtensionConfig -Role "WebRole" -DiagnosticsConfigurationPath $webrole_diagconfigpath
$workerrole_diagconfig = New-AzureServiceDiagnosticsExtensionConfig -Role "WorkerRole" -DiagnosticsConfigurationPath $workerrole_diagconfigpath

New-AzureDeployment -ServiceName $service_name -Slot Production -Package $service_package -Configuration $service_config -ExtensionConfiguration @($webrole_diagconfig,$workerrole_diagconfig)

If the diagnostics configuration file specifies a StorageAccount element with a storage account name, then the New-AzureServiceDiagnosticsExtensionConfig cmdlet automatically uses that storage account. For this configuration to work, the storage account needs to be in the same subscription as the Cloud Service being deployed.

From Azure SDK 2.6 onward, the extension configuration files generated by the MSBuild publish target output includes the storage account name based on the diagnostics configuration string specified in the service configuration file (.cscfg). The following script shows you how to parse the Extension configuration files from the publish target output and configure diagnostics extension for each role when deploying the cloud service.

$service_name = "MyService"
$service_package = "C:\build\output\CloudService.cspkg"
$service_config = "C:\build\output\ServiceConfiguration.Cloud.cscfg"

#Find the Extensions path based on service configuration file
$extensionsSearchPath = Join-Path -Path (Split-Path -Parent $service_config) -ChildPath "Extensions"

$diagnosticsExtensions = Get-ChildItem -Path $extensionsSearchPath -Filter "PaaSDiagnostics.*.PubConfig.xml"
$diagnosticsConfigurations = @()
foreach ($extPath in $diagnosticsExtensions)
{
    #Find the RoleName based on file naming convention PaaSDiagnostics.<RoleName>.PubConfig.xml
    $roleName = ""
    $roles = $extPath -split ".",0,"simplematch"
    if ($roles -is [system.array] -and $roles.Length -gt 1)
    {
        $roleName = $roles[1]
        $x = 2
        while ($x -le $roles.Length)
            {
               if ($roles[$x] -ne "PubConfig")
                {
                    $roleName = $roleName + "." + $roles[$x]
                }
                else
                {
                    break
                }
                $x++
            }
        $fullExtPath = Join-Path -path $extensionsSearchPath -ChildPath $extPath
        $diagnosticsconfig = New-AzureServiceDiagnosticsExtensionConfig -Role $roleName -DiagnosticsConfigurationPath $fullExtPath
        $diagnosticsConfigurations += $diagnosticsconfig
    }
}
New-AzureDeployment -ServiceName $service_name -Slot Production -Package $service_package -Configuration $service_config -ExtensionConfiguration $diagnosticsConfigurations

Visual Studio Codespace uses a similar approach for automated deployments of Cloud Services with the diagnostics extension. See Publish-AzureCloudDeployment.ps1 for a complete example.

If no StorageAccount was specified in the diagnostics configuration, then you need to pass in the StorageAccountName parameter to the cmdlet. If you specify the StorageAccountName parameter, then the cmdlet uses the storage account specified in the parameter and not the one specified in the diagnostics configuration file.

If the diagnostics storage account is in a different subscription from the Cloud Service, then you need to explicitly pass in the StorageAccountName and StorageAccountKey parameters to the cmdlet. The StorageAccountKey parameter isn't needed when the diagnostics storage account is in the same subscription, as the cmdlet can automatically query and set the key value when enabling the diagnostics extension. However, if the diagnostics storage account is in a different subscription, then the cmdlet might not be able to get the key automatically and you need to explicitly specify the key through the StorageAccountKey parameter.

$webrole_diagconfig = New-AzureServiceDiagnosticsExtensionConfig -Role "WebRole" -DiagnosticsConfigurationPath $webrole_diagconfigpath -StorageAccountName $diagnosticsstorage_name -StorageAccountKey $diagnosticsstorage_key
$workerrole_diagconfig = New-AzureServiceDiagnosticsExtensionConfig -Role "WorkerRole" -DiagnosticsConfigurationPath $workerrole_diagconfigpath -StorageAccountName $diagnosticsstorage_name -StorageAccountKey $diagnosticsstorage_key

Enable diagnostics extension on an existing Cloud Service

You can use the Set-AzureServiceDiagnosticsExtension cmdlet to enable or update diagnostics configuration on a Cloud Service that is already running.

$service_name = "MyService"
$webrole_diagconfigpath = "MyService.WebRole.PubConfig.xml"
$workerrole_diagconfigpath = "MyService.WorkerRole.PubConfig.xml"

$webrole_diagconfig = New-AzureServiceDiagnosticsExtensionConfig -Role "WebRole" -DiagnosticsConfigurationPath $webrole_diagconfigpath
$workerrole_diagconfig = New-AzureServiceDiagnosticsExtensionConfig -Role "WorkerRole" -DiagnosticsConfigurationPath $workerrole_diagconfigpath

Set-AzureServiceDiagnosticsExtension -DiagnosticsConfiguration @($webrole_diagconfig,$workerrole_diagconfig) -ServiceName $service_name

Get current diagnostics extension configuration

Use the Get-AzureServiceDiagnosticsExtension cmdlet to get the current diagnostics configuration for a cloud service.

Get-AzureServiceDiagnosticsExtension -ServiceName "MyService"

Remove diagnostics extension

To turn off diagnostics on a cloud service, you can use the Remove-AzureServiceDiagnosticsExtension cmdlet.

Remove-AzureServiceDiagnosticsExtension -ServiceName "MyService"

If you enabled the diagnostics extension using either Set-AzureServiceDiagnosticsExtension or the New-AzureServiceDiagnosticsExtensionConfig without the Role parameter, then you can remove the extension using Remove-AzureServiceDiagnosticsExtension without the Role parameter. If the Role parameter was used when enabling the extension, then it must also be used when removing the extension.

To remove the diagnostics extension from each individual role:

Remove-AzureServiceDiagnosticsExtension -ServiceName "MyService" -Role "WebRole"

Next Steps

• For more information on using Azure diagnostics and other techniques to troubleshoot problems, see Enabling Diagnostics in Azure Cloud Services and Virtual Machines.
• The Diagnostics Configuration Schema explains the various xml configurations options for the diagnostics extension.
• To learn how to enable the diagnostics extension for Virtual Machines, see Create a Windows Virtual machine with monitoring and diagnostics using Azure Resource Manager Template