Appenders

Appender Overview

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
an appender to write messages to a message queue

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 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
DBAppender
FileAppender
FilteringAppender
IOMServerAppender
JavaAppender
JMSAppender
RollingFileAppender
sLogAppender
UNXFacilityAppender
WindowsEventAppender
ZOSFacilityAppender
ZOSWtoAppender

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 and time, the thread identifier, and the message, respectively, in the log.

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

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

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.

DBAppender

DBAppender writes log events to a SAS table or to a table in a third-party DBMS.

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 run-time cache.

JavaAppender

JavaAppender sends messages to a custom Java class.

JMSAppender

JMSAppender sends messages to a message queue by using the Java Message Server (JMS) interface.

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);