The SAS Logging Facility

Appenders

An appender is a named entity that is referenced by a logger. An appender specifies the destination for the message, specifies how the message is formatted, specifies attributes for the appender class, and provides additional filtering capabilities.

When a log event occurs, the logging facility processes the message by using the appender that is named in the logger's <appender-ref> element in a logging facility configuration file, or in the APPENDER-REF argument of a logger language element in a SAS program.

SAS has several appender classes for processing messages:

appenders to log messages to an operating system console
an IOM server appender to log messages from any IOM server
file appenders for writing log messages to a file on disk
appenders to write to Windows, UNIX, and z/OS operating system logs

For a complete list and description of the SAS server appenders, see SAS Appenders for Server Logging.

You define appenders in the logging configuration file or in a SAS program by using a SAS function, autocall macro, or DATA step component object. An appender definition requires an appender class and name and the required parameters for the appender class. To customize the message, you specify the message layout within the appender definition. In a logging facility configuration file, you can include additional filtering arguments in the appender definition.

Logger definitions in SAS programs can reference appenders that are defined in a SAS program or any of the SAS server appenders.

For more information, see Appender Reference and Creating and Using Appenders in a SAS Program.

XML Elements for Configuring Appenders

General Appender Syntax

In a logging configuration file, the appender has the following general structure:

<appender class="appender-class" name="appender-name">
      [ <param name="parameter-name" value="parameter-value"/>-1
        ... <param name="parameter-name" value="parameter-value"/>-n ]
      [ <layout>
            <param name="Header" value="header-text"/>
            <param name="HeaderPattern" value="conversion-pattern"/>
            <param name="ConversionPattern" value="conversion-pattern"/>
            <param name="Footer" value="footer-text"/>
            <param name="FooterPattern" value="conversion-pattern"/>
            <param name="XMLEscape" value="TRUE | FALSE"/>
         </layout> ]
      [ <filter>
             <filter-definitions>
         </filter> ]
</appender>

The brackets ([ ]) indicate that the element is optional.

Syntax Description:

class="appender-class"

The appender class is a type of appender. The following appender classes can be used in the logging facility:

ARMAppender
ConsoleAppender
FileAppender
FilteringAppender
IOMServerAppender
RollingFileAppender
sLogAppender
UNXFacilityAppender
WindowsEventAppender
ZOSFacilityAppender
ZOSWtoAppender

For more information about logging facility appenders, see Appender Reference.

name="appender-name"

The appender name is a user-specified name for the appender. An appender is associated with a logger when the appender name is specified as the value of the logger's appender-ref attribute.

<param name="parameter-name" value="parameter-value"/>

Most appenders have required parameters for specifying information that is relevant to the appender. Many parameter names are unique for individual appenders. The name= attribute specifies the name of the parameter, and the value= attribute specifies the value for the parameter.

For example, appenders that write messages to a user-specified file use the File parameter, where the value of the File parameter specifies the location and name of the log file.

See Appender Reference for each appender's required parameters.

<layout> <param name="ConversionPattern" value="conversion-pattern"/> <param name="Header" value="literal-string"/> <param name="HeaderPattern" value="conversion-pattern"/> <param name="Footer " value="literal-string"/> <param name="FooterPattern" value="conversion-pattern"/> <param name="XMLEscape" value="true | false"/> </layout>

You use the <layout> elements to specify how messages should be formatted in the log. The conversion pattern is a series of conversion characters that represent the types of data to include in the log. For example, use the conversion characters %d %t %m to include the date, the time, and the message, respectively, in the log.

You can use the Header, HeaderPattern, Footer, and FooterPattern parameters to specify the conversion characters that should appear at the top and the bottom of the log. You can use the XMLEscape parameter to specify whether certain characters (for example, "<") is converted to its entity representation, which in this case would be "<".

For more information, see Formatting Messages.

<filter> <filter-definitions> </filter>

You can use filters to accept or deny messages based on the following:

a character string in the message
a range of message thresholds
a single message threshold
a combination of character string, single message threshold, or a range of message thresholds

For more information, see Filters.

SAS Appenders for Server Logging

The following appenders can be configured as the value of the <appender> "class" attribute in the XML configuration files for SAS servers:

ARMAppender: ARMAppender processes all Application Response Measurement (ARM) messages that are submitted by an external ARM agent or by the SAS ARM agent.
ConsoleAppender: ConsoleAppender writes messages to the UNIX and Windows operating system consoles.
FileAppender: FileAppender writes messages to the specified file in the specified path.
FilteringAppender: FilteringAppender applies specified filters to determine whether events should be passed to a referenced appender. You can specify a layout to be applied to the events before they are passed.
IOMServerAppender: IOMServerAppender commits messages from any IOM server to a volatile runtime cache.
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.
sLogAppender: sLogAppender is a reserved appender. You should not define new instances of this appender.
UNXFacilityAppender: UNXFacilityAppender writes messages to the syslogd logging facility in UNIX operating systems.
WindowsEventAppender: WindowsEventAppender writes messages to the Windows Event log.
ZOSFacilityAppender: ZOSFacilityAppender enables multiple instances of SAS in the z/OS operating system to write messages to a common location.
ZOSWtoAppender: ZOSWtoAppender directs SAS application messages to the z/OS operating system console.

Appenders in the SAS Language

When you specify an appender reference in a logger language element, you can use any of the appenders that are defined for SAS server logging and the appender FileRefAppender.

FileRefAppender is an appender that you create only in the SAS language, and only by using a SAS function, DATA step object, or autocall macro. As the name indicates, FileRefAppender names a fileref that defines a location to store messages. FileRefAppender is the only appender that can be created by using the SAS language.

When you create an appender in a DATA step, the appender is available only for the duration of the DATA step. After the DATA step has run, the appender is no longer available.

For more information, see Creating and Using Appenders in a SAS Program.

Referencing Appenders in a Logger

After an appender is defined, it can be referenced by a logger. To reference an appender in a logging configuration file, you include the appender name in the logger's <appender-ref> element. In the following logger and appender definitions, the appender WinEvntVwr is referenced by the logger WEVLogger:

<appender class="WindowsEventAppender" name="WinEvntVwr">
   <param name="Appname" value="myApp"/>
</appender>

<logger name="WEVLogger">
   <level="error"/>
   <appender-ref ref="WinEvntVwr"/>
</logger>

To reference an appender in a logger language element, you specify the appender name as the value of the APPENDER-REF argument:

%log4sas_logger(myLogger, appender-ref=(myAppender), level=error);

rc= log4sas_logger("myLogger" "appender-ref=(myAppender) level=error";

declare logger logobj("myLogger");
logobj.appenderref="myAppender");

To write the same message in multiple logs, you can specify multiple appender references in a configuration file logger definition:

<logger name="MyLoggers">
   <level="error"/>
   <appender-ref ref="WinEvntVwr"/>
   <appender-ref ref="RollingFileAppender"/>
</logger>

In a SAS program, you can add multiple appender names separated by a space in the APPENDER-REF argument:

%log4sas_logger(myLogger, appender-ref=(myAppender myRollingFile), level=error);

Top of Page