Class BufferingAppenderSkeleton

Namespace

log4net.Appender

Assembly

log4net.dll

Abstract base class implementation of IAppender that buffers events in a fixed size buffer.

public abstract class BufferingAppenderSkeleton : AppenderSkeleton, IBulkAppender, IAppender, IOptionHandler

Inheritance

object

AppenderSkeleton

BufferingAppenderSkeleton

Implements

IBulkAppender

IAppender

IOptionHandler

Derived

AdoNetAppender

BufferingForwardingAppender

RemotingAppender

SmtpAppender

SmtpPickupDirAppender

Inherited Members

AppenderSkeleton.Close()

AppenderSkeleton.DoAppend(LoggingEvent)

AppenderSkeleton.DoAppend(LoggingEvent[])

AppenderSkeleton.FilterEvent(LoggingEvent)

AppenderSkeleton.AddFilter(IFilter)

AppenderSkeleton.ClearFilters()

AppenderSkeleton.IsAsSevereAsThreshold(Level)

AppenderSkeleton.Append(LoggingEvent[])

AppenderSkeleton.PreAppendCheck()

AppenderSkeleton.RenderLoggingEvent(LoggingEvent)

AppenderSkeleton.RenderLoggingEvent(TextWriter, LoggingEvent)

AppenderSkeleton.Threshold

AppenderSkeleton.ErrorHandler

AppenderSkeleton.FilterHead

AppenderSkeleton.Layout

AppenderSkeleton.Name

AppenderSkeleton.RequiresLayout

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This base class should be used by appenders that need to buffer a number of events before logging them. For example the AdoNetAppender buffers events and then submits the entire contents of the buffer to the underlying database in one go.

Subclasses should override the SendBuffer(LoggingEvent[]) method to deliver the buffered events.

The BufferingAppenderSkeleton maintains a fixed size cyclic buffer of events. The size of the buffer is set using the BufferSize property.

A ITriggeringEventEvaluator is used to inspect each event as it arrives in the appender. If the Evaluator triggers, then the current buffer is sent immediately (see SendBuffer(LoggingEvent[])). Otherwise the event is stored in the buffer. For example, an evaluator can be used to deliver the events immediately when an ERROR event arrives.

The buffering appender can be configured in a Lossy mode. By default the appender is NOT lossy. When the buffer is full all the buffered events are sent with SendBuffer(LoggingEvent[]). If the Lossy property is set to true then the buffer will not be sent when it is full, and new events arriving in the appender will overwrite the oldest event in the buffer. In lossy mode the buffer will only be sent when the Evaluator triggers. This can be useful behavior when you need to know about ERROR events but not about events with a lower level, configure an evaluator that will trigger when an ERROR event arrives, the whole buffer will be sent which gives a history of events leading up to the ERROR event.

Constructors

BufferingAppenderSkeleton()

Initializes a new instance of the BufferingAppenderSkeleton class.

protected BufferingAppenderSkeleton()

Remarks

Protected default constructor to allow subclassing.

BufferingAppenderSkeleton(bool)

Initializes a new instance of the BufferingAppenderSkeleton class.

protected BufferingAppenderSkeleton(bool eventMustBeFixed)

Parameters

eventMustBeFixed bool

the events passed through this appender must be fixed by the time that they arrive in the derived class' SendBuffer method.

Remarks

Protected constructor to allow subclassing.

The eventMustBeFixed should be set if the subclass expects the events delivered to be fixed even if the BufferSize is set to zero, i.e. when no buffering occurs.

Properties

BufferSize

Gets or sets the size of the cyclic buffer used to hold the logging events.

public int BufferSize { get; set; }

Property Value

int

The size of the cyclic buffer used to hold the logging events.

Remarks

The BufferSize option takes a positive integer representing the maximum number of logging events to collect in a cyclic buffer. When the BufferSize is reached, oldest events are deleted as new events are added to the buffer. By default the size of the cyclic buffer is 512 events.

If the BufferSize is set to a value less than or equal to 1 then no buffering will occur. The logging event will be delivered synchronously (depending on the Lossy and Evaluator properties). Otherwise the event will be buffered.

Evaluator

Gets or sets the ITriggeringEventEvaluator that causes the buffer to be sent immediately.

public ITriggeringEventEvaluator Evaluator { get; set; }

Property Value

ITriggeringEventEvaluator

The ITriggeringEventEvaluator that causes the buffer to be sent immediately.

Remarks

The evaluator will be called for each event that is appended to this appender. If the evaluator triggers then the current buffer will immediately be sent (see SendBuffer(LoggingEvent[])).

If Lossy is set to true then an Evaluator must be specified.

Fix

Gets or sets a the fields that will be fixed in the event

public virtual FixFlags Fix { get; set; }

Property Value

FixFlags

The event fields that will be fixed before the event is buffered

Remarks

The logging event needs to have certain thread specific values captured before it can be buffered. See Fix for details.

See Also

Fix

Lossy

Gets or sets a value that indicates whether the appender is lossy.

public bool Lossy { get; set; }

Property Value

bool

true if the appender is lossy, otherwise false. The default is false.

Remarks

This appender uses a buffer to store logging events before delivering them. A triggering event causes the whole buffer to be send to the remote sink. If the buffer overruns before a triggering event then logging events could be lost. Set Lossy to false to prevent logging events from being lost.

If Lossy is set to true then an Evaluator must be specified.

LossyEvaluator

Gets or sets the value of the ITriggeringEventEvaluator to use.

public ITriggeringEventEvaluator LossyEvaluator { get; set; }

Property Value

ITriggeringEventEvaluator

The value of the ITriggeringEventEvaluator to use.

Remarks

The evaluator will be called for each event that is discarded from this appender. If the evaluator triggers then the current buffer will immediately be sent (see SendBuffer(LoggingEvent[])).

OnlyFixPartialEventData

Gets or sets a value indicating if only part of the logging event data should be fixed.

[Obsolete("Use Fix property")]
public virtual bool OnlyFixPartialEventData { get; set; }

Property Value

bool

true if the appender should only fix part of the logging event data, otherwise false. The default is false.

Remarks

Setting this property to true will cause only part of the event data to be fixed and serialized. This will improve performance.

See LoggingEvent.FixVolatileData(FixFlags) for more information.

Methods

ActivateOptions()

Initialize the appender based on the options set

public override void ActivateOptions()

Remarks

This is part of the IOptionHandler delayed object activation scheme. The ActivateOptions() method must be called on this object after the configuration properties have been set. Until ActivateOptions() is called this object is in an undefined state and must not be used.

If any of the configuration properties are modified then ActivateOptions() must be called again.

Append(LoggingEvent)

This method is called by the AppenderSkeleton.DoAppend(LoggingEvent) method.

protected override void Append(LoggingEvent loggingEvent)

Parameters

loggingEvent LoggingEvent

the event to log

Remarks

Stores the loggingEvent in the cyclic buffer.

The buffer will be sent (i.e. passed to the SendBuffer(LoggingEvent[]) method) if one of the following conditions is met:

• The cyclic buffer is full and this appender is marked as not lossy (see Lossy)
• An Evaluator is set and it is triggered for the loggingEvent specified.

Before the event is stored in the buffer it is fixed (see LoggingEvent.FixVolatileData(FixFlags)) to ensure that any data referenced by the event will be valid when the buffer is processed.

Flush()

Flush the currently buffered events

public virtual void Flush()

Remarks

Flushes any events that have been buffered.

If the appender is buffering in Lossy mode then the contents of the buffer will NOT be flushed to the appender.

Flush(bool)

Flush the currently buffered events

public virtual void Flush(bool flushLossyBuffer)

Parameters

flushLossyBuffer bool

set to true to flush the buffer of lossy events

Remarks

Flushes events that have been buffered. If flushLossyBuffer is false then events will only be flushed if this buffer is non-lossy mode.

If the appender is buffering in Lossy mode then the contents of the buffer will only be flushed if flushLossyBuffer is true. In this case the contents of the buffer will be tested against the LossyEvaluator and if triggering will be output. All other buffered events will be discarded.

If flushLossyBuffer is true then the buffer will always be emptied by calling this method.

OnClose()

Close this appender instance.

protected override void OnClose()

Remarks

Close this appender instance. If this appender is marked as not Lossy then the remaining events in the buffer must be sent when the appender is closed.

SendBuffer(LoggingEvent[])

Sends the events.

protected abstract void SendBuffer(LoggingEvent[] events)

Parameters

events LoggingEvent[]

The events that need to be send.

Remarks

The subclass must override this method to process the buffered events.

SendFromBuffer(LoggingEvent, CyclicBuffer)

Sends the contents of the buffer.

protected virtual void SendFromBuffer(LoggingEvent firstLoggingEvent, CyclicBuffer buffer)

Parameters

firstLoggingEvent LoggingEvent

The first logging event.

buffer CyclicBuffer

The buffer containing the events that need to be send.

Remarks

The subclass must override SendBuffer(LoggingEvent[]).