LoggingEventSource Class

Definition

Namespace:

Microsoft.Extensions.Logging.EventSource

Assembly:

Microsoft.Extensions.Logging.EventSource.dll

Package:

Microsoft.Extensions.Logging.EventSource v9.0.0-rc.2.24473.5

The LoggingEventSource is the bridge from all ILogger based logging to EventSource/EventListener logging.

You turn this logging on by enabling the EventSource called

 Microsoft-Extensions-Logging

When you enabled the EventSource, the EventLevel you set is translated in the obvious way to the level associated with the ILogger (thus Debug = verbose, Informational = Informational ... Critical == Critical)

This allows you to filter by event level in a straightforward way.

For finer control you can specify a EventSource Argument called

FilterSpecs

The FilterSpecs argument is a semicolon separated list of specifications. Where each specification is

SPEC = // empty spec, same as * | NAME // Just a name the level is the default level | NAME : LEVEL // specifies level for a particular logger (can have a * suffix).

When "UseAppFilters" is specified in the FilterSpecs, it avoids disabling all categories which happens by default otherwise.

Where Name is the name of a ILoggger (case matters), Name can have a * which acts as a wildcard AS A SUFFIX. Thus Net* will match any loggers that start with the 'Net'.

The LEVEL is a number or a LogLevel string. 0=Trace, 1=Debug, 2=Information, 3=Warning, 4=Error, Critical=5 This specifies the level for the associated pattern. If the number is not specified, (first form of the specification) it is the default level for the EventSource.

First match is used if a particular name matches more than one pattern.

In addition the level and FilterSpec argument, you can also set EventSource Keywords. See the Keywords definition below, but basically you get to decide if you wish to have

• Keywords.Message - You get the event with the data in parsed form.
• Keywords.JsonMessage - you get an event with the data in parse form but as a JSON blob (not broken up by argument ...)
• Keywords.FormattedMessage - you get an event with the data formatted as a string

It is expected that you will turn only one of these keywords on at a time, but you can turn them all on (and get the same data logged three different ways.

Example Usage

This example shows how to use an EventListener to get ILogging information

class MyEventListener : EventListener { protected override void OnEventSourceCreated(EventSource eventSource) { if (eventSource.Name == "Microsoft-Extensions-Logging") { // initialize a string, string dictionary of arguments to pass to the EventSource. // Turn on loggers matching App* to Information, everything else () is the default level (which is EventLevel.Error) var args = new Dictionary<string, string>() { { "FilterSpecs", "App:Information;*" } }; // Set the default level (verbosity) to Error, and only ask for the formatted messages in this case. EnableEvents(eventSource, EventLevel.Error, LoggingEventSource.Keywords.FormattedMessage, args); } } protected override void OnEventWritten(EventWrittenEventArgs eventData) { // Look for the formatted message event, which has the following argument layout (as defined in the LoggingEventSource. // FormattedMessage(LogLevel Level, int FactoryID, string LoggerName, string EventId, string FormattedMessage); if (eventData.EventName == "FormattedMessage") Console.WriteLine("Logger {0}: {1}", eventData.Payload[2], eventData.Payload[4]); } }

public ref class LoggingEventSource sealed : System::Diagnostics::Tracing::EventSource

[System.Diagnostics.Tracing.EventSource(Name="Microsoft-Extensions-Logging")]
public sealed class LoggingEventSource : System.Diagnostics.Tracing.EventSource

[<System.Diagnostics.Tracing.EventSource(Name="Microsoft-Extensions-Logging")>]
type LoggingEventSource = class
    inherit EventSource

Public NotInheritable Class LoggingEventSource
Inherits EventSource

Inheritance

Object

EventSource

LoggingEventSource

Attributes

EventSourceAttribute

Examples

The following example shows how to use an EventListener to get ILogging information:

class MyEventListener : EventListener 
{
    protected override void OnEventSourceCreated(EventSource eventSource) 
    {
        if (eventSource.Name == "Microsoft-Extensions-Logging") 
        {
            // initialize a string, string dictionary of arguments to pass to the EventSource.
            // Turn on loggers matching App* to Information, everything else (*) is the default level (which is EventLevel.Error)
            var args = new Dictionary<string, string>() { { "FilterSpecs", "App*:Information;*" } };
            // Set the default level (verbosity) to Error, and only ask for the formatted messages in this case.
            EnableEvents(eventSource, EventLevel.Error, LoggingEventSource.Keywords.FormattedMessage, args);
        }
    }

    protected override void OnEventWritten(EventWrittenEventArgs eventData) 
    {
        // Look for the formatted message event, which has the following argument layout (as defined in the LoggingEventSource.
        // FormattedMessage(LogLevel Level, int FactoryID, string LoggerName, string EventId, string FormattedMessage);
        if (eventData.EventName == "FormattedMessage")
            Console.WriteLine("Logger {0}: {1}", eventData.Payload[2], eventData.Payload[4]);
    }
}

Remarks

You turn this logging on by enabling the EventSource called Microsoft-Extensions-Logging.

When you enabled the EventSource, the EventLevel you set is translated in the obvious way to the level associated with the ILogger (thus Debug = verbose, Informational = Informational ... Critical == Critical)

This allows you to filter by event level in a straightforward way.

For finer control you can specify a EventSource Argument called FilterSpecs.

The FilterSpecs argument is a semicolon separated list of specifications. Where each specification is

SPEC =                          // empty spec, same as *
     | NAME                     // Just a name the level is the default level
     | NAME : LEVEL            // specifies level for a particular logger (can have a * suffix).

Where Name is the name of a ILogger (case matters), Name can have a * which acts as a wildcard AS A SUFFIX. Thus, Net* will match any loggers that start with the 'Net'.

The LEVEL is a number or a LogLevel string. 0=Trace, 1=Debug, 2=Information, 3=Warning, 4=Error, Critical=5 This specifies the level for the associated pattern. If the number is not specified, (first form of the specification) it is the default level for the EventSource.

First match is used if a particular name matches more than one pattern.

In addition to the level and FilterSpec argument, you can also set EventSource Keywords. See the Keywords definition below, but basically you get to decide if you wish to have

• Keywords.Message - You get the event with the data in parsed form.
• Keywords.JsonMessage - you get an event with the data in parse form but as a JSON blob (not broken up by argument ...)
• Keywords.FormattedMessage - you get an event with the data formatted as a string

It is expected that you will turn only one of these keywords on at a time, but you can turn them all on and get the same data logged three different ways.

Properties

ConstructionException	Gets any exception that was thrown during the construction of the event source. (Inherited from EventSource)
Guid	The unique identifier for the event source. (Inherited from EventSource)
Name	The friendly name of the class that is derived from the event source. (Inherited from EventSource)
Settings	Gets the settings applied to this event source. (Inherited from EventSource)

Methods

Dispose()	Releases all resources used by the current instance of the EventSource class. (Inherited from EventSource)
Dispose(Boolean)	Releases the unmanaged resources used by the EventSource class and optionally releases the managed resources. (Inherited from EventSource)
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetTrait(String)	Gets the trait value associated with the specified key. (Inherited from EventSource)
GetType()	Gets the Type of the current instance. (Inherited from Object)
IsEnabled()	Determines whether the current event source is enabled. (Inherited from EventSource)
IsEnabled(EventLevel, EventKeywords, EventChannel)	Determines whether the current event source is enabled for events with the specified level, keywords and channel. (Inherited from EventSource)
IsEnabled(EventLevel, EventKeywords)	Determines whether the current event source that has the specified level and keyword is enabled. (Inherited from EventSource)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
OnEventCommand(EventCommandEventArgs)	Called when the current event source is updated by the controller. (Inherited from EventSource)
ToString()	Obtains a string representation of the current event source instance. (Inherited from EventSource)
Write(String, EventSourceOptions)	Writes an event without fields, but with the specified name and options. (Inherited from EventSource)
Write(String)	Writes an event without fields, but with the specified name and default options. (Inherited from EventSource)
Write<T>(String, EventSourceOptions, Guid, Guid, T)	Writes an event with the specified name, options, related activity and event data. (Inherited from EventSource)
Write<T>(String, EventSourceOptions, T)	Writes an event with the specified name, event data and options. (Inherited from EventSource)
Write<T>(String, EventSourceOptions, T)	Writes an event with the specified name, options and event data. (Inherited from EventSource)
Write<T>(String, T)	Writes an event with the specified name and data. (Inherited from EventSource)
WriteEvent(Int32, Byte[])	Writes an event by using the provided event identifier and byte array argument. (Inherited from EventSource)
WriteEvent(Int32, EventSource+EventSourcePrimitive[])	Writes an event by using the provided event identifier and a variable number of event source primitives. (Inherited from EventSource)
WriteEvent(Int32, Int32, Int32, Int32)	Writes an event by using the provided event identifier and 32-bit integer arguments. (Inherited from EventSource)
WriteEvent(Int32, Int32, Int32)	Writes an event by using the provided event identifier and 32-bit integer arguments. (Inherited from EventSource)
WriteEvent(Int32, Int32, String)	Writes an event by using the provided event identifier and 32-bit integer and string arguments. (Inherited from EventSource)
WriteEvent(Int32, Int32)	Writes an event by using the provided event identifier and 32-bit integer argument. (Inherited from EventSource)
WriteEvent(Int32, Int64, Byte[])	Writes the event data using the specified identifier and 64-bit integer and byte array arguments. (Inherited from EventSource)
WriteEvent(Int32, Int64, Int64, Int64)	Writes an event by using the provided event identifier and 64-bit arguments. (Inherited from EventSource)
WriteEvent(Int32, Int64, Int64)	Writes an event by using the provided event identifier and 64-bit arguments. (Inherited from EventSource)
WriteEvent(Int32, Int64, String)	Writes an event by using the provided event identifier and 64-bit integer, and string arguments. (Inherited from EventSource)
WriteEvent(Int32, Int64)	Writes an event by using the provided event identifier and 64-bit integer argument. (Inherited from EventSource)
WriteEvent(Int32, Object[])	Writes an event by using the provided event identifier and array of arguments. (Inherited from EventSource)
WriteEvent(Int32, String, Int32, Int32)	Writes an event by using the provided event identifier and arguments. (Inherited from EventSource)
WriteEvent(Int32, String, Int32)	Writes an event by using the provided event identifier and arguments. (Inherited from EventSource)
WriteEvent(Int32, String, Int64)	Writes an event by using the provided event identifier and arguments. (Inherited from EventSource)
WriteEvent(Int32, String, String, String)	Writes an event by using the provided event identifier and string arguments. (Inherited from EventSource)
WriteEvent(Int32, String, String)	Writes an event by using the provided event identifier and string arguments. (Inherited from EventSource)
WriteEvent(Int32, String)	Writes an event by using the provided event identifier and string argument. (Inherited from EventSource)
WriteEvent(Int32)	Writes an event by using the provided event identifier. (Inherited from EventSource)
WriteEventCore(Int32, Int32, EventSource+EventData*)	Creates a new WriteEvent overload by using the provided event identifier and event data. (Inherited from EventSource)
WriteEventWithRelatedActivityId(Int32, Guid, Object[])	Writes an event that indicates that the current activity is related to another activity. (Inherited from EventSource)
WriteEventWithRelatedActivityIdCore(Int32, Guid*, Int32, EventSource+EventData*)	Writes an event that indicates that the current activity is related to another activity. (Inherited from EventSource)

Events

EventCommandExecuted

Occurs when a command comes from an event listener. (Inherited from EventSource)