Microsoft.Extensions.Logging.EventSource
A logger that writes messages to EventSource instance.
On Windows platforms EventSource will deliver messages using Event Tracing for Windows (ETW) events.
On Linux EventSource will use LTTng (http://lttng.org) to deliver messages.
ActivityScope is just a IDisposable that knows how to send the ActivityStop event when it is
desposed. It is part of the BeginScope() support.
'serializes' a given exception into an ExceptionInfo (that EventSource knows how to serialize)
The exception to get information for.
ExceptionInfo object represending a .NET Exception
ETW does not support a concept of a null value. So we use an un-initialized object if there is no exception in the event data.
Converts an ILogger state object into a set of key-value pairs (That can be send to a EventSource)
The provider for the .
Creates an instance of .
The logging event source.
Represents information about exceptions that is captured by EventSourceLogger
Bridges 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]);
}
}
This is public from an EventSource consumer point of view, but since these definitions
are not needed outside this class
Meta events are events about the LoggingEventSource itself (that is they did not come from ILogger
Turns on the 'Message' event when ILogger.Log() is called. It gives the information in a programmatic (not formatted) way
Turns on the 'FormatMessage' event when ILogger.Log() is called. It gives the formatted string version of the information.
Turns on the 'MessageJson' event when ILogger.Log() is called. It gives JSON representation of the Arguments.
The one and only instance of the LoggingEventSource.
FormattedMessage() is called when ILogger.Log() is called. and the FormattedMessage keyword is active
This only gives you the human readable formatted message.
Message() is called when ILogger.Log() is called. and the Message keyword is active
This gives you the logged information in a programmatic format (arguments are key-value pairs)
ActivityStart is called when ILogger.BeginScope() is called
Set the filtering specification. null means turn off all loggers. Empty string is turn on all providers.
The filter specification to set.
Given a set of specifications Pat1:Level1;Pat1;Level2 ... Where
Pat is a string pattern (a logger Name with a optional trailing wildcard * char)
and Level is a number 0 (Trace) through 5 (Critical).
The :Level can be omitted (thus Pat1;Pat2 ...) in which case the level is 1 (Debug).
A completely empty string act like * (all loggers set to Debug level).
The first specification that 'loggers' Name matches is used.
Parses the level specification (which should look like :N where n is a number 0 (Trace)
through 5 (Critical). It can also be an empty string (which means 1 (Debug) and ';' marks
the end of the specification. This specification should start at spec[curPos]
It returns the value in 'ret' and returns true if successful. If false is returned ret is left unchanged.
Extension methods for the class.
Adds a logger that writes messages to the instance.
The extension method argument.
The so that additional calls can be chained.
Adds a logger that writes messages to the instance.
The extension method argument.
The so that additional calls can be chained.
Scope provider that does nothing.
Returns a cached instance of .
An empty scope without any logic
Throws an if is null.
The reference type argument to validate as non-null.
The name of the parameter with which corresponds.
Throws either an or an
if the specified string is or whitespace respectively.
String to be checked for or whitespace.
The name of the parameter being checked.
The original value of .
Attribute used to indicate a source generator should create a function for marshalling
arguments instead of relying on the runtime to generate an equivalent marshalling function at run-time.
This attribute is meaningless if the source generator associated with it is not enabled.
The current built-in source generator only supports C# and only supplies an implementation when
applied to static, partial, non-generic methods.
Initializes a new instance of the .
Name of the library containing the import.
Gets the name of the library containing the import.
Gets or sets the name of the entry point to be called.
Gets or sets how to marshal string arguments to the method.
If this field is set to a value other than ,
must not be specified.
Gets or sets the used to control how string arguments to the method are marshalled.
If this field is specified, must not be specified
or must be set to .
Gets or sets whether the callee sets an error (SetLastError on Windows or errno
on other platforms) before returning from the attributed method.
Specifies how strings should be marshalled for generated p/invokes
Indicates the user is supplying a specific marshaller in .
Use the platform-provided UTF-8 marshaller.
Use the platform-provided UTF-16 marshaller.
States a dependency that one member has on another.
This can be used to inform tooling of a dependency that is otherwise not evident purely from
metadata and IL, for example a member relied on via reflection.
Initializes a new instance of the class
with the specified signature of a member on the same type as the consumer.
The signature of the member depended on.
Initializes a new instance of the class
with the specified signature of a member on a .
The signature of the member depended on.
The containing .
Initializes a new instance of the class
with the specified signature of a member on a type in an assembly.
The signature of the member depended on.
The full name of the type containing the specified member.
The assembly name of the type containing the specified member.
Initializes a new instance of the class
with the specified types of members on a .
The types of members depended on.
The containing the specified members.
Initializes a new instance of the class
with the specified types of members on a type in an assembly.
The types of members depended on.
The full name of the type containing the specified members.
The assembly name of the type containing the specified members.
Gets the signature of the member depended on.
Either must be a valid string or
must not equal , but not both.
Gets the which specifies the type
of members depended on.
Either must be a valid string or
must not equal , but not both.
Gets the containing the specified member.
If neither nor are specified,
the type of the consumer is assumed.
Gets the full name of the type containing the specified member.
If neither nor are specified,
the type of the consumer is assumed.
Gets the assembly name of the specified type.
is only valid when is specified.
Gets or sets the condition in which the dependency is applicable, e.g. "DEBUG".
Specifies the types of members that are dynamically accessed.
This enumeration has a attribute that allows a
bitwise combination of its member values.
Specifies no members.
Specifies the default, parameterless public constructor.
Specifies all public constructors.
Specifies all non-public constructors.
Specifies all public methods.
Specifies all non-public methods.
Specifies all public fields.
Specifies all non-public fields.
Specifies all public nested types.
Specifies all non-public nested types.
Specifies all public properties.
Specifies all non-public properties.
Specifies all public events.
Specifies all non-public events.
Specifies all interfaces implemented by the type.
Specifies all members.
Suppresses reporting of a specific rule violation, allowing multiple suppressions on a
single code artifact.
is different than
in that it doesn't have a
. So it is always preserved in the compiled assembly.
Initializes a new instance of the
class, specifying the category of the tool and the identifier for an analysis rule.
The category for the attribute.
The identifier of the analysis rule the attribute applies to.
Gets the category identifying the classification of the attribute.
The property describes the tool or tool analysis category
for which a message suppression attribute applies.
Gets the identifier of the analysis tool rule to be suppressed.
Concatenated together, the and
properties form a unique check identifier.
Gets or sets the scope of the code that is relevant for the attribute.
The Scope property is an optional argument that specifies the metadata scope for which
the attribute is relevant.
Gets or sets a fully qualified path that represents the target of the attribute.
The property is an optional argument identifying the analysis target
of the attribute. An example value is "System.IO.Stream.ctor():System.Void".
Because it is fully qualified, it can be long, particularly for targets such as parameters.
The analysis tool user interface should be capable of automatically formatting the parameter.
Gets or sets an optional argument expanding on exclusion criteria.
The property is an optional argument that specifies additional
exclusion where the literal metadata target is not sufficiently precise. For example,
the cannot be applied within a method,
and it may be desirable to suppress a violation against a statement in the method that will
give a rule violation, but not against all statements in the method.
Gets or sets the justification for suppressing the code analysis message.
Specifies that null is allowed as an input even if the corresponding type disallows it.
Specifies that null is disallowed as an input even if the corresponding type allows it.
Specifies that an output may be null even if the corresponding type disallows it.
Specifies that an output will not be null even if the corresponding type allows it. Specifies that an input argument was not null when the call returns.
Specifies that when a method returns , the parameter may be null even if the corresponding type disallows it.
Initializes the attribute with the specified return value condition.
The return value condition. If the method returns this value, the associated parameter may be null.
Gets the return value condition.
Specifies that when a method returns , the parameter will not be null even if the corresponding type allows it.
Initializes the attribute with the specified return value condition.
The return value condition. If the method returns this value, the associated parameter will not be null.
Gets the return value condition.
Specifies that the output will be non-null if the named parameter is non-null.
Initializes the attribute with the associated parameter name.
The associated parameter name. The output will be non-null if the argument to the parameter specified is non-null.
Gets the associated parameter name.
Applied to a method that will never return under any circumstance.
Specifies that the method will not return if the associated Boolean parameter is passed the specified value.
Initializes the attribute with the specified parameter value.
The condition parameter value. Code after the method will be considered unreachable by diagnostics if the argument to
the associated parameter matches this value.
Gets the condition parameter value.
Specifies that the method or property will ensure that the listed field and property members have not-null values.
Initializes the attribute with a field or property member.
The field or property member that is promised to be not-null.
Initializes the attribute with the list of field and property members.
The list of field and property members that are promised to be not-null.
Gets field or property member names.
Specifies that the method or property will ensure that the listed field and property members have not-null values when returning with the specified return value condition.
Initializes the attribute with the specified return value condition and a field or property member.
The return value condition. If the method returns this value, the associated field or property member will not be null.
The field or property member that is promised to be not-null.
Initializes the attribute with the specified return value condition and list of field and property members.
The return value condition. If the method returns this value, the associated field and property members will not be null.
The list of field and property members that are promised to be not-null.
Gets the return value condition.
Gets field or property member names.