org.apache.log4j.AppenderSkeleton
org.apache.log4j.WriterAppender
org.apache.log4j.FileAppender
uk.org.simonsite.log4j.appender.TimeAndSizeRollingAppender
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public final class TimeAndSizeRollingAppender
This appender is responsible for writing log events to file, and rolling
files when they reach configurable limits of time and/or size. It is
configured and behaves in much the same way as the
DailyRollingFileAppender, with some useful
differences.
Maximum log file size can be configured (default 10MB) using the MaxFileSize property. This means that log files can be rolled within the configured time period if the maximum file size is exceeded. Backups are indicated by a count suffix at the end of log filenames, e.g. for the time suffix specified by the default pattern "'.'yyyy-MM-dd" (which would ordinarily result in a log file named e.g. "foo.log.2007-01-01") will result in backups named "foo.log.2007-01-01.1", "foo.log.2007-01-01.2", etc.
Configuring the maximum number of allowable backup log files (default 10) using the MaxRollFileCount property helps prevent this appender from consuming disk space without limit. Excess backup log files are scavenged by a background thread.
Configuring the scavenging interval (default 30 seconds) using the ScavengeInterval property specifies the duration for which the scavenger thread should sleep between operations. The log file scavenger only operates upon files that start with the path specified by the File configuration parameter. Older files will be deleted first.
Setting a scavenge interval of -1 prevents the scavenger from running.
Backup log file compression may be configured using the allowed compression algorithms specified by the CompressionAlgorithm property:
Default behaviour is not to compress backup log files unless the
CompressionAlgorithm property is configured. Backup files are
compressed by a background thread. At roll time the name of the backup log
File object is put into the compressor thread's FIFO queue.
By default the compressor works on a best-effort basis: if the queue fills
up, then older backup filenames are discarded and will therefore not be
compressed.
The appender can be configured to force compression of all backup files by
setting the CompressionUseBlockingQueue property to "
true" (default is "false"). Forcing
compression comes at the cost of blocking the compressor's queue and
therefore the shared daemon thread used for compression and scavenging tasks;
the application thread that invoked the Logger will
not be blocked. The queue will cease to block once the current compression
operation has completed and the compressor has removed the next file from its
queue.
The appender's CompressionMinQueueSize property (default 0) controls the minimum number of backup files that must be in the queue awaiting compression before any compression will take actually take place. For example, if this property is set to 5, then at least 5 backup file rolls must take place before the oldest file currently in the compressor's queue will be compressed. Keeping the most recent files uncompressed can be helpful at support time.
You may choose to register a FileCompressionEventListener with the
appender. To do so you must provide your own implementation of the
FileCompressionEventListener interface on the classpath, and
configure it via XML. For example:
<appender name="LOG-DAILYROLL"
class="uk.org.simonsite.log4j
.appender.TimeAndSizeRollingAppender">
<param name="File"
value="/logs/app.log"/>
<param name="CompressionAlgorithm"
value="ZIP"/>
<fileCompressionEventListener
class="com.acme.MyFileCompressionEventListener">
<param name="MyParam" value="Sample
Value"/>
</fileCompressionEventListener>
<layout class="org.apache.log4j.SimpleLayout"/>
</appender>
If you have chosen a daily, weekly, or longer rolling strategy (via the
DatePattern property), then you may wish to take advantage of the
TimeZoneId property. In these cases setting the TimeZoneId
property will ensure that the appender rolls at midnight in the configured
time zone. For legal time zone IDs accepted by the appender, see core Java
API doc for the TimeZone class.
Setting the appender's DateRollEnforced property to true
(default false) activates pro-active log rolling at time boundaries.
Time boundaries are enforced by a background thread. The standard
DailyRollingFileAppender only rolls log files
reactively upon the dispatch of a logging event. This appender allows
proactive control over log rolling by enforcing a schedule implied by the
DatePattern property. For example, <param
name="DatePattern" value=".yyyy-MM-dd"/> will see the
log file roll at the end of the day, even if the application is otherwise
inactive. Similarly <param name="DatePattern"
value=".yyyy-MM-dd-HH"/> will result in log files being rolled
every hour.
A custom message of your choosing may be written into the first line of each
new log file created after a file roll has completed. This is achieved by
setting the FileRollEventMessage property to a message string. If
this property is configured with a blank value (e.g. <param
name="FileRollEventMessage"/>), the appender will ensure that a
default message is written at the top of the new log file instead. If this
property is not set, no message will be written to the top of new log files.
Messages are appended at Level.ALL using the root
logger.
As an alternative to a message being written on file roll you may choose the
greater flexibility afforded by registering a FileRollEventListener
with the appender. To do so you must provide your own implementation of the
FileRollEventListener interface on the classpath, and configure it
via XML. For example:
<appender name="LOG-DAILYROLL"
class="uk.org.simonsite.log4j
.appender.TimeAndSizeRollingAppender">
<param name="File"
value="/logs/app.log"/>
<fileRollEventListener
class="com.acme.MyFileRollEventListener" >
<param name="MyParam" value="Sample
Value"/>
</fileRollEventListener>
<layout class="org.apache.log4j.SimpleLayout"/>
</appender>
The appender can be configured to roll the most recent backup file, regardless of the file's last modification time or size, immediately after receiving the first logging event after the appender's options are activated.
For example, say the appender is configured to roll every hour, or for files exceeding 10MB in size, and that a 1 MB log file exists that was last written 10 minutes before the hour. The application is restarted 5 minutes before the hour and logs an event. When the RollOnStartup property is set to true, the log file described in this example scenario will be rolled into a backup, and a new log file will be created.
NB If you use a Layout that writes headers
and footers and require a single header and footer per log file, then you
should set the RollOnStartup property to true.
Out-of-the-box Log4J file appenders can be configured to flush after each
append (via WriterAppender#setImmediateFlush()), though this offers
no guarantees that what is appended will actually be written to disk. What is
appended may be stored, for a short time, in memory buffers by the underlying
OS. Therefore, in the event of machine failure, some logging events may be
lost. Setting the FlushToStorageOnAppend property to true
causes this appender to invoke FileDescriptor.sync() after each
append. FlushToStorageOnAppend is false by default.
NB This option comes with a performance overhead and may have
a material impact upon application throughput: applications should be profiled.
An example configuration snippet taken from an actual Log4J XML configuration file is given here (generate the Javadoc to see the correct formatting). This configuration provides an appender that rolls each day and creates log files no larger than 10MB. The number of backup files is checked every 30 seconds, whereupon if the number of backup files exceeds 100 the extra backups will be deleted. The appender will make best efforts to compress backup files using the GZ algorithm.
<appender name="LOG-DAILYROLL"
class="uk.org.simonsite.log4j
.appender.TimeAndSizeRollingAppender">
<param name="File"
value="/logs/app.log"/>
<param name="Threshold" value="DEBUG"/>
<param name="DatePattern"
value=".yyyy-MM-dd"/>
<param name="MaxFileSize"
value="10MB"/>
<param name="MaxRollFileCount"
value="100"/>
<param name="ScavengeInterval"
value="30000"/>
<param name="BufferedIO"
value="false"/>
<param name="CompressionAlgorithm"
value="GZ"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern"
value="%-5p %-23d{ISO8601} [%t] %x: %c{1} - %m%n"/>
</layout>
</appender>
This next configuration provides an appender that rolls each day, creates log files no larger than 100MB, and limits the number of backup files to no more than 10. The number of backup files is checked every 30 seconds, whereupon if the number of backup files exceeds 10 the extra backups will be deleted. The appender will make best efforts to compress backup files using the ZIP algorithm, but it will only compress backup files after more than 5 rolls have taken place during the lifetime of the application instance. Finally, this configuration causes the appender to honour time boundaries by rolling logs pro-actively at the end of each day, rather that reactively in response to a logging event. After file roll is complete, the new log file will have the message "First line of each file following a roll" printed on the first line.
<appender name="LOG-DAILYROLL"
class="uk.org.simonsite.log4j
.appender.TimeAndSizeRollingAppender">
<param name="File"
value="/logs/app.log"/>
<param name="Threshold" value="DEBUG"/>
<param name="DatePattern"
value=".yyyy-MM-dd"/>
<param name="MaxFileSize"
value="100MB"/>
<param name="DateRollEnforced"
value="true"/>
<param name="FileRollEventMessage" value="First
line of each file following a roll"/>
<param name="BufferedIO"
value="false"/>
<param name="CompressionAlgorithm"
value="ZIP"/>
<param name="CompressionMinQueueSize"
value="5"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern"
value="%-5p %-23d{ISO8601} [%t] %x: %c{1} - %m%n"/>
</layout>
</appender>
A final example of the simplest configuration provides an appender that rolls each day and creates log files no larger than 10MB. The number of backup files is checked every 30 seconds, whereupon if the number of backup files exceeds 10 the extra backups will be deleted. Backup files are not compressed, log files are rolled reactively, and no roll event messages are written at the top of each new log file.
<appender name="LOG-DAILYROLL"
class="uk.org.simonsite.log4j
.appender.TimeAndSizeRollingAppender">
<param name="File"
value="/logs/app.log"/>
<param name="Threshold" value="DEBUG"/>
<param name="BufferedIO"
value="false"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern"
value="%-5p %-23d{ISO8601} [%t] %x: %c{1} - %m%n"/>
</layout>
</appender>
DailyRollingFileAppender| Field Summary |
|---|
| Fields inherited from class org.apache.log4j.FileAppender |
|---|
bufferedIO, bufferSize, fileAppend, fileName |
| Fields inherited from class org.apache.log4j.WriterAppender |
|---|
encoding, immediateFlush, qw |
| Fields inherited from class org.apache.log4j.AppenderSkeleton |
|---|
closed, errorHandler, headFilter, layout, name, tailFilter, threshold |
| Constructor Summary | |
|---|---|
TimeAndSizeRollingAppender()
|
|
TimeAndSizeRollingAppender(Layout layout,
String filename)
|
|
TimeAndSizeRollingAppender(Layout layout,
String filename,
boolean append)
|
|
TimeAndSizeRollingAppender(Layout layout,
String filename,
boolean append,
boolean bufferedIO,
int bufferSize)
|
|
| Method Summary | |
|---|---|
void |
activateOptions()
|
void |
close()
|
protected void |
closeFile()
Makes file closing behaviour visible to classes in this package. |
protected OutputStreamWriter |
createWriter(OutputStream os)
|
boolean |
equals(Object other)
|
String |
getCompressionAlgorithm()
|
int |
getCompressionLevel()
|
long |
getCompressionMaxBlockingInterval()
|
int |
getCompressionMinQueueSize()
|
boolean |
getCompressionUseBlockingQueue()
|
String |
getDatePattern()
|
String |
getDatePatternLocale()
|
boolean |
getDateRollEnforced()
|
(package private) LoggingTaskExecutorService |
getExecutorService()
|
(package private) FileRoller |
getFileRoller()
|
String |
getFileRollEventListener()
Deprecated. |
boolean |
getFlushToStorageOnAppend()
|
(package private) FileCompressionEventListener |
getGuestFileCompressionEventListener()
|
(package private) FileRollEventListener |
getGuestFileRollEventListener()
|
(package private) File |
getIoFile()
|
(package private) LogFileCompressorTask |
getLogFileCompressor()
|
(package private) LogFileScavenger |
getLogFileScavenger()
|
String |
getMaxFileSize()
|
int |
getMaxRollFileCount()
|
String |
getMinFreeDiskSpace()
|
(package private) AppenderRollingProperties |
getProperties()
|
boolean |
getRollOnStartup()
|
long |
getScavengeInterval()
|
String |
getTimeZoneId()
|
int |
hashCode()
|
(package private) void |
openFile()
Opens the log file and prepares this appender to write to it. |
boolean |
parseUnrecognizedElement(Element element,
Properties props)
Parses the following elements and configures instances of the classes attributed to each element discovered: <fileRollEventListener class="..." /> for implementors of FileRollEventListener
<fileCompressionEventListener class="..." /> for
implementors of FileCompressionEventListener
<logFileScavenger class="..." /> for
implementors of LogFileScavenger
<logTaskExecutorService class="..." /> for
implementors of LoggingTaskExecutorService
For each of these elements, child <param/> elements are treated as
expected by the DOMConfigurator. |
void |
setCompressionAlgorithm(String compressionAlgorithm)
|
void |
setCompressionLevel(int compressionLevel)
|
void |
setCompressionMaxBlockingInterval(long compressionInterval)
|
void |
setCompressionMinQueueSize(int compressionMinQueueSize)
The minimum number of backup files that must be in the queue awaiting compression before any compression will take place. |
void |
setCompressionUseBlockingQueue(boolean compressionBlockingQueue)
|
void |
setDatePattern(String datePattern)
|
void |
setDatePatternLocale(String datePatternLocale)
Sets the Locale to be used when processing date patterns. |
void |
setDateRollEnforced(boolean dateRollEnforced)
|
void |
setFileRollEventListener(String className)
Deprecated. Configure FileRollEventListeners via XML, using the
"fileRollEventListener" element. |
void |
setFileRollEventMessage(String message)
|
void |
setFlushToStorageOnAppend(boolean flushToStorageOnAppend)
When this property is true, configured values for the properties FileAppender.setBufferedIO(boolean)and
WriterAppender.setImmediateFlush(boolean) are overridden to
false and true, respectively, upon activation of an
instance of this object. |
void |
setLogFileScavenger(String className)
Deprecated. Configure LogFileScavengers via XML, using the
"logFileScavenger" element. |
(package private) void |
setLogTaskExecutorService(LoggingTaskExecutorService loggingTaskExecutorService)
Test use only. |
void |
setMaxFileSize(String value)
|
void |
setMaxRollFileCount(int maxRollFileCount)
|
void |
setMinFreeDiskSpace(long minFreeDiskSpace)
|
void |
setMinFreeDiskSpace(String value)
Warning Use of this property requires Java 6. |
protected void |
setQWForFiles(Writer writer)
|
void |
setRollOnStartup(boolean rollOnStartup)
|
void |
setScavengeInterval(long intervalMillis)
|
void |
setTimeZoneId(String timeZoneId)
|
protected void |
subAppend(LoggingEvent event)
Responsible for executing file rolls as and when required, in addition to delegating to the super class to perform the actual append operation. |
protected void |
writeFooter()
|
protected void |
writeHeader()
|
| Methods inherited from class org.apache.log4j.FileAppender |
|---|
getAppend, getBufferedIO, getBufferSize, getFile, reset, setAppend, setBufferedIO, setBufferSize, setFile, setFile |
| Methods inherited from class org.apache.log4j.WriterAppender |
|---|
append, checkEntryConditions, closeWriter, getEncoding, getImmediateFlush, requiresLayout, setEncoding, setErrorHandler, setImmediateFlush, setWriter, shouldFlush |
| Methods inherited from class org.apache.log4j.AppenderSkeleton |
|---|
addFilter, clearFilters, doAppend, finalize, getErrorHandler, getFilter, getFirstFilter, getLayout, getName, getThreshold, isAsSevereAsThreshold, setLayout, setName, setThreshold |
| Methods inherited from class java.lang.Object |
|---|
clone, getClass, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public TimeAndSizeRollingAppender()
public TimeAndSizeRollingAppender(Layout layout,
String filename)
throws IOException
layout - filename -
IOException
public TimeAndSizeRollingAppender(Layout layout,
String filename,
boolean append)
throws IOException
layout - filename - append -
IOException
public TimeAndSizeRollingAppender(Layout layout,
String filename,
boolean append,
boolean bufferedIO,
int bufferSize)
throws IOException
layout - filename - append - bufferedIO - bufferSize -
IOException| Method Detail |
|---|
public boolean equals(Object other)
equals in class Objectpublic int hashCode()
hashCode in class Objectpublic final void activateOptions()
activateOptions in interface OptionHandleractivateOptions in class FileAppenderpublic final void close()
close in interface Appenderclose in class WriterAppender
public final boolean parseUnrecognizedElement(Element element,
Properties props)
throws Exception
FileRollEventListenerFileCompressionEventListenerLogFileScavengerLoggingTaskExecutorServiceDOMConfigurator.
NB Only one of each element is permitted.
parseUnrecognizedElement in interface UnrecognizedElementHandlerException(org.w3c.dom.Element, java.util.Properties)public String getCompressionAlgorithm()
public boolean getCompressionUseBlockingQueue()
public long getCompressionMaxBlockingInterval()
public int getCompressionMinQueueSize()
public int getCompressionLevel()
public String getDatePattern()
public String getDatePatternLocale()
public boolean getDateRollEnforced()
public String getFileRollEventListener()
public boolean getFlushToStorageOnAppend()
public String getMaxFileSize()
public String getMinFreeDiskSpace()
public int getMaxRollFileCount()
public boolean getRollOnStartup()
public long getScavengeInterval()
public String getTimeZoneId()
public void setCompressionAlgorithm(String compressionAlgorithm)
compressionAlgorithm - "ZIP" or "GZ"public void setCompressionUseBlockingQueue(boolean compressionBlockingQueue)
public void setCompressionMaxBlockingInterval(long compressionInterval)
public void setCompressionLevel(int compressionLevel)
compressionLevel - Deflater.DEFAULT_COMPRESSION,
Deflater.NO_COMPRESSION, or in the range
Deflater.BEST_SPEED to Deflater.BEST_COMPRESSION.Deflaterpublic void setCompressionMinQueueSize(int compressionMinQueueSize)
compressionMinQueueSize - >= 0.public void setDatePattern(String datePattern)
datePattern - in compliance with localized patterns similar to those
specified by SimpleDateFormat. Note that the pattern
characters in the main Javadoc of SimpleDateFormat are
defaults for Locale.ENGLISH, if I understand correctly.SimpleDateFormatpublic void setDatePatternLocale(String datePatternLocale)
Locale to be used when processing date patterns. Variants
are not supported; only language and (optionally) country may be used,
e.g. "en", "en_GB" or "fr_CA" are
all valid. If no locale is supplied, Locale.ENGLISH will be used.
datePatternLocale - Locale,
setDatePattern(String)public void setDateRollEnforced(boolean dateRollEnforced)
dateRollEnforced - When true file rolls will occur pro-actively when the
time boundary is reached, rather than reactively in response to a
logging event.public void setFileRollEventListener(String className)
FileRollEventListeners via XML, using the
"fileRollEventListener" element.
className - The fully qualified name of the class that implements the
FileRollEventListener interface; implementors must be
declared public and have a default constructor.public void setFlushToStorageOnAppend(boolean flushToStorageOnAppend)
FileAppender.setBufferedIO(boolean)and
WriterAppender.setImmediateFlush(boolean) are overridden to
false and true, respectively, upon activation of an
instance of this object.
flushToStorageOnAppend - false by default.public void setLogFileScavenger(String className)
LogFileScavengers via XML, using the
"logFileScavenger" element.
className - The fully qualified name of the class that implements the
LogFileScavenger interface; implementors must be declared
public and have a default constructor.public void setFileRollEventMessage(String message)
message - The message to be appended at the top of each new file created
following a file roll. If the message is empty, a default message
will be appended instead.public void setMaxFileSize(String value)
public void setMinFreeDiskSpace(String value)
value - public void setMaxRollFileCount(int maxRollFileCount)
public void setRollOnStartup(boolean rollOnStartup)
rollOnStartup - true if the appender should roll, and create a new log
file, immediately upon receiving the first logging event after
activation.public void setScavengeInterval(long intervalMillis)
public void setMinFreeDiskSpace(long minFreeDiskSpace)
public void setTimeZoneId(String timeZoneId)
final FileRoller getFileRoller()
final FileRollEventListener getGuestFileRollEventListener()
final FileCompressionEventListener getGuestFileCompressionEventListener()
final LogFileCompressorTask getLogFileCompressor()
final LogFileScavenger getLogFileScavenger()
final LoggingTaskExecutorService getExecutorService()
final AppenderRollingProperties getProperties()
final File getIoFile()
final void openFile()
final void setLogTaskExecutorService(LoggingTaskExecutorService loggingTaskExecutorService)
loggingTaskExecutorService - protected final void closeFile()
closeFile in class FileAppenderFileAppender.closeFile()protected final OutputStreamWriter createWriter(OutputStream os)
createWriter in class WriterAppenderprotected final void setQWForFiles(Writer writer)
setQWForFiles in class FileAppenderprotected final void subAppend(LoggingEvent event)
subAppend in class WriterAppenderWriterAppender.subAppend(org.apache.log4j.spi.LoggingEvent)protected final void writeFooter()
writeFooter in class WriterAppenderprotected final void writeHeader()
writeHeader in class WriterAppender
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||