Use the Azure Diagnostics Configuration File in Azure SDK 2.4 and earlier

Article
11/10/2015

Note

Warning

This article only applies to diagnostics in the Azure SDK 2.4 and earlier.

You collect diagnostic data by importing the Diagnostics module into the service model and then configuring data sources from which diagnostic data is collected. Data sources must be added to the configuration of the diagnostic monitor to collect diagnostic data. You can configure the diagnostics monitor programmatically, however the Windows Azure SDK gives you the ability to configure Diagnostics using an XML configuration file (diagnostics.wadcfg) instead. This method has many advantages over writing code:

Diagnostics starts before the OnStart method is run so that errors in startup tasks can be caught and logged
Any changes made to the configuration at run time will remain after a restart.
Diagnostics configuration changes do not require the code to be rebuilt.
You can automatically start the diagnostics monitor with a specific configuration without needing additional code (which might cause an exception that would prevent your role from starting).

The default diagnostics behavior is to collect infrastructure and trace logs and not transfer data to storage. If you want to collect data in addition to the default data, you must configure the diagnostics monitor to do so.

This topic discusses creating the diagnostics.wadcfg XML configuration file. For more information on the overall process of configuring diagnostics data sources in your application, persisting diagnostics data to storage, and viewing that data in storage, see Enabling Diagnostics in Windows Azure.

Create the diagnostics configuration file

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.

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.wadcfg configuration file is an XML document that conforms to the schema located at %ProgramFiles%\Microsoft SDKs\Windows Azure\<SDK>\<VersionNumber>\schemas\DiagnosticsConfig201010.xsd, where <SDK> is the developer SDK you are using and <VersionNumber> is the version. For more information about the schema for this XML file, see Azure Diagnostics 1.0 Configuration Schema.

The following example shows an example diagnostics.wadcfg configuration file. This configuration file collects all types of diagnostics information, be sure to remove the data sources you do not want to collect in your application.

<?xml version="1.0" encoding="utf-8" ?>
<DiagnosticMonitorConfiguration xmlns="https://schemas.microsoft.com/ServiceHosting/2010/10/DiagnosticsConfiguration"
      configurationChangePollInterval="PT1M"
      overallQuotaInMB="4096">

  <DiagnosticInfrastructureLogs bufferQuotaInMB="0"
     scheduledTransferLogLevelFilter="Verbose"
     scheduledTransferPeriod="PT30M" />

  <Logs bufferQuotaInMB="0"
     scheduledTransferLogLevelFilter="Verbose"
     scheduledTransferPeriod="PT30M" />

  <Directories bufferQuotaInMB="0"
     scheduledTransferPeriod="PT30M">  
    <!-- FailedRequestLogs and IISLogs are only relevant to Web roles -->
    <CrashDumps container="wad-crash-dumps" directoryQuotaInMB="0" />
    <FailedRequestLogs container="wad-frq" directoryQuotaInMB="0" />
    <IISLogs container="wad-iis" directoryQuotaInMB="0" />
    <DataSources>
      <DirectoryConfiguration container="diagnostics-custom-logs" directoryQuotaInMB="1024">
        <LocalResource name="MyCustomLogs" relativePath="."/>
      </DirectoryConfiguration>     
    </DataSources>
  </Directories>

  <PerformanceCounters bufferQuotaInMB="0" scheduledTransferPeriod="PT30M">
    <PerformanceCounterConfiguration counterSpecifier="\Memory\Available Bytes" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\Processor(_Total)\% Processor Time" sampleRate="PT30S" />
    <!-- These three elements are only relevant to Web roles -->
    <PerformanceCounterConfiguration counterSpecifier="\Process(w3wp)\% Processor Time" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\Process(w3wp)\Private Bytes" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\Process(w3wp)\Thread Count" sampleRate="PT30S" />
    <!-- These three elements are only relevant to Worker roles -->
    <!-- <PerformanceCounterConfiguration counterSpecifier="\Process(WaWorkerHost)\% Processor Time" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\Process(WaWorkerHost)\Private Bytes" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\Process(WaWorkerHost)\Thread Count" sampleRate="PT30S" /> -->
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR Interop(_Global_)\# of marshalling" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR Loading(_Global_)\% Time Loading" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR LocksAndThreads(_Global_)\Contention Rate / sec" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR Memory(_Global_)\# Bytes in all Heaps" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR Networking(_Global_)\Connections Established" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR Remoting(_Global_)\Remote Calls/sec" sampleRate="PT30S" />
    <PerformanceCounterConfiguration counterSpecifier="\.NET CLR Jit(_Global_)\% Time in Jit" sampleRate="PT30S" />
  </PerformanceCounters>

  <WindowsEventLog bufferQuotaInMB="0"
     scheduledTransferLogLevelFilter="Verbose"
     scheduledTransferPeriod="PT30M">
    <DataSource name="Application!*" />
    <DataSource name="System!*" />
  </WindowsEventLog>

</DiagnosticMonitorConfiguration>

For information on the XML elements used above, see Azure Diagnostics 1.2 Configuration Schema.

Use the Azure Diagnostics Configuration File in Azure SDK 2.4 and earlier

Create the diagnostics configuration file

Additional resources