Common.Logging.ETWLogger

Common.Logging.ETWLogger

Common.Logging.ETWLogger provides an adapter for connecting Common.Logging to the Event-Tracing for Windows logging subsystem that is available on later editions of the Windows Operating System (both Servers and Clients). See MSDN for more information on Event-Tracing for Windows.

Quick-Start

• Add the Common.Logging.ETWLogger NuGet package to your project.
• To configure the logger in code, simply create an instance of the Common.Logging.ETW.ETWLoggerAdapter and call the .GetLogger(...) method on the adapter as follows:

var adapter = new ETWLoggerAdapter();
var logger = adapter.GetLogger(typeof(MyClass));

logger.Warn("Message to Log here!"); 

• To Configure the logger via e.g., App.config, web.config files, add the relevant sections to your .config file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>
    <sectionGroup name="common">
      <section name="logging" type="Common.Logging.ConfigurationSectionHandler, Common.Logging" />
    </sectionGroup>
  </configSections>

  <common>
    <logging>
      <factoryAdapter type="Common.Logging.ETW.ETWLoggerFactoryAdapter, Common.Logging.ETWLogger">
      </factoryAdapter>
    </logging>
  </common>

</configuration>

Advanced Configuration

Common.Logging.ETWLogger offers several configuration options to control its behavior as follows:

Custom EventSource Sub-Class

Common.Logging.ETWLogger makes use of the Microsoft.Diagnostics.Tracing.EventSource NuGet package to expose an API for managed (.NET) code to communicate with the underlying native Event-Tracing for Windows (ETW) subsystem. Among other things, this library provides an EventSource super-class from which developers must derive their own sub-class to communicate with ETW. Common.Logging.ETWLogger provides a default sub-class derived from this EventSource super-class and it is intended to meet the needs of most adopters of Common.Logging.ETWLogger.

For more fine-grained control over the behavior of Common.Logging.ETWLogger, developers can derive their own sub-class from the EventSource super-class and configure Common.Logging.ETWLogger to use your own custom type instead.

The Common.Logging.ETW.ETWLoggerAdapter exposes a property that can configured to contain an instance of your custom EventSource-derived sub-class in code as follows:

var adapter = new ETWLoggerAdapter();
adapter.ETWEventSource = new MyCustomDerivedEventSource();

var logger = adapter.GetLogger(typeof(MyClass));
logger.Warn("Message to Log here!"); 

This can be configured in e.g., app.config, web.config files as follows:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>
    <sectionGroup name="common">
      <section name="logging" type="Common.Logging.ConfigurationSectionHandler, Common.Logging" />
    </sectionGroup>
  </configSections>

  <common>
    <logging>
      <factoryAdapter type="Common.Logging.ETW.ETWLoggerFactoryAdapter, Common.Logging.ETWLogger">
      	<arg key='commonLoggingEventSourceType' value='MyNamespace.MyCustomDerivedEventSource,MyAssemblyContainingTheCustomEventSource'/>
	  </factoryAdapter>
    </logging>
  </common>

</configuration>

Requirements for custom EventSource Sub-Classes

In order for Common.Logging.ETWLogger to properly interact with your custom EventSource-derived sub-class, the following requirements must be satisfied:

1. Your custom sub-class must derive from Microsoft.Diagnostics.Tracing.EventSource. Note: the Microsoft.Diagnostics.Tracing.EventSource package also places a number of other restrictions on types derived from EventSource and of course your own sub-class must satisfy all of these as well.
2. Your custom sub-class must implement the Common.Logging.ETW.ICommonLoggingEventSource interface. This is a Common.Logging-specific interface that Common.Logging.ETWLogger expects any custom EventSource-derived type to fully-implement. For more detail, see the full interface definition and refer to the default implementation of this interface provided with Common.Logging.ETWLogger as an example of this.

Minimum Log Level

Known Limitations