This post is compatible with Windows Azure SDK v1.3 and v1.4

Earlier in the week, the Windows Azure team posted about a way to use a configuration file to set up the runtime diagnostics in the Windows Azure SDK version 1.3. This is an alternative to the imperative programmatic approach and has the key benefit of executing the setup before the role itself starts and before any Startup tasks execute. In this blog I will show how to use the diagnostics.wadcfg diagnostics configuration file, how to use intellisense with it and how it can be used to capture early Windows Azure lifecycle events. A Source code example is also provided.

First of all we need to start with a vanilla Windows Azure Worker Role. I chose this for simplicity, but the approach does work for other role types. For adjustments you need to make for different role types, see the later section called Differences between role types.

To this root of this Worker Role, we must add a file called diagnostics.wadcfg. You can choose to add it as a text file or an xml file; the latter will allow basic validation checking such as ensuring tags are closed. We will choose the Xml file approach, as it also allows us to setup intellisense for a richer design-time experience. Right click on your solution and

Add a new file to the solution

Next choose the XML file option given to use and give it the correct filename.

Add an xml file with the correct filename

The new file should be set to have the correct build properties set in order that the file is packaged correctly.

Set the Build Action to Content and Copy to Output to a "Copy **" option

The basic XML file generated by Visual Studio is show below. You can delete all the contents of this file:

Basic xml to be deleted

If you try to type in to the newly created file you will see that you are not given any particularly useful options by IntelliSense. This next step is optional, and so skip the next section if you are just going to paste in an existing file. I will now show how to validate any XML file against a known XSD schema in Visual Studio 2010.

How to Validate an XML file against a know XSD schema in Visual Studio 2010

Firstly, enter the XML | Schemas … dialog:

Enter the XML Schemas option

This is what the dialog looks like:

XML Schemas dialog

XML Schemas dialog

Click the Add button, and in the resulting dialog browse to the path of your XSD. Select the XSD and click OK. The path to the Windows Azure Diagnostic Configuration file XSD is located at %ProgramFiles%Windows Azure SDK[version]schemasDiagnosticsConfig201010.xsd. MSDN has a more detailed document on the schema for this XML file located at Windows Azure Diagnostics Configuration Schema.

Browse and select the XSD

Browse and select the XSD

Visual Studio will then show the schema that you have added as the highlighted row in the next dialog box. This will also by default have a tick in the “Use” column, meaning it has been loaded and is associated with the current document. In future, this all xml files will automatically associated with the correct schema if there is a matching xmlns in the XML file.

Confirmation of schema loaded

Confirmation of schema loaded

Clicking OK on this final dialog completes the process. This allows IntelliSense to begin providing suggestions for new nodes as well as validating existing nodes:

IntelliSense!

IntelliSense!

XML value and how to test

Now we can start adding in a basic set of XML nodes that will allow us to trace Windows Event Log details. The basic code is shown below. The schema is very familiar should you be experienced with Windows Azure Diagnostics. If not, I suggest you may like to read this blog post about how those diagnostics work. The only slight complexity is that scheduledTransferPeriod is in an encoded form, using ISO-8601 to encode a TimeSpan of 1 minute as “PT1M”.

<DiagnosticMonitorConfiguration xmlns="http://schemas.microsoft.com/ServiceHosting/2010/10/DiagnosticsConfiguration"
configurationChangePollInterval="PT1M"
overallQuotaInMB="4096">
<WindowsEventLog bufferQuotaInMB="4096" scheduledTransferLogLevelFilter="Verbose" scheduledTransferPeriod="PT1M">
    <DataSource name="Application!*"/>
  </WindowsEventLog>
</DiagnosticMonitorConfiguration>

You can see how IntelliSense is really useful in this scenario by this screenshot:

IntelliSense again!

IntelliSense again!

Once you have this value in your wadcfg file, you will have a role that will copy any Windows event logs for Application that occur – this happens very early in the lifecycle, and we can prove this by adding in a very simple console application that writes to the Windows Application log.

The console application I will not go into details regarding how to create and link it to the worker role – it is included in the source code provided and if you want to know more details they’re included in my blog post about Custom Performance Counters in Windows Azure, which uses a similar console application to install the counters.

The code within the console application is very straight forward:

using System;
using System.Diagnostics;

namespace EventLogWriter
{
     class Program
     {
          static void Main(string[] args)
          {
               string eventSourceName = "EventLogWriter";

               if (!EventLog.SourceExists(eventSourceName))
                    EventLog.CreateEventSource(eventSourceName, "Application");

               EventLog.WriteEntry(eventSourceName, args[0], EventLogEntryType.Warning);
          }
     }
}

The program just adds whatever is provided as the first argument to it into the Application Event Log. The solution will look like this:

Solution structure

Solution structure

You must make sure you add the Startup task to your ServiceDefinition.csdef file:

ServiceDefinition.csdef

ServiceDefinition.csdef

Differences Between Role Types

The different role types in Windows Azure need a slightly different setup in order to use this approach. The differences are simply related to File Location of the diagnostics.wadcfg file. From the new msdn documentation:

The following list identifies the locations of the diagnostics configuration file for the different role types:

  • For worker roles, the configuration file is located in the root directory of the role.
  • For web roles, the configuration file is located in the bin directory under the root directory of the role.
  • For VM roles, the configuration file must be located in the %ProgramFiles%Windows Azure Integration Componentsv1.0Diagnostics folder in the server image that you are uploading to the Windows Azure Management Portal. A default file is located in this folder that you can modify or you can overwrite this file with one of your own.

Conclusion

This screen show the logs being created in the Windows Event Log:

Event Log

Event Log

This is the associated row in Windows Azure Blob Storage, as copied by the Windows Azure Diagnostics library:

Result in BlobStorage

Result in BlobStorage

Potential Problems

When I was creating this blog, I ran into a problem:

If you get this error, make sure you have all the required attributes on each node!

If you get this error, make sure you have all the required attributes on each node!

The message is “Windows Azure Diagnostics Agent has stopped working”. This was my fault, as I had hand crafted the XML file and had missed some important attributes on the <DiagnosticMonitorConfiguration/> root node.  Make sure you have the configurationChangePollInterval and overallQuotaInMB specified, otherwise you will get this problem.

<DiagnosticMonitorConfiguration xmlns="http://schemas.microsoft.com/ServiceHosting/2010/10/DiagnosticsConfiguration"
configurationChangePollInterval="PT1M"
overallQuotaInMB="4096">

Source code

As promised, the source code can be downloaded here: FileBasedDiagnosticsConfig

About these ads