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:

  1. 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.
  2. 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.
  3. 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:

<LocalStorage name="CustomLogs" cleanOnRoleRecycle="false" sizeInMB="128" />

Here is the corresponding snippet from within diagnostics.wadcfg:

<DirectoryConfiguration container="wad-custom" directoryQuotaInMB="128">
<LocalResource name="CustomLogs" relativePath="." />

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:

For more posts in my WAD series:

Comments (3)
  1. Dee says:

    What happens when the directoryQuotaInMB is exceeded – roles will be unable to write to that directory?

  2. david.hardin says:

    Your best bet is to test what happens but I believe the configured sizeInMB of the LocalStorage element sets a hard limit on how much Azure will allow you to store.  The directoryQuotaInMB along with other WAD quotas are soft limits which WAD can exceed temporarily due to its own processing.

    With the settings I show above you'd only be able to write 128 MB before needing to clean the folder mainly due to the sizeInMB value.

    Take a look at the second half of this blog for additional info:…/configuring-wad-via-the-diagnostics-wadcfg-config-file.aspx

  3. Hu Ha says:

    The above description works fine for me. – BUT –

    When I change the settings in Visual Studio 2013 with the Windwos Azure Tool V2.2.11003.1601 it changes the line

           <LocalResource name="CustomTrace" relativePath="."/>


           <Absolute path="[CustomTrace]." expandEnvironment="false" />

    How to reproduce: Go to the properties of the web/worker role. From the "Configuration" tab under "Diagnostics" edit the "Custom plan". Just clicking OK will do.

    When deploying with this change, the custom log files will no longer be transferred to the storage account. I have to manually undo the changes in that line in order to make things work again!

    This issue only occurs when you run it in the Compute Emulator or create a new VM during deploying. Deploying over an already running VM will not take over these changes and you can´t see the effect because the settings are already stored in table storage and the new settings will be ignored.

Comments are closed.

Skip to main content