Diagnostics Configuration Mechanisms and Order of Precedence
Updated: August 18, 2014
Windows Azure Diagnostics can be configured using several different mechanisms: the configuration blob in storage, imperative code, declarative configuration, or the default configuration. The preferred mechanism to configure Diagnostics is to use a XML configuration file (diagnostics.wadcfg) in the application project. Using this approach, the diagnostics.wadcfg file completely defines the configuration and it can be updated and redeployed at will. Note that mixing the use of the diagnostics.wadcfg configuration file with programmatic mechanisms of setting configuration using the DiagnosticMonitor or RoleInstanceDiagnosticManager classes can lead to confusion (see below for more details). The following list describes the different configuration mechanisms and the precedence order for how the diagnostic monitor applies configuration information:
wad-control-container blob- A control configuration blob will be created for each role instance whenever a role without a blob starts. The wad-control-container blob has the highest precedence for controlling behavior and any changes to the blob will take effect the next time the instance polls for changes. The default polling interval is once per minute. The mechanisms described below are used to update the contents of the wad-control-container blob.
Imperative code: RoleInstanceDiagnosticManager.SetCurrentConfiguration()- The SetCurrentConfiguration method updates the wad-control-container blob directly and will result in a new configuration taking effect on the next polling interval. This is the preferred mechanism for setting configuration programmatically, either within the role OnStart method or from an external application. Note that the SetCurrentConfiguration method only changes configuration for a specific instance, but the DeploymentDiagnosticManager object can be used to get a RoleInstanceDiagnosticManager object for each instance. See Remotely Change the Diagnostic Monitor Configuration for more information.
Imperative code: DiagnosticMonitor.Start()- The use of the Start method with a DiagnosticMonitorConfiguration input parameter will override the default configuration but will NOT override or update a pre-existing wad-control–container blob. This approach is effective for a new deployment, but ineffective for an update deployment and therefore is best avoided. Note that the Diagnostics monitor is automatically started if the Diagnostics module was imported into your project, so typically no process is actually started when the Start method is called.
Declarative modeling using the diagnostics.wadcfg file- 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 worker role or the bin directory of the web role. If the configuration file exists in one of these locations when the Diagnostics module is imported, the Diagnostics monitor uses the diagnostics.wadcfg configuration file settings. See Use the Azure Diagnostics Configuration File for more information.
The diagnostics.wadcfg file and a deployment is the preferred mechanism for managing role wide configuration, but only if used exclusively. Updates to diagnostics.wadcfg take effect only if the wad-control-container blob has never been updated programmatically. Calls to Start or SetCurrentConfiguration are instance level configuration overrides which take precedence over diagnostics.wadcfg changes.
Default configuration- In applications built using SDK version 1.3 and later, the Diagnostics monitor will automatically start and run if the Diagnostics module was imported in your project. The default configuration will be used if none of the approaches listed above have been used to update the configuration. The default configuration can be retrieved by using the GetDefaultInitialConfiguration method. By default, Windows Azure logs, IIS logs, and Windows Azure Diagnostic infrastructure logs are collected locally but are not persisted to storage.