Table of Contents

Class LoggingEvent

Namespace
log4net.Core
Assembly
log4net.dll

The internal representation of logging events.

public class LoggingEvent : ISerializable
Inheritance
LoggingEvent
Implements
Inherited Members

Remarks

When an affirmative decision is made to log then a LoggingEvent instance is created. This instance is passed around to the different log4net components.

This class is of concern to those wishing to extend log4net.

Some of the values in instances of LoggingEvent are considered volatile, that is the values are correct at the time the event is delivered to appenders, but will not be consistent at any time afterwards. If an event is to be stored and then processed at a later time these volatile values must be fixed by calling FixVolatileData(). There is a performance penalty for incurred by calling FixVolatileData() but it is essential to maintaining data consistency.

Constructors

LoggingEvent(SerializationInfo, StreamingContext)

Serialization constructor

protected LoggingEvent(SerializationInfo info, StreamingContext context)

Parameters

info SerializationInfo

The SerializationInfo that holds the serialized object data.

context StreamingContext

The StreamingContext that contains contextual information about the source or destination.

Remarks

Initializes a new instance of the LoggingEvent class with serialized data.

LoggingEvent(Type, ILoggerRepository, string, Level, object, Exception)

Initializes a new instance of the LoggingEvent class from the supplied parameters.

public LoggingEvent(Type callerStackBoundaryDeclaringType, ILoggerRepository repository, string loggerName, Level level, object message, Exception exception)

Parameters

callerStackBoundaryDeclaringType Type

The declaring type of the method that is the stack boundary into the logging system for this call.

repository ILoggerRepository

The repository this event is logged in.

loggerName string

The name of the logger of this event.

level Level

The level of this event.

message object

The message of this event.

exception Exception

The exception for this event.

Remarks

Except TimeStamp, Level and LoggerName, all fields of LoggingEvent are filled when actually needed. Call FixVolatileData() to cache all data locally to prevent inconsistencies.

This method is called by the log4net framework to create a logging event.

LoggingEvent(Type, ILoggerRepository, LoggingEventData)

Initializes a new instance of the LoggingEvent class using specific data.

public LoggingEvent(Type callerStackBoundaryDeclaringType, ILoggerRepository repository, LoggingEventData data)

Parameters

callerStackBoundaryDeclaringType Type

The declaring type of the method that is the stack boundary into the logging system for this call.

repository ILoggerRepository

The repository this event is logged in.

data LoggingEventData

Data used to initialize the logging event.

Remarks

This constructor is provided to allow a LoggingEvent to be created independently of the log4net framework. This can be useful if you require a custom serialization scheme.

Use the GetLoggingEventData(FixFlags) method to obtain an instance of the LoggingEventData class.

This constructor sets this objects Fix flags to All, this assumes that all the data relating to this event is passed in via the data parameter and no other data should be captured from the environment.

LoggingEvent(Type, ILoggerRepository, LoggingEventData, FixFlags)

Initializes a new instance of the LoggingEvent class using specific data.

public LoggingEvent(Type callerStackBoundaryDeclaringType, ILoggerRepository repository, LoggingEventData data, FixFlags fixedData)

Parameters

callerStackBoundaryDeclaringType Type

The declaring type of the method that is the stack boundary into the logging system for this call.

repository ILoggerRepository

The repository this event is logged in.

data LoggingEventData

Data used to initialize the logging event.

fixedData FixFlags

The fields in the struct that have already been fixed.

Remarks

This constructor is provided to allow a LoggingEvent to be created independently of the log4net framework. This can be useful if you require a custom serialization scheme.

Use the GetLoggingEventData(FixFlags) method to obtain an instance of the LoggingEventData class.

The fixedData parameter should be used to specify which fields in the data struct have been preset. Fields not specified in the fixedData will be captured from the environment if requested or fixed.

LoggingEvent(LoggingEventData)

Initializes a new instance of the LoggingEvent class using specific data.

public LoggingEvent(LoggingEventData data)

Parameters

data LoggingEventData

Data used to initialize the logging event.

Remarks

This constructor is provided to allow a LoggingEvent to be created independently of the log4net framework. This can be useful if you require a custom serialization scheme.

Use the GetLoggingEventData(FixFlags) method to obtain an instance of the LoggingEventData class.

This constructor sets this objects Fix flags to All, this assumes that all the data relating to this event is passed in via the data parameter and no other data should be captured from the environment.

Fields

HostNameProperty

The key into the Properties map for the host name value.

public const string HostNameProperty = "log4net:HostName"

Field Value

string

IdentityProperty

The key into the Properties map for the thread identity value.

public const string IdentityProperty = "log4net:Identity"

Field Value

string

UserNameProperty

The key into the Properties map for the user name value.

public const string UserNameProperty = "log4net:UserName"

Field Value

string

Properties

Domain

Gets the AppDomain friendly name.

public string Domain { get; }

Property Value

string

The AppDomain friendly name.

Remarks

Gets the AppDomain friendly name.

ExceptionObject

Gets the exception object used to initialize this event.

public Exception ExceptionObject { get; }

Property Value

Exception

The exception object used to initialize this event.

Remarks

Gets the exception object used to initialize this event. Note that this event may not have a valid exception object. If the event is serialized the exception object will not be transferred. To get the text of the exception the GetExceptionString() method must be used not this property.

If there is no defined exception object for this event then null will be returned.

Fix

The fixed fields in this event

public FixFlags Fix { get; set; }

Property Value

FixFlags

The set of fields that are fixed in this event

Remarks

Fields will not be fixed if they have previously been fixed. It is not possible to 'unfix' a field.

Identity

Gets the identity of the current thread principal.

public string Identity { get; }

Property Value

string

The string name of the identity of the current thread principal.

Remarks

Calls System.Threading.Thread.CurrentPrincipal.Identity.Name to get the name of the current thread principal.

Level

Gets the Level of the logging event.

public Level Level { get; }

Property Value

Level

The Level of the logging event.

Remarks

Gets the Level of the logging event.

LocationInformation

Gets the location information for this logging event.

public LocationInfo LocationInformation { get; }

Property Value

LocationInfo

The location information for this logging event.

Remarks

The collected information is cached for future use.

See the LocationInfo class for more information on supported frameworks and the different behavior in Debug and Release builds.

LoggerName

Gets the name of the logger that logged the event.

public string LoggerName { get; }

Property Value

string

The name of the logger that logged the event.

Remarks

Gets the name of the logger that logged the event.

MessageObject

Gets the message object used to initialize this event.

public object MessageObject { get; }

Property Value

object

The message object used to initialize this event.

Remarks

Gets the message object used to initialize this event. Note that this event may not have a valid message object. If the event is serialized the message object will not be transferred. To get the text of the message the RenderedMessage property must be used not this property.

If there is no defined message object for this event then null will be returned.

Properties

Additional event specific properties.

public PropertiesDictionary Properties { get; }

Property Value

PropertiesDictionary

Additional event specific properties.

Remarks

A logger or an appender may attach additional properties to specific events. These properties have a string key and an object value.

This property is for events that have been added directly to this event. The aggregate properties (which include these event properties) can be retrieved using LookupProperty(string) and GetProperties().

Once the properties have been fixed Fix this property returns the combined cached properties. This ensures that updates to this property are always reflected in the underlying storage. When returning the combined properties there may be more keys in the Dictionary than expected.

RenderedMessage

Gets the message, rendered through the RendererMap.

public string RenderedMessage { get; }

Property Value

string

The message rendered through the RendererMap.

Remarks

The collected information is cached for future use.

Repository

The ILoggerRepository that this event was created in.

public ILoggerRepository Repository { get; }

Property Value

ILoggerRepository

Remarks

The ILoggerRepository that this event was created in.

StartTime

Gets the time when the current process started.

public static DateTime StartTime { get; }

Property Value

DateTime

This is the time when this process started.

Remarks

The TimeStamp is stored internally in UTC and converted to the local time zone for this computer.

Tries to get the start time for the current process. Failing that it returns the time of the first call to this property.

Note that AppDomains may be loaded and unloaded within the same process without the process terminating and therefore without the process start time being reset.

StartTimeUtc

Gets the UTC time when the current process started.

public static DateTime StartTimeUtc { get; }

Property Value

DateTime

This is the UTC time when this process started.

Remarks

Tries to get the start time for the current process. Failing that it returns the time of the first call to this property.

Note that AppDomains may be loaded and unloaded within the same process without the process terminating and therefore without the process start time being reset.

ThreadName

Gets the name of the current thread.

public string ThreadName { get; }

Property Value

string

The name of the current thread, or the thread ID when the name is not available.

Remarks

The collected information is cached for future use.

TimeStamp

Gets the time of the logging event.

public DateTime TimeStamp { get; }

Property Value

DateTime

The time of the logging event.

Remarks

The TimeStamp is stored in UTC and converted to the local time zone for this computer.

TimeStampUtc

Gets UTC the time of the logging event.

public DateTime TimeStampUtc { get; }

Property Value

DateTime

The UTC time of the logging event.

UserName

Gets the name of the current user.

public string UserName { get; }

Property Value

string

The name of the current user, or NOT AVAILABLE when the underlying runtime has no support for retrieving the name of the current user.

Remarks

Calls WindowsIdentity.GetCurrent().Name to get the name of the current windows user.

To improve performance, we could cache the string representation of the name, and reuse that as long as the identity stayed constant. Once the identity changed, we would need to re-assign and re-render the string.

However, the WindowsIdentity.GetCurrent() call seems to return different objects every time, so the current implementation doesn't do this type of caching.

Timing for these operations:

MethodResults
WindowsIdentity.GetCurrent()10000 loops, 00:00:00.2031250 seconds
WindowsIdentity.GetCurrent().Name10000 loops, 00:00:08.0468750 seconds

This means we could speed things up almost 40 times by caching the value of the WindowsIdentity.GetCurrent().Name property, since this takes (8.04-0.20) = 7.84375 seconds.

Methods

FixVolatileData()

Fix instance fields that hold volatile data.

[Obsolete("Use Fix property")]
public void FixVolatileData()

Remarks

Some of the values in instances of LoggingEvent are considered volatile, that is the values are correct at the time the event is delivered to appenders, but will not be consistent at any time afterwards. If an event is to be stored and then processed at a later time these volatile values must be fixed by calling FixVolatileData(). There is a performance penalty incurred by calling FixVolatileData() but it is essential to maintaining data consistency.

Calling FixVolatileData() is equivalent to calling FixVolatileData(bool) passing the parameter false.

See FixVolatileData(bool) for more information.

FixVolatileData(bool)

Fixes instance fields that hold volatile data.

[Obsolete("Use Fix property")]
public void FixVolatileData(bool fastButLoose)

Parameters

fastButLoose bool

Set to true to not fix data that takes a long time to fix.

Remarks

Some of the values in instances of LoggingEvent are considered volatile, that is the values are correct at the time the event is delivered to appenders, but will not be consistent at any time afterwards. If an event is to be stored and then processed at a later time these volatile values must be fixed by calling FixVolatileData(). There is a performance penalty for incurred by calling FixVolatileData() but it is essential to maintaining data consistency.

The fastButLoose param controls the data that is fixed. Some of the data that can be fixed takes a long time to generate, therefore if you do not require those settings to be fixed they can be ignored by setting the fastButLoose param to true. This setting will ignore the LocationInformation and UserName settings.

Set fastButLoose to false to ensure that all settings are fixed.

FixVolatileData(FixFlags)

Fix the fields specified by the FixFlags parameter

protected void FixVolatileData(FixFlags flags)

Parameters

flags FixFlags

the fields to fix

Remarks

Only fields specified in the flags will be fixed. Fields will not be fixed if they have previously been fixed. It is not possible to 'unfix' a field.

GetExceptionStrRep()

Returns this event's exception's rendered using the RendererMap.

[Obsolete("Use GetExceptionString instead")]
public string GetExceptionStrRep()

Returns

string

This event's exception's rendered using the RendererMap.

Remarks

Obsolete. Use GetExceptionString() instead.

GetExceptionString()

Returns this event's exception's rendered using the RendererMap.

public string GetExceptionString()

Returns

string

This event's exception's rendered using the RendererMap.

Remarks

Returns this event's exception's rendered using the RendererMap.

GetLoggingEventData()

Gets the portable data for this LoggingEvent.

public LoggingEventData GetLoggingEventData()

Returns

LoggingEventData

The LoggingEventData for this event.

Remarks

A new LoggingEvent can be constructed using a LoggingEventData instance.

Does a Partial fix of the data in the logging event before returning the event data.

GetLoggingEventData(FixFlags)

Gets the portable data for this LoggingEvent.

public LoggingEventData GetLoggingEventData(FixFlags fixFlags)

Parameters

fixFlags FixFlags

The set of data to ensure is fixed in the LoggingEventData

Returns

LoggingEventData

The LoggingEventData for this event.

Remarks

A new LoggingEvent can be constructed using a LoggingEventData instance.

GetObjectData(SerializationInfo, StreamingContext)

Serializes this object into the SerializationInfo provided.

[SecurityCritical]
public virtual void GetObjectData(SerializationInfo info, StreamingContext context)

Parameters

info SerializationInfo

The SerializationInfo to populate with data.

context StreamingContext

The destination for this serialization.

Remarks

The data in this event must be fixed before it can be serialized.

The FixVolatileData() method must be called during the DoAppend(LoggingEvent) method call if this event is to be used outside that method.

GetProperties()

Get all the composite properties in this event

public PropertiesDictionary GetProperties()

Returns

PropertiesDictionary

the PropertiesDictionary containing all the properties

Remarks

See LookupProperty(string) for details of the composite properties stored by the event.

This method returns a single PropertiesDictionary containing all the properties defined for this event.

LookupProperty(string)

Lookup a composite property in this event

public object LookupProperty(string key)

Parameters

key string

the key for the property to lookup

Returns

object

the value for the property

Remarks

This event has composite properties that combine together properties from several different contexts in the following order:

WriteRenderedMessage(TextWriter)

Write the rendered message to a TextWriter

public void WriteRenderedMessage(TextWriter writer)

Parameters

writer TextWriter

the writer to write the message to

Remarks

Unlike the RenderedMessage property this method does store the message data in the internal cache. Therefore if called only once this method should be faster than the RenderedMessage property, however if the message is to be accessed multiple times then the property will be more efficient.