Appender Reference

FileAppender

FileAppender Overview

FileAppender writes messages to the specified file in the specified path.

FileAppender Syntax

XML Configuration

<filter-definitions>

</filter>

</layout>

</appender>

FileAppender Syntax Description

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

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

Default:	None
Required:	Yes

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
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:	Yes, if path-and-filename-pattern is not specified.
Interaction:	path and filename overwrites any value that you specify for path-and-filename-pattern.

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, system description, or process ID) 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, if path-and-filename is not specified.
Interaction:	path and filename is overwritten by any value that you specify for path-and-filename.

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.

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 in the configuration file 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.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.

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, 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
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

FileAppender Examples

Example 1: 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>

FileAppender Usage and Best Practices

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

Top of Page