Enable diagnostics in Azure Cloud Services (classic) using PowerShell
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 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.
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
- 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