Using the Windows Azure Diagnostics Configuration File

The configuration file is an XML document that conforms to the schema located at %ProgramFiles%\Windows Azure SDK\<VersionNumber>\schemas\DiagnosticsConfig201010.xsd, where <VersionNumber> is the version of the Windows Azure SDK that you are using.

For more information about the schema for this XML file, see Windows Azure Diagnostics Configuration Schema. The following example shows a typical diagnostics configuration file:

<DiagnosticMonitorConfiguration xmlns="http://schemas.microsoft.com/ServiceHosting/2010/10/DiagnosticsConfiguration"
      configurationChangePollInterval="PT1M"
      overallQuotaInMB="4096">
   <DiagnosticInfrastructureLogs bufferQuotaInMB="1024"
      scheduledTransferLogLevelFilter="Verbose"
      scheduledTransferPeriod="PT1M" />
   <Logs bufferQuotaInMB="1024"
      scheduledTransferLogLevelFilter="Verbose"
      scheduledTransferPeriod="PT1M" />
   <Directories bufferQuotaInMB="1024" 
      scheduledTransferPeriod="PT1M">
   
      <!-- These three elements specify the special directories 
           that are set up for the log types -->
      <CrashDumps container="wad-crash-dumps" directoryQuotaInMB="256" />
      <FailedRequestLogs container="wad-frq" directoryQuotaInMB="256" />
      <IISLogs container="wad-iis" directoryQuotaInMB="256" />
      
      <!-- For regular directories the DataSources element is used -->
      <DataSources>
         <DirectoryConfiguration container="wad-panther" directoryQuotaInMB="128">
            <!-- Absolute specifies an absolute path with optional environment expansion -->
            <Absolute expandEnvironment="true" path="%SystemRoot%\system32\sysprep\Panther" />
         </DirectoryConfiguration>
         <DirectoryConfiguration container="wad-custom" directoryQuotaInMB="128">
            <!-- LocalResource specifies a path relative to a local 
                 resource defined in the service definition -->
            <LocalResource name="MyLoggingLocalResource" relativePath="logs" />
         </DirectoryConfiguration>
      </DataSources>
   </Directories>
   <PerformanceCounters bufferQuotaInMB="512" scheduledTransferPeriod="PT1M">
      <!-- The counter specifier is in the same format as the imperative 
           diagnostics configuration API -->
      <PerformanceCounterConfiguration 
         counterSpecifier="\Processor(_Total)\% Processor Time" sampleRate="PT5S" />
   </PerformanceCounters>
   <WindowsEventLog bufferQuotaInMB="512"
      scheduledTransferLogLevelFilter="Verbose"
      scheduledTransferPeriod="PT1M">
      <!-- The event log name is in the same format as the imperative 
           diagnostics configuration API -->
      <DataSource name="System!*" />
   </WindowsEventLog>
</DiagnosticMonitorConfiguration>

Note
The CrashDumps, FailedRequestLogs, and IISLogs elements are not applicable to the VM role.

You can refer to the Diagnostics Configuration Schema for understanding the format of an element, and you can use the following information for a better understanding of how to use these elements:

• DiagnosticMonitorConfiguration – contains the definitions for the set of standard fixed data buffers for logging and diagnostic information. For more information, see DiagnosticMonitorConfiguration.
  
  
• DiagnosticInfrastructureLogs – contains the definitions for the size of the data buffer, and the level and frequency of data transfer for diagnostics infrastructure logs. For more information see, DiagnosticInfrastructureLogs.
  
  
• Logs – contains the definitions for the size of the data buffer, and the level and frequency of data transfer for the basic Windows Azure logs. For more information, see Logs.
  
  
• Directories – contains the definitions for the path, size of the data buffer, and the level and frequency of data transfer for the file-based logs that you define. This element contains definitions for both the special directories (CrashDumps, FailedRequestLogs, and IISLogs) and directories that you create (DataSources). For more information, see Directories.
  
  
• PerformanceCounters – contains the definitions for the counter configuration, size of the data buffer, and the level and frequency of data transfer for the performance counter data. For more information, see PerformanceCounters.
  
  

  Note
  If you are using a startup task to install a custom performance counter you cannot put the counter definition in the configuration file because the diagnostic monitor attempts to use the counter before you create it.

• WindowsEventLog – contains the definitions for the log, size of the data buffer, and the level and frequency of data transfer for the Windows event logs. For more information, see WindowsEventLog.
  
  

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 Components\<VersionNumber>\Diagnostics folder in the server image that you are uploading to the Windows Azure Management Portal. <VersionNumber> is the version of the Windows Azure SDK that you are using. A default file is located in this folder that you can modify or you can overwrite this file with one of your own.
  
  

If the configuration file exists in one of these locations when the Diagnostics module is imported, the diagnostics monitor configures settings using the configuration file instead of the default settings.

The diagnostics monitor uses the following precedence for configuration:

1. Configuration stored in blob storage. The Diagnostics module stores configuration information in blob storage, which is used to control Diagnostics configuration using the DeploymentDiagnosticManager.
   
   
   
   
2. Configuration specified through imperative code. The configuration is set by using a parameter with the Start method of the DiagnosticMonitor class.
   
   
3. Configuration specified declaratively. When a role imports the Diagnostics module by using the service definition, the Diagnostics module looks for a file named “diagnostics.wadcfg” in the root directory of the role.
   
   

   Note
   This configuration is saved to the control container so that it is visible by using the DeploymentDiagnosticManager, but a flag is set in the configuration that ensures that imperative code takes precedence.

4. Factory default configuration is used. This configuration can be retrieved by using the GetDefaultInitialConfiguration method of the DiagnosticMonitor class, and configures Diagnostics to collect infrastructure and trace logs locally, but does not set any scheduled transfers. In worker roles this configuration also includes crash dumps and in web roles it includes crash dumps, IIS logs, and failed request logs.