Apache Log4cxx  Version 2.0.0
Loading...
Searching...
No Matches
log4cxx::AsyncAppender Class Reference

The AsyncAppender decouples logging event creation from output by processing log events asynchronously. More...

#include <asyncappender.h>

Inheritance diagram for log4cxx::AsyncAppender:
log4cxx::spi::AppenderAttachable log4cxx::AppenderSkeleton log4cxx::helpers::Object log4cxx::Appender log4cxx::spi::OptionHandler log4cxx::helpers::Object

Public Member Functions

 AsyncAppender ()
 Create new instance.
virtual ~AsyncAppender ()
 If not closed, calls AsyncAppender::close.
void addAppender (const AppenderPtr &newAppender) override
 Ensure newAppender receives any logging event added to this appender.
void doAppend (const spi::LoggingEventPtr &event) override
 Call AppenderSkeleton::doAppendImpl without acquiring a lock.
void append (const spi::LoggingEventPtr &event) override
 Add event to a ring buffer.
AppenderList getAllAppenders () const override
 Get iterator over attached appenders.
AppenderPtr getAppender (const LogString &name) const override
 Get appender by name.
bool isAttached (const AppenderPtr &appender) const override
 Determines if specified appender is attached.
void removeAllAppenders () override
 Removes and closes all attached appenders.
bool removeAppender (const AppenderPtr &appender) override
 Remove appender.
bool removeAppender (const LogString &name) override
 Remove the name appender.
bool replaceAppender (const AppenderPtr &oldAppender, const AppenderPtr &newAppender) override
 Replace oldAppender with newAppender.
void replaceAppenders (const AppenderList &newList) override
 Replace any previously added appenders with newList.
void setBufferSize (int newSize)
 Use newSize (an integer value in the range 1 to 10 million) for the number of logging events the ring buffer can hold.
int getBufferSize () const
 Gets the current buffer size.
void setBlocking (bool newValue)
 Use newValue for whether appender should block the calling thread if there is no space in the ring buffer.
bool getBlocking () const
 Gets whether appender should block calling thread when ring buffer is full.
void setOption (const LogString &option, const LogString &value) override
 Override this method to set option to value.
Public Member Functions inherited from log4cxx::spi::AppenderAttachable
virtual ~AppenderAttachable ()
Public Member Functions inherited from log4cxx::helpers::Object
virtual ~Object ()
virtual const helpers::Class & getClass () const =0
virtual bool instanceof (const Class &clazz) const =0
virtual const void * cast (const Class &clazz) const =0
Public Member Functions inherited from log4cxx::AppenderSkeleton
 AppenderSkeleton (const LayoutPtr &layout={})
virtual ~AppenderSkeleton ()
void activateOptions () override
 Activate the options that were previously set with calls to option setters.
void addFilter (const spi::FilterPtr &newFilter) override
 Add newFilter to end of the spi::Filter chain.
void clearFilters () override
 Clear the spi::Filter chain.
void close () override
 Release any resources allocated within the appender such as file handles, network connections, etc.
const spi::ErrorHandlerPtr getErrorHandler () const
 The currently set spi::ErrorHandler for this Appender.
spi::FilterPtr getFilter () const override
 The first spi::Filter in the filter chain for this Appender.
const spi::FilterPtr getFirstFilter () const
 The first spi::Filter in the filter chain for this Appender.
LayoutPtr getLayout () const override
 The currently set Layout for this appender.
LogString getName () const override
 The name of this Appender.
const LevelPtr getThreshold () const
 This appender's current threshold level.
bool isAsSevereAsThreshold (const LevelPtr &level) const
 Is level greater than or equal to this appender's threshold?
void setErrorHandler (const spi::ErrorHandlerPtr &newValue)
 Use newValue as the spi::ErrorHandler for this Appender.
void setLayout (const LayoutPtr &newValue) override
 Use newValue as the layout for this appender.
void setName (const LogString &newValue) override
 Use newValue for the name of this Appender.
void setThreshold (const LevelPtr &newValue)
 Use newValue as this appender's threshold level.
void activateOptions (helpers::Pool &)
Public Member Functions inherited from log4cxx::Appender
virtual ~Appender ()
void doAppend (const spi::LoggingEventPtr &event, helpers::Pool &pool)
virtual bool requiresLayout () const
Public Member Functions inherited from log4cxx::spi::OptionHandler
virtual ~OptionHandler ()
void activateOptions (helpers::Pool &)

Static Public Attributes

static const int MaxBufferedEventCount = 10000000

Additional Inherited Members

Protected Member Functions inherited from log4cxx::AppenderSkeleton
 AppenderSkeleton (LOG4CXX_PRIVATE_PTR(AppenderSkeletonPrivate) priv)
void doAppendImpl (const spi::LoggingEventPtr &event)
 Call the AppenderSkeleton::append method if the level of event is not lower than this appender's threshold and no attached spi::Filter indicates event is rejected.
bool isAccepted (const spi::LoggingEventPtr &event) const
 Does no attached filter deny event or does an attached filter accept event?

Detailed Description

The AsyncAppender decouples logging event creation from output by processing log events asynchronously.

The AsyncAppender stores the logging event in a bounded buffer and then returns control to the application. A separate thread forwards events to the attached appender(s).

An AsyncAppender is used when you configure a logger to be asynchronous. These AsyncAppender(s) use the default values for all options and they cannot be changed using configuration file entries. For more control over the AsyncAppender options, use appender-ref element in the logger configuration instead.

Important notes:

  • Your application must call LogManager::shutdown when it exits to prevent undefined behaviour when using this appender.
  • Runtime configuration of options requires an XML configuration file (see the example below).

This appender is useful when outputting to a slow event sink, for example, unbuffered output to a file, a remote SMTP server or a database. Note that configuring a FileAppender to use buffered output usually results in lower overhead than attaching the FileAppender to an AsyncAppender as the inter-thread communication overhead can exceed the time to add a message to a buffer.

You can attach multiple appenders to an AsyncAppender by:

  • calling AsyncAppender::addAppender repeatedly when progammatically configuring Log4cxx.
  • adding multiple appender-ref elements to the appender class="AsyncAppender" element when using runtime configuration.

Here is a sample configuration file:

<?xml version="1.0" encoding="UTF-8" ?>
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
<appender name="A1" class="RollingFileAppender">
<param name="File" value="${PROGRAM_FILE_PATH.PARENT_PATH}/${PROGRAM_FILE_PATH.STEM}.log" />
<layout class="PatternLayout">
<param name="ConversionPattern" value="%d %-5p %c{2} - %m%n"/>
</layout>
</appender>
<appender name="SENDMAIL" class="SMTPAppender">
<param name="from" value="${PROGRAM_FILE_PATH.STEM}@example.org" />
<param name="to" value="some_support_group@example.org" />
<param name="subject" value="Service error detected in ${PROGRAM_FILE_PATH.STEM}" />
<param name="SMTPHost" value="smtp.example.com"/>
<layout class="PatternLayout">
<param name="ConversionPattern" value="%-5p %c{2} - %m%n"/>
</layout>
<!-- triggeringPolicy class="SpecialTriggeringEventEvaluator" -->
<!-- param name="evaluatorClass" value="SpecialTriggeringEventEvaluator" -->
</appender>
<appender name="ASYNC" class="AsyncAppender">
<param name="BufferSize" value="1000"/>
<param name="Blocking" value="false"/>
<appender-ref ref="SENDMAIL"/>
</appender>
<root>
<priority value ="INFO" />
<appender-ref ref="A1" />
<appender-ref ref="ASYNC" />
</root>
</log4j:configuration>

Configurable properties

When the application produces logging events faster than the background thread is able to process, the bounded buffer can become full. In this situation AsyncAppender will either block until the bounded buffer has a free slot or discard the event. The Blocking property controls which behaviour is used. When events are discarded, the logged output will indicate this with a log message prefixed with Discarded. The output may contain one Discarded message per logger name, the logging event of the highest level for each logger whose events have been discarded.

To determine whether the application produces logging events faster than the background thread is able to process, enable Log4cxx internal debugging. The AsyncAppender will output a histogram of queue length frequencies when closed.

See AsyncAppender::setOption for details.

Constructor & Destructor Documentation

◆ AsyncAppender()

log4cxx::AsyncAppender::AsyncAppender ( )

Create new instance.

◆ ~AsyncAppender()

virtual log4cxx::AsyncAppender::~AsyncAppender ( )
virtual

If not closed, calls AsyncAppender::close.

Member Function Documentation

◆ addAppender()

void log4cxx::AsyncAppender::addAppender ( const AppenderPtr & newAppender)
overridevirtual

Ensure newAppender receives any logging event added to this appender.

Parameters
newAppenderappender to add, may not be null.

Implements log4cxx::spi::AppenderAttachable.

◆ append()

void log4cxx::AsyncAppender::append ( const spi::LoggingEventPtr & event)
overridevirtual

Add event to a ring buffer.

The behaviour when the ring buffer is full is controlled by the Blocking property value.

Implements log4cxx::AppenderSkeleton.

◆ doAppend()

void log4cxx::AsyncAppender::doAppend ( const spi::LoggingEventPtr & event)
overridevirtual

Call AppenderSkeleton::doAppendImpl without acquiring a lock.

Reimplemented from log4cxx::AppenderSkeleton.

◆ getAllAppenders()

AppenderList log4cxx::AsyncAppender::getAllAppenders ( ) const
overridevirtual

Get iterator over attached appenders.

Returns
list of all attached appenders.

Implements log4cxx::spi::AppenderAttachable.

◆ getAppender()

AppenderPtr log4cxx::AsyncAppender::getAppender ( const LogString & name) const
overridevirtual

Get appender by name.

Parameters
namename, may not be null.
Returns
matching appender or null.

Implements log4cxx::spi::AppenderAttachable.

◆ getBlocking()

bool log4cxx::AsyncAppender::getBlocking ( ) const

Gets whether appender should block calling thread when ring buffer is full.

If false, messages will be counted by logger and a summary message added after the buffered events have been appended.

Returns
true if calling thread will be blocked when ring buffer is full.

◆ getBufferSize()

int log4cxx::AsyncAppender::getBufferSize ( ) const

Gets the current buffer size.

Returns
the current value of the BufferSize option.

◆ isAttached()

bool log4cxx::AsyncAppender::isAttached ( const AppenderPtr & appender) const
overridevirtual

Determines if specified appender is attached.

Parameters
appenderappender.
Returns
true if attached.

Implements log4cxx::spi::AppenderAttachable.

◆ removeAllAppenders()

void log4cxx::AsyncAppender::removeAllAppenders ( )
overridevirtual

Removes and closes all attached appenders.

Implements log4cxx::spi::AppenderAttachable.

◆ removeAppender() [1/2]

bool log4cxx::AsyncAppender::removeAppender ( const AppenderPtr & appender)
overridevirtual

Remove appender.

Returns
true if successful.

Implements log4cxx::spi::AppenderAttachable.

◆ removeAppender() [2/2]

bool log4cxx::AsyncAppender::removeAppender ( const LogString & name)
overridevirtual

Remove the name appender.

Returns
true if successful.

Implements log4cxx::spi::AppenderAttachable.

◆ replaceAppender()

bool log4cxx::AsyncAppender::replaceAppender ( const AppenderPtr & oldAppender,
const AppenderPtr & newAppender )
overridevirtual

Replace oldAppender with newAppender.

Returns
true if oldAppender was replaced with newAppender.

Implements log4cxx::spi::AppenderAttachable.

◆ replaceAppenders()

void log4cxx::AsyncAppender::replaceAppenders ( const AppenderList & newList)
overridevirtual

Replace any previously added appenders with newList.

Implements log4cxx::spi::AppenderAttachable.

◆ setBlocking()

void log4cxx::AsyncAppender::setBlocking ( bool newValue)

Use newValue for whether appender should block the calling thread if there is no space in the ring buffer.

Parameters
newValuetrue if appender should wait until space is available in the ring buffer.

◆ setBufferSize()

void log4cxx::AsyncAppender::setBufferSize ( int newSize)

Use newSize (an integer value in the range 1 to 10 million) for the number of logging events the ring buffer can hold.

The ring buffer size cannot be changed once the appender has received an event.

◆ setOption()

void log4cxx::AsyncAppender::setOption ( const LogString & option,
const LogString & value )
overridevirtual

Override this method to set option to value.

Supported options Supported values Default value
BufferSize 1..10000000 128
Blocking True,False True
See also
AppenderSkeleton::setOption()

Reimplemented from log4cxx::AppenderSkeleton.

Member Data Documentation

◆ MaxBufferedEventCount

const int log4cxx::AsyncAppender::MaxBufferedEventCount = 10000000
static

The documentation for this class was generated from the following file: