RollingFileAppender

Syntax Description

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

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

Default	None
Requirement	These attributes are required.

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
Requirement	This parameter is not required.
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.
Requirement	This parameter is not required.
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
Requirement	This parameter is not required.
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.

Default	FALSE
Requirement	This parameter is not required.

name="Locale" value="locale"

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

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.
Requirement	This parameter is not required.
See	SAS National Language Support (NLS): Reference Guide

name="Threshold" value="TRACE | DEBUG | INFO | WARN | ERROR | FATAL"

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.

Default	None
Requirement	This parameter is not required.
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.

Default	FALSE
Requirement	This parameter is not required.
Interactions	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 for FixedWindowRollingPolicy

filter-definitions

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

Default	None
Requirement	filter-definitions are not required.
See	Filters

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

specifies how the log message is written to the log.

Default	None. If a conversion pattern is not specified, then the log event produces an empty string.
Requirement	This parameter is not required.
See	Pattern Layouts

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
• TimeBasedRollingPolicy

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 class="FixedWindowRollingPolicy">

<param name="FileNamePattern" value="path-and-filename-pattern"/>

<param name="maxIndex" value="maximum-index"/>

<param name="minIndex" value="minimum-index"/>

</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.

See	S Conversion Character

Default	None
Requirement	This parameter is not required.
Interaction	If both the File parameter and the FileNamePattern parameter are specified, then the File parameter takes precedence.
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.

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.

Default	7
Range	1–14
Requirement	This parameter is not required.
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.

Default	1
Range	1–14
Requirement	This parameter is not required.

Interactions	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 class="TimeBasedRollingPolicy">

<param name="FileNamePattern" value="filename-pattern"/>

<param name="rollOver" value="TRUE | FALSE"/>

</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 yyyy-mm-dd, or if you want to include additional information such as the hour.

See	Pattern Layouts

%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.

See	S Conversion Character

Default	None
Requirement	This parameter is required.
Interaction	If both the File parameter and the FileNamePattern parameter are specified, then the File parameter takes precedence.
Example	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.

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
Requirement	This argument is not required.

triggeringPolicy class="SizeBasedTriggeringPolicy | FilterBasedTriggeringPolicy"

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

• SizeBasedTriggeringPolicy
• FilterBasedTriggeringPolicy

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 class="SizeBasedTriggeringPolicy">

<param name="MaxFileSize" value ="maximum-file-size">

</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:

<triggeringPolicy class="FilterBasedTriggeringPolicy">

<param name="Filters">

<filter-definitions>

</param>

</triggeringPolicy>

filter-definitions

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

See

Filters