Initialize or Change Azure Diagnostics Configuration

Article
11/10/2015

Note

This article applies to Azure SDK 2.4 and below.

You collect diagnostic data by importing the Windows Azure Diagnostics module into the service model and then configuring data sources from which diagnostic data is collected. The Diagnostics monitor runs in Windows Azure and in the Microsoft Azure compute emulator to collect diagnostic data for a role instance. If the Diagnostics module has been imported into the service model for a role, the Diagnostics monitor automatically starts when a role instance starts. Data sources must be added to the configuration of the Diagnostics monitor to collect diagnostic data. If you don’t explicitly configure the Diagnostics monitor, the default configuration will be used when the role starts. Only some of the available data sources are added to the Diagnostics monitor by default, you must configure the collection of other data sources using the diagnostics.wadcfg file. Diagnostics data will be collected and stored on the role instance, but will not be persisted to storage unless you specify a storage account in the ServiceConfiguration.cscfg file. Once your application is deployed to Windows Azure, you can also remotely change the Diagnostics monitor configuration from an application running outside of Windows Azure. For detailed steps on enabling Diagnostics in your application, see How To Enable Diagnostics in a Cloud Service.

Import the Diagnostics module

To collect diagnostics data, you must import the Diagnostics module in the service model for each role from which you want to collect diagnostic data. The module is imported by adding an Import element to the ServiceDefinition.csdef file. The following example shows the Import element defined for a web role:

<?xml version="1.0" encoding="utf-8"?>
<ServiceDefinition name="MyHostedService" xmlns="https://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition" schemaVersion="2012-10.1.8">
  <WebRole name="WebRole1">
    <!--<Sites> ... </Sites> -->
    <!-- <Endpoints> ... </Endpoints> -->
    <Imports>
      <Import moduleName="Diagnostics" />
    </Imports>
  </WebRole>
</ServiceDefinition>

For more information about defining the service definition file and the service configuration file, see the Schema Reference. For more information about defining the service model for a hosted service, see Set Up a Hosted Service for Windows Azure.

Configure Storage of Your Diagnostics Data

Diagnostics data is not persisted to storage by default. To transfer diagnostic data to storage, you must define a connection string in the ServiceConfiguration.cscfg file. The following example shows how to define a connection string for transferring data to the Microsoft Azure storage emulator:

<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="MyHostedService" xmlns="https://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration" osFamily="1" osVersion="*">
  <Role name="WebRole1">
    <Instances count="1" />
    <ConfigurationSettings>
    <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="UseDevelopmentStorage=true" />
    </ConfigurationSettings>
  </Role>
</ServiceConfiguration>

If you want to use a storage account in Windows Azure, you must change the connection string to include an account name and account key:

<ConfigurationSettings>
   <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString" value="DefaultEndpointsProtocol=https;AccountName=<AccountName>;AccountKey=<AccountKey>"/>
</ConfigurationSettings>

The AccountName and AccountKey values are found in the Windows Azure Management Portal in the storage account dashboard, under Manage Access Keys. The protocol for the connection string must be https.

Diagnostics Data Sources

Only some of the available data sources are added to the diagnostic monitor by default, you must add others to collect specific types of diagnostic data. For information on the types of diagnostic data that you can configure your application to collect, see Azure Diagnostics Data Sources.

Initializing or Changing Diagnostics Monitor Configuration

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 Diagnostics monitor to collect diagnostic data. There are several mechanisms for configuring Diagnostics; using the diagnostics.wadcfg configuration file at deployment is the preferred mechanism for managing role wide configuration. For more information, see Azure Diagnostics Configuration Mechanisms and Order of Precedence in SDK 2.4 and earlier.

After you have deployed a cloud service you can also remotely change the configuration of the Diagnostics monitor in your application from another application running outside of Windows Azure.

Use the Diagnostics Configuration File

In version 1.2 You could configure the diagnostics monitor programmatically. This has been deprecated in version 1.3 and higher. In version 1.2, 1.3, and higher, 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 in the OnStart method:

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).

For web roles, the diagnostics.wadcfg configuration file is placed in the bin directory under the root directory of the role. For worker roles, the diagnostics.wadcfg configuration file is placed in 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. When your web or worker role is deployed the configuration information in the diagnostics.wadcfg file is written to the wad-control-container container in your storage account. For more information on using the Diagnostics configuration file, see Use the Azure Diagnostics Configuration File in Azure SDK 2.4 and earlier.

Programmatically configure Diagnostics using DiagnosticMonitor.Start()

The Start method with a DiagnosticMonitorConfiguration can be used to set Diagnostics configuration in the OnStart method of your role. This approach is effective for a new deployment, but ineffective for an update deployment and therefore is best avoided.

Programmatically configure Diagnostics using RoleInstanceDiagnosticManager.SetCurrentConfiguration()

After you have deployed a cloud service you can remotely change the configuration of the diagnostic monitor from code running in an application outside of Windows Azure using the DeploymentDiagnosticManager class. From this class, you can modify the diagnostic monitors for one or more role instances. You can also change the configuration of the diagnostic monitor for just one role instance using the RoleInstanceDiagnosticManager class. For more information, see Remotely Change the Azure Diagnostic Monitor Configuration in Azure SDK 2.4 and earlier.