com.kdgregory.log4j.aws.internal.shared

Class AbstractAppender<WriterConfigType,AppenderStatsType extends AbstractAppenderStatistics,AppenderStatsMXBeanType>

java.lang.Object

org.apache.log4j.AppenderSkeleton

com.kdgregory.log4j.aws.internal.shared.AbstractAppender<WriterConfigType,AppenderStatsType,AppenderStatsMXBeanType>

All Implemented Interfaces:

org.apache.log4j.Appender, org.apache.log4j.spi.OptionHandler

Direct Known Subclasses:

CloudWatchAppender, KinesisAppender, SNSAppender

public abstract class AbstractAppender<WriterConfigType,AppenderStatsType extends AbstractAppenderStatistics,AppenderStatsMXBeanType>
extends org.apache.log4j.AppenderSkeleton

Common implementation code that's shared between appenders.

For the most part, appenders have the same behavior: they initialize, transform log messages, and shut down. Most of the code to do that lives here, with a few hooks that are implemented in the appender proper.

Note that some behaviors, such as log rotation, are implemented here even if they are not supported by all appenders. The appenders that do not support those behaviors are responsible for disabling them. For example, an appender that does not support log rotation should throw if setRotationMode(java.lang.String) is called.

Note that most of the member variables defined by this class are protected. This is primarily to support testing, but also follows my philosophy of related classes: there is no logical difference between direct access properties; in both cases you're defining an API. Of course, this is a public API for an internal class, so any application code that touches these variables should not be surprised if they cease to exist.

Field Summary

Fields

Modifier and Type	Field and Description
protected AppenderStatsType	appenderStats
protected long	batchDelay
protected String	clientEndpoint
protected String	clientFactory
protected MessageQueue.DiscardAction	discardAction
protected int	discardThreshold
protected int	lastRotationCount
protected long	lastRotationTimestamp
protected long	rotationInterval
protected RotationMode	rotationMode
protected AtomicInteger	sequence
protected ThreadFactory	threadFactory
protected LogWriter	writer
protected WriterFactory<WriterConfigType,AppenderStatsType>	writerFactory

Fields inherited from class org.apache.log4j.AppenderSkeleton

errorHandler, headFilter, layout, name, tailFilter, threshold

Constructor Summary

Constructors

Constructor and Description
AbstractAppender(ThreadFactory threadFactory, WriterFactory<WriterConfigType,AppenderStatsType> writerFactory, AppenderStatsType appenderStats, Class<AppenderStatsMXBeanType> appenderStatsMXBeanClass)

Method Summary

Modifier and Type	Method and Description
protected void	append(org.apache.log4j.spi.LoggingEvent event)
void	close()
protected abstract WriterConfigType	generateWriterConfig() Called just before a writer is created, so that the subclass can perform substitutions on the configuration.
AppenderStatsType	getAppenderStatistics() Returns the appender statistics object.
long	getBatchDelay() Returns the maximum batch delay; see setBatchDelay(long).
String	getClientEndpoint() Returns the current service endpoint.
String	getClientFactory() Returns the current AWS client factory class/method name.
String	getDiscardAction() Returns the configured discard action.
int	getDiscardThreshold() Returns the configured discard threshold.
long	getRotationInterval() Returns the current rotation interval.
String	getRotationMode() Returns the current rotation mode.
int	getSequence() Returns the current log sequence number.
protected abstract boolean	isMessageTooLarge(LogMessage message) Called append(org.apache.log4j.spi.LoggingEvent) to ensure that we don't have a single message that violates AWS batching rules.
protected void	registerStatisticsBean() Registers the appender statistics with JMX.
boolean	requiresLayout()
protected void	rotate() Rotates the log writer.
void	setBatchDelay(long value) Sets the maximum batch delay, in milliseconds.
void	setClientEndpoint(String value) Sets the service endpoint.
void	setClientFactory(String value) Sets a static AWS client factory method, which will be called instead of the writer's internal client factory.
void	setDiscardAction(String value) Sets the action to take when the number of unsent messages exceeds the discard threshold.
void	setDiscardThreshold(int value) Sets the number of unsent messages that will trigger message discard.
void	setRotationInterval(long value) Sets the rotation interval, for those appenders that support rotation.
void	setRotationMode(String value) Sets the rule for log stream rotation, for those appenders that support rotation.
void	setSequence(int value) Sets the log sequence number, used by the {sequence} substitution variable.
protected void	unregisterStatisticsBean() Unregisters the appender statistics from JMX.

Methods inherited from class org.apache.log4j.AppenderSkeleton

activateOptions, addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setErrorHandler, setLayout, setName, setThreshold

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

threadFactory

protected ThreadFactory threadFactory

writerFactory

protected WriterFactory<WriterConfigType,AppenderStatsType extends AbstractAppenderStatistics> writerFactory

appenderStats

protected AppenderStatsType extends AbstractAppenderStatistics appenderStats

writer

protected volatile LogWriter writer

lastRotationTimestamp

protected volatile long lastRotationTimestamp

lastRotationCount

protected volatile int lastRotationCount

batchDelay

protected long batchDelay

discardThreshold

protected int discardThreshold

discardAction

protected MessageQueue.DiscardAction discardAction

rotationMode

protected RotationMode rotationMode

rotationInterval

protected long rotationInterval

sequence

protected AtomicInteger sequence

clientFactory

protected String clientFactory

clientEndpoint

protected String clientEndpoint

Constructor Detail

AbstractAppender

public AbstractAppender(ThreadFactory threadFactory,
                        WriterFactory<WriterConfigType,AppenderStatsType> writerFactory,
                        AppenderStatsType appenderStats,
                        Class<AppenderStatsMXBeanType> appenderStatsMXBeanClass)

Method Detail

setBatchDelay

public void setBatchDelay(long value)

Sets the maximum batch delay, in milliseconds.

The writer attempts to gather multiple logging messages into a batch, to reduce communication with the service. The batch delay controls the time that a message will remain in-memory while the writer builds this batch. In a low-volume environment it will be the main determinant of when the batch is sent; in a high volume environment it's likely that the maximum request size will be reached before the batch delay expires.

The default value is 2000, which is rather arbitrarily chosen.

getBatchDelay

public long getBatchDelay()

Returns the maximum batch delay; see setBatchDelay(long). Primarily used for testing.

setDiscardThreshold

public void setDiscardThreshold(int value)

Sets the number of unsent messages that will trigger message discard. A high value is useful when network connectivity is intermittent and/or overall AWS communication is causing throttling. However, a value that is too high may cause out-of-memory errors.

The default, 10,000, is based on the assumptions that (1) each message will be 1k or less, and (2) any app that uses remote logging can afford 10MB.

Note: at present, discard threshold cannot be changed after creating a log writer. For appenders that rotate logs, a new configuration value will be recognized at the time of rotation.

getDiscardThreshold

public int getDiscardThreshold()

Returns the configured discard threshold.

setDiscardAction

public void setDiscardAction(String value)

Sets the action to take when the number of unsent messages exceeds the discard threshold. Values are "none" (retain all messages), "oldest" (discard oldest messages), and "newest" (discard most recent messages).

The default is "oldest". Attempting to set an incorrect value will throw a configuration error.

Note: at present, discard action cannot be changed after creating a log writer. For appenders that rotate logs, a new configuration value will be recognized at the time of rotation.

getDiscardAction

public String getDiscardAction()

Returns the configured discard action.

setRotationMode

public void setRotationMode(String value)

Sets the rule for log stream rotation, for those appenders that support rotation. See RotationMode for values.

Attempting to set an invalid mode is equivalent to "none", but will emit a warning to the Log4J internal log.

getRotationMode

public String getRotationMode()

Returns the current rotation mode.

setRotationInterval

public void setRotationInterval(long value)

Sets the rotation interval, for those appenders that support rotation. This parameter is valid only when the rotationMode parameter is "interval" or "count": for the former, it's the number of milliseconds between rotations, for the latter the number of messages.

If using interval rotation, you should include {timestamp} in the log stream name. If using counted rotation, you should include {sequence}.

getRotationInterval

public long getRotationInterval()

Returns the current rotation interval.

setSequence

public void setSequence(int value)

Sets the log sequence number, used by the {sequence} substitution variable.

getSequence

public int getSequence()

Returns the current log sequence number.

setClientFactory

public void setClientFactory(String value)

Sets a static AWS client factory method, which will be called instead of the writer's internal client factory. This may be useful if the default client is not appropriate (for example, to set a non-default region).

The passed string is of the form com.example.Classname.methodName. If this does not reference a class/method on the classpath then writer initialization will fail.

Calling this method after the writer has been initialized will have no effect (except for those appenders that rotate logs, in which case it will apply to the post-rotate writer).

getClientFactory

public String getClientFactory()

Returns the current AWS client factory class/method name. Will be null if the factory hasn't been set.

setClientEndpoint

public void setClientEndpoint(String value)

Sets the service endpoint. This is intended for use with older AWS SDK versions that do not provide client factories and default to us-east-1, although it can be used for newer releases when you want to override the default region provider. The endpoint setting is ignored if you specify a client factory.

getClientEndpoint

public String getClientEndpoint()

Returns the current service endpoint. Will be null if the endpoint has not been explicitly set.

getAppenderStatistics

public AppenderStatsType getAppenderStatistics()

Returns the appender statistics object.

append

protected void append(org.apache.log4j.spi.LoggingEvent event)

Specified by:

append in class org.apache.log4j.AppenderSkeleton

close

public void close()

requiresLayout

public boolean requiresLayout()

rotate

protected void rotate()

Rotates the log writer. This must be exposed by appenders that support log rotation; they can simply delegate to the super implementation.

generateWriterConfig

protected abstract WriterConfigType generateWriterConfig()

Called just before a writer is created, so that the subclass can perform substitutions on the configuration.

isMessageTooLarge

protected abstract boolean isMessageTooLarge(LogMessage message)

Called append(org.apache.log4j.spi.LoggingEvent) to ensure that we don't have a single message that violates AWS batching rules.

registerStatisticsBean

protected void registerStatisticsBean()

Registers the appender statistics with JMX. Logs but otherwise ignores failure.

The name for the bean is consistent with the Log4J LayoutDynamicMBean, so that it will appear in the hierarchy under the appender.

Note: this method is protected so that it can be avoided during unit tests.

unregisterStatisticsBean

protected void unregisterStatisticsBean()

Unregisters the appender statistics from JMX. This is called when the appender is closed. Logs but otherwise ignores failure.

Note: this method is protected so that it can be avoided during unit tests.