Configuring diagnostics.wadcfg to Capture Custom Log Files
Windows Azure Diagnostics (WAD) has the ability to copy files to Azure blob storage. The feature is meant for copying custom log files but you can use it to copy any file that WAD has permission to access. To configure this feature via diagnostics.wadcfg add appropriate <DataSource> and <DirectoryConfiguration> elements to the XML.
Within <DirectoryConfiguration> there is the option to use <Absolute> or <LocalResource>. The local resource approach is appropriate in most situations since absolute paths are harder to define which exist in both the DevFabric and Azure environments. The MSDN documentation covering diagnostics.wadcfg shows the use of an absolute path to copy the logs from a %SystemRoot% location.
For custom logs use the local resource approach. The configuration steps are:
Define a <LocalStorage> element in ServiceDefinition.csdef. Set the name attribute to any value desired. Set the sizeInMB attribute value large enough to hold the anticipated log data. Set cleanOnRoleRecycle to false for reasons discussed below.
Add a <DirectoryConfiguration> element to diagnostics.wadcfg. Set the container attribute value to the name of the Azure storage blob container you want WAD to use. WAD automatically creates the blob container if it does not exist. Set the directoryQuotaInMB attribute value to the same value used for the <LocalStorage> sizeInMB value in step 1.
Add a <LocalResource> element within <DirectoryConfiguration>. Set the name attribute to the same value used for the name attribute of the <LocalStorage> element in step 1. Set the relativePath attribute value, “.” means from the root of the local storage.
Warning: Not specifying the relativePath attribute or setting the value to an empty string causes WAD to ignore the entire <DirectoryConfiguration> element.
Here is a snippet from within ServiceDefinition.csdef:
<LocalResources> <LocalStorage name="CustomLogs" cleanOnRoleRecycle="false" sizeInMB="128" /> </LocalResources>
Here is the corresponding snippet from within diagnostics.wadcfg:
<DataSources> <DirectoryConfiguration container="wad-custom" directoryQuotaInMB="128"> <LocalResource name="CustomLogs" relativePath="." /> </DirectoryConfiguration> </DataSources>
WAD does not delete or remove custom files, it just persists them to blob storage, so you’ll need to implement a cleanup strategy. This is actually a good feature considering it may be inappropriate to delete the files.
[Kevin Williamson contacted me to let me know the above paragraph is inaccurate. Thanks Kevin. He says, "WAD will do garbage collection once a monitored directory reaches the directoryQuotaInMB value. In your example in the blog post you probably never saw the GC happen because both the directoryQuotaInMB and the sizeInMB of the LocalStorage resource were both set to 128 MB. In this scenario the folder will never grow above 128 MB so the WAD garbage collection will never kick in. You want to have the directoryQuotaInMB to be slightly smaller than the sizeInMB, and then WAD will clean up files once the directoryQuotaInMB size is hit."]
Regarding setting cleanOnRoleRecycle to false, I suspect there are role recycle scenarios during which WAD will not have had time to transfer the files. If the files are left on the disk then WAD will transfer them after the recycle. This is another reason for implementing your own cleanup strategy.
Finally, there is some difference of opinion as to WAD needing an exclusive lock on the files it copies. I believe some logging code uses file writing techniques which prevent WAD from performing the copy. Here are some links about the issue:
https://archive.msdn.microsoft.com/azurediag
https://blog.bareweb.eu/2011/01/implementing-azure-diagnostics-with-sdk-v1-3/
For more posts in my WAD series: