Appender Reference

RollingFileAppender

RollingFileAppender writes messages to the specified file in the specified path, and begins writing messages to a new file that has a different name when specified criteria are met. For example, messages can roll over to a new file every hour, every day, when the file grows to a specified size, or when filtering criteria are met.

RollingFileAppender Syntax

XML Configuration

<filter-definitions>

</filter>

</layout>

<rollingPolicy-parameters>

</rollingPolicy>

<triggeringPolicy-parameters>

</triggeringPolicy>

</appender>

RollingFileAppender Syntax Description

class="RollingFileAppender" name="appender-name"

specifies the user-assigned name for this instance of RollingFileAppender.

Default:	None
Required:	Yes

name="Append" value="TRUE | FALSE"

controls how messages are committed to the log file if the file already exists when logging begins. Specify one of the following values:

TRUE	appends new messages to the end of the existing file.
FALSE	erases the contents of the existing file and overwrites them with new messages.

Default:	TRUE
Required:	No
Interaction:	If both the Unique parameter and the Append parameter are specified, then the Unique parameter takes precedence. For details, see the Unique parameter.

name="Encoding" value="encoding-value"

specifies the encoding that is used to write messages to the file.

Default:	The encoding setting that is in effect for the SAS session. For example, the ENCODING system option might be specified in the configuration file for a SAS server or for Base SAS. If the ENCODING system option is not specified for the SAS session, then the defaults that are described in the SAS National Language Support (NLS): Reference Guide are used. For logging processes that run outside a SAS session (for example, logging for the SAS Object Spawner), the default is the encoding that is specified in the operating system settings.
Required:	No
See:	SAS National Language Support (NLS): Reference Guide

name="File" value="path-and-filename"

specifies the path and filename of the file to which messages are written.

Default:	None
Required:	No
Interaction:	This filename overwrites any value that you specify for path-and-filename-pattern in a RollingPolicy or TriggeringPolicy configuration.

name="ImmediateFlush" value="TRUE | FALSE"

determines whether messages are written to the file immediately or held in a buffer. Specify one of the following values:

TRUE	writes messages to the file immediately as they are received.
FALSE	holds messages in a buffer and writes them to the file when the buffer is full. The default buffer size is 16 KB.

Required:	No
Default:	TRUE

name="Locale" value="locale"

specifies the locale that is used to write messages to the file.

Required:	No
Default:	The locale setting that is in effect for the SAS session. For example, the LOCALE system option might be specified in the configuration file for a SAS server or for Base SAS. For logging processes that run outside a SAS session (for example, logging for the SAS Object Spawner), the default is the locale that is specified in the operating system settings.
See:	SAS National Language Support (NLS): Reference Guide

specifies the lowest event level that this appender processes. Events that are below the specified level are ignored. The valid values are listed here from lowest to highest.

Required:	No
Default:	None
See:	Logging Thresholds

name="Unique" value="TRUE | FALSE"

creates a new file, with an underscore and a unique number appended to the filename, if the log file already exists when logging begins. Numbers are assigned sequentially from 0 to 32766.

For example, suppose Events_%d.log is specified in path-and-filename-pattern for TimeBasedRollingPolicy. If the current date is August 3, 2008, and a file already exists that has the name Events_20080803.log, then the next log file that is created is named Events_20080803_0.log. If a file already exists that has the name Events_20080803_0.log, then the next log file that is created is named Events_20080803_1.log.

Required:	No
Default:	FALSE
Interaction:	If both the Unique parameter and the Append parameter are specified, then the Unique parameter takes precedence. If the log file already exists when logging begins, and if Unique is set to TRUE and Append is set to either TRUE or FALSE, then messages are written to a new file with a unique number appended to the filename. If Unique is set to TRUE and FixedWindowRollingPolicy is specified, then a complete set of unique files is created when logging begins. For details, see the Interaction description for FixedWindowRollingPolicy.

filter-definitions

specifies the names and associated parameters of filters that limit the messages that are logged by this appender.

Default:	None
Required:	No
Main discussion:	Filters

name="ConversionPattern" value="conversion-pattern"

specifies how the log message is written to the log.

Required:	No
Default:	None. If a conversion pattern is not specified, then the log event produces an empty string.
Main discussion:	Pattern Layout

rollingPolicy class="FixedWindowRollingPolicy | TimeBasedRollingPolicy"

specifies the policy that controls the creation of new log files and filenames when messages roll over to a new file. SAS provides the following instances of rollingPolicy:

FixedWindowRollingPolicy

specifies a fixed set of filenames that include sequentially assigned index numbers. To specify when log files roll over, specify either SizeBasedTriggeringPolicy or FilterBasedTriggeringPolicy in the TriggeringPolicy parameter. When the specified criteria are met, the log files are rolled over as follows:

The appender renames each existing log file by incrementing the index number in the filename by 1. For example, Events03.log is renamed to Events04.log, Events02.log is renamed to Events03.log, and Events01.log is renamed to Events02.log.
If a file already exists that has a filename that includes maximum-index, then the messages in that file are overwritten. For example, if Events04.log already exists when rollover occurs, and if 4 is specified in maximum-index, then the contents of Events04.log are replaced with the contents of Events03.log.
The appender creates a new file with minimum-index in the filename (for example, Events01.log), and subsequent messages are written to that file.

Use the following syntax to specify FixedWindowRollingPolicy:

</rollingPolicy>

name="fileNamePattern" value="path-and-filename-pattern"

specifies the path to which the log file is written and the conversion pattern that is used to create the log filename when messages roll over to a new file. The conversion pattern can include the following characters:

%i

indicates where the index number is to appear. The index number is incremented by 1 each time a new file is created.

%S{key}

indicates where system information (such as the host name, operating system, or system description) appears. You must specify a key to indicate the type of system information that appears.

Main discussion:

Conversion Characters

For example, specify c:\logs\MetadataServer_S{host_name}_%i.log if you want the log files to be written to the path c:\logs\ and if you want the files to be named MetadataServer_host-name_01.log, MetadataServer_host-name_02.log, and so on.

Default:	None
Required:	No
Interaction:	path and filename is overwritten by any value that you specify for path-and-filename.

name="maxIndex" value="maximum-index"

specifies an integer that is the highest number to be used as an index in the log filename. For example, if you set minimum-index to 1 and maximum-index to 10, the appender creates a maximum of ten log files. When the maximum has been reached, the appender overwrites the most recently created file.

Range:	1 - 14
Required:	No
Default:	7
Interaction:	If maximum-index is equal to minimum-index, then only one file is created.

name="minIndex" value="minimum-index"

specifies an integer that is the beginning number to be used as an index in the log filename. For example, if you set minimum-index to 3, the name of the first log file that is created will contain the characters 03 in the position that is specified by %i in the filename pattern.

Acceptable values:	Any integer from 1 to 14
Required:	No
Default:	1

Interaction:

If Unique is set to TRUE and FixedWindowRollingPolicy is specified, then a complete set of fixed window files is created when logging begins. If one or more sets of fixed window files already exist when logging begins, then a new set of fixed window files is created that has an underscore character and a unique number appended to each filename.

For example, if Unique is set to TRUE and FixedWindowRollingPolicy is specified with a filename pattern of Events%i.log, a minimum-index of 1, and a maximum-index of 4, then log files are created as follows:

When logging first begins, the following empty files are created: Events01.log, Events02.log, Events03.log, and Events04.log. Messages are written to Events01.log and are rolled over to the other files in the group as specified by the triggering policy.
The next time logging begins, the following set of files is created and written to: Events01_0.log, Events02_0.log, Events03_0.log, and Events04_0.log.
Each subsequent time that logging begins, a new set of files is created with a new unique suffix (for example, _1, _2, _3).

TimeBasedRollingPolicy

specifies the use of a log filename that contains the current date. You do not need to specify a value for triggeringPolicy when you use this policy. To specify when a new log file is created, you can specify either of the following options:

Creation of (rollover to) a new log file whenever the generated filename differs from the current filename. This is the default behavior.

For example, if the filename includes the current year, month, and day, then a new file is created when the system date changes to a new day.
Creation of a new log file only when a new session begins.

When rollover occurs, the message Log continues in path-and-filename is written to the end of the current file. The message Log continued from path-and-filename is written to the beginning of the newly created file.

Use the following syntax to specify TimeBasedRollingPolicy:

</rollingPolicy>

name="fileNamePattern" value="path-and-filename-pattern"

specifies the path to which the log file is written and the conversion pattern that is used to create the log filename. The conversion pattern can include the following characters:

%d

indicates where the current date appears. You can specify a date format or a date and time pattern in braces after %d if you want the date to appear in a format other than yyyymmdd, or if you want to include additional information such as the hour.

Main discussion:

Conversion Characters

%S{key}

indicates where system information (such as the host name, operating system, or system description) appears. You must specify a key to indicate the type of system information that appears.

Main discussion:

Conversion Characters

For example, specify c:\logs\MetadataServer_%d_%S{host_name}.log if you want the log files to be written to the path c:\logs\ and the filename to include the current date and the name of the metadata server host machine.

Default:	None
Required:	Yes
Interaction:	path and filename is overwritten by any value that you specify for path-and-filename.

name="rollOver" value="TRUE | FALSE"

indicates whether a new log file is created whenever the generated filename differs from the current filename. Specify one of the following values:

TRUE: creates (rolls over to) a new file whenever the generated filename differs from the current filename.
FALSE: creates a new log file only when a new session begins.

Default:	TRUE
Required:	No

triggeringPolicy class="SizeBasedTriggeringPolicy | FilterBasedTriggeringPolicy"

specifies the policy that determines when a new log file is created. SAS provides the following instances of triggeringPolicy:

SizeBasedTriggeringPolicy

specifies the creation of a new log file when the number of bytes in the current log file is greater than or equal to the specified maximum-file-size. Along with this policy, specify FixedWindowRollingPolicy in the RollingPolicy parameter to control how new log filenames are assigned and the number of files that are created.

Use the following syntax to specify SizeBasedTriggeringPolicy:

</triggeringPolicy>

name="MaxFileSize" value ="maximum-file-size": specifies the maximum size, in bytes, of the log file. When the log file reaches this size, messages roll over to a new file. You can use the suffix KB (for kilobytes), MB (for megabytes), or GB (for gigabytes) when you are specifying the size. For example, 10KB is interpreted as 10240 bytes.

FilterBasedTriggeringPolicy

specifies the creation of a new log file when a log event is received that meets the specified filtering criteria. Along with this policy, specify FixedWindowRollingPolicy in the RollingPolicy parameter to control how new log filenames are assigned and the number of files that are created.

Use the following syntax to specify FilterBasedTriggeringPolicy:

<filter-definitions>

</param>

</triggeringPolicy>

filter-definitions

specifies the filters that are used to trigger rollover to a new log file.

Main discussion:

Filters

RollingFileAppender Configuration Examples

Example 1: Roll Over to a New Log File Every Day

This RollingFileAppender configuration writes messages to a log file whose name contains the current date (for example, MetadataServer_20080301.log). When the system date changes, messages roll over to a new log file whose name contains the new date (for example, MetadataServer_20080302.log).

<appender class="RollingFileAppender" name="TimeBasedRollingFile">
   <param name="Append" value="true"/>
   <param name="ImmediateFlush" value="true"/>      
   <rollingPolicy class="TimeBasedRollingPolicy">
      <param name="fileNamePattern" value="c:\logs\MetadataServer_%d.log"/>
   </rollingPolicy>
   <layout>
      <param name="ConversionPattern" value="%d %-5p [%t] %u - %m"/>
   </layout>
</appender>

Example 2: Roll Over to a New Log When a New Session Begins

This RollingFileAppender configuration writes messages to a log file whose name contains the current date (for example, MetadataServer_20080301.log). When a new session begins, messages roll over to a new log file whose name contains the current date (for example, MetadataServer_20080302.log).

<appender class="RollingFileAppender" name="TimeBasedRollingFile">
   <param name="Append" value="true"/>
   <param name="ImmediateFlush" value="true"/>      
   <rollingPolicy class="TimeBasedRollingPolicy">
      <param name="fileNamePattern" value="c:\logs\MetadataServer_%d.log"/>
      <param name="rollOver" value="false"/>
   </rollingPolicy>
   <layout>
      <param name="ConversionPattern" value="%d %-5p [%t] %u - %m"/>
   </layout>
</appender>

Example 3: Roll Over to a New Log File When the File Reaches a Specified Size

In this example, RollingFileAppender writes messages to a log file whose name contains an index number. The first file that is created is called MetadataServer_01.log. When the size of MetadataServer_01.log is greater than or equal to 100 KB, the file is renamed to MetadataServer_02.log, and subsequent messages are written to a newly created instance of MetadataServer_01.log.

The next time MetadataServer_01.log reaches or exceeds 100 KB, MetadataServer_02.log is renamed to MetadataServer_03.log, MetadataServer_01.log is renamed to MetadataServer_02.log, and subsequent messages are written to a newly created instance of MetadataServer_01.log.

Rollover continues until nine files have been created, at which point the contents of MetadataServer_09.log are overwritten when rollover occurs.

<!-- Rolling log file based on log file size -->
<appender class="RollingFileAppender" name="FixedWindowRollingFile">
   <param name="Append" value="true"/>
   <param name="ImmediateFlush" value="true"/>      
   <rollingPolicy class="FixedWindowRollingPolicy">
      <param name="fileNamePattern" value="c:\logs\MetadataServ_%i.log"/>
      <param name="minIndex" value="1"/>
      <param name="maxIndex" value="9"/>
   </rollingPolicy>
   <triggeringPolicy class="SizeBasedTriggeringPolicy">
      <param name="MaxFileSize" value="100KB"/>
   </triggeringPolicy>
   <layout>
      <param name="ConversionPattern" value="%d %-5p [%t] %u - %m"/>
   </layout>
</appender>

RollingFileAppender Usage and Best Practices

You can configure an instance of RollingFileAppender to do the following:

roll over to a new log file when the system date or time changes (for example, every day or every hour)
roll over to a new log file when a new session begins
roll over to a new log file when the file reaches a specified size
roll over to a new log file when log events match the specified filtering criteria

In addition, RollingFileAppender provides all of the functionality of FileAppender.

Note: On OpenVMS systems, uppercase letters are used in the filename for the first log file that is created. When logging rolls over to a new file, the filename is formed, using the case that is specified in the File parameter of the appender configuration. [cautionend]

The following best practices apply to RollingFileAppender:

Use of the Unique parameter is recommended to avoid overwriting log files. However, if numerous files are created that have the same root filename and different numerical suffixes, then the system must perform multiple comparisons to determine a unique number. To conserve system resources, consider specifying a path-and-filename-pattern that includes a unique identifier such as process ID (%S{pid}).

Top of Page