Edit

Enable diagnostics in Azure Cloud Services (classic) using PowerShell

  • Article

Important

Cloud Services (classic) is now deprecated for new customers and will be retired on August 31st, 2024 for all customers. New deployments should use the new Azure Resource Manager based deployment model Azure Cloud Services (extended support).

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 will automatically use that storage account. For this 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 will include the storage account name based on the diagnostics configuration string specified in the service configuration file (.cscfg). The script below 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 Online 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 the StorageAccountName parameter is specified, then the cmdlet will always use the storage account that is specified in the parameter and not the one that is 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 is not 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.

Warning

When you enable diagnostics for an existing role, any extensions that you have already set are disabled when the package is deployed. These include:

  • Microsoft Monitoring Agent Diagnostics
  • Microsoft Azure Security Monitoring
  • Microsoft Antimalware
  • Microsoft Monitoring Agent
  • Microsoft Service Profiler Agent
  • Windows Azure Domain Extension
  • Windows Azure Diagnostics Extension
  • Windows Azure Remote Desktop Extension
  • Windows Azure Log Collector

You can reset your extensions via the Azure portal or PowerShell after you deploy the updated role.

$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