FileAppender

Writes messages to the specified file in the specified path.

Valid in:

XML configuration

Table of Contents

Syntax

<filter-definitions>

</filter>

</layout>

</appender>

Syntax Description

class="FileAppender" name="appender-name"

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

Default	None
Requirement	This element is required.

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

controls how messages are written 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 name=" Unique" .

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

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	d Conversion Character

%S{key}

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

See	S Conversion Character

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

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 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 in the configuration file for Base SAS.
Default	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

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	No
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.log is specified in path-and-filename. If the files Events.log and Events.log_0 already exist, then the next log file that is created is named Events.log_1.

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, messages are logged as follows:
	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 FALSE and Append is set to TRUE, then messages are appended to the end of the existing file.
	If Unique is set to FALSE and Append is set to FALSE, then the contents of the existing file are erased and overwritten with new messages.

filter-definitions

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

Default	None
Requirement	No
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	No
See	Pattern Layouts

Details

FileAppender writes messages to the specified file in the specified path. When you create an instance of FileAppender, you can specify the following:

how messages are written if the file already exists when logging begins. Messages can be appended to the end of the existing file, they can overwrite the existing file contents, or they can be written to a new file that has a unique name.
whether to write messages immediately upon receipt or to hold them in a buffer.
the minimum (threshold) event level to be logged.
the locale and encoding to be used when writing to the file.
a conversion pattern to be used for creating the filename.

The following best practices apply to FileAppender:

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}).

Example: Appending Messages to a File

The following instance of FileAppender writes messages to a file called Events.log. If the file already exists when logging begins, messages are appended to the end of the file.

<appender class="FileAppender" name="File">
   <param name="File" value="c:\logs\Events.log"/>  
   <param name="Append" value="true"/>
   <param name="ImmediateFlush" value="true"/>      
   <layout>
      <param name="ConversionPattern" value="%d %-5p [%t] %u - %m"/>
   </layout>
</appender>