Diagnostic logging with Azure SDK 2.5

Azure SDK 2.5 was announced on November 12th 2014.  Among other changes, the SDK includes Azure Diagnostics Client Library 1.3, which has significant and breaking changes since previous versions (Azure SDK 2.4 and previous versions used Diagnostics 1.0).

One of the primary reasons for the change is to move from a plugin model to an extension model. This means the diagnostic extension and the Role itself are decoupled. The extension is installed separately and doesn't require a redeployment of the role.

The move to an extension model means diagnostics can now be used with Virtual Machines as well as Cloud Services.

Configuration

Previously there was a Diagnostics import in the csdef file of the Role, and a storage account connection string in the Role's configuration file. It was also possible to configure diagnostics  via code or via XML (in the wadcfg file).

These are no longer present or possible and all diagnostic configuration is in a wadcfgx file.

This configuration can be managed in Visual Studio by right-clicking on the Role and selecting Properties, then on the Configuration tab ensure Enable Diagnostics is ticked and click Configure. This will bring up the Diagnostics configuration window.

See this article for steps on how to use diagnostics 1.3 with Cloud Services and Virtual Machines. For more detail on the diagnostics changes required when upgrading to Azure SDK 2.5, take a look at this excellent article.

Deployment

The SDK changes also mean the way diagnostics is deployed has changed. When deploying directly from Visual Studio, it automatically handles deployment of the diagnostics extension for you. If deploying from a different build infrastructure like TeamCity, an additional step and some PowerShell will be necessary:

Set-AzureServiceDiagnosticsExtension –StorageContext [storage context] –DiagnosticsConfigurationPath [public config] –ServiceName [service name] –Slot 'Staging' –Role 'WorkerRole1'

The storage context can be created with:

New-AzureStorageContext –StorageAccountName [name] –StorageAccountKey [key]

The diagnostics configuration path should point at an XML file, that is a transform of the wadcfgx file. It should contain the xml header (version and encoding) and the PublicConfig section only. Note that the wadcfgx file is not deployed along with the Role, so this additional step should be performed by your existing deployment process.

Gotchas

While upgrading to this newer version, you might find that application logs are not being saved. If you come across this problem, make sure the appropriate trace listener is defined in app or web config.

When creating a new web or worker role and enabling diagnostics, this trace listener config was automatically added. However, I found it did not get added in a project being upgraded and had to add it manually.