LOG4SAS_LOGGER Function

Creates a logger.

Category:	Logging
Example:	Logging Example Using Functions

Table of Contents

Syntax

LOG4SAS_LOGGER("name", <"options"> )

Required Arguments

"name"

specifies a name for the logger.

Requirement	The name must be enclosed in double quotation marks.
Tips	Requests to create a logger are ignored if they use the name of an existing logger.
Tips	You can specify the root logger by setting name equal to either two double quotation marks with no space between them (" "), or to "root". If you specify the root logger, these settings are in effect only during the lifespan of the DATA step. Root settings before and after the DATA step are based on the logging configuration file.
Example	App.Security

"options"

specify one or more of the following options for this logger:

ADDITIVITY=(TRUE | FALSE)

specifies whether to pass a log event to only the appender that is associated with the logger or to all of the appenders in the logger's hierarchy. TRUE specifies to send a log event to all of the appenders in the logger's hierarchy. FALSE specifies to send a log event to only the appenders that are referenced by the APPENDER-REF= option.

Default	TRUE
Restriction	ADDITIVITY can be modified for a logger only if the logger’s IMMUTABILITY option in the logging configuration file is set to FALSE. If you cannot modify a logger’s ADDITIVITY option, contact your system administrator.

APPENDER-REF=(appender_name_list)

specifies one or more appender names to which log events for the logger are passed. Separate the appender names with a space or a comma.

Requirement	An appender must be defined in a SAS program before it can be used in appender_name_list.
Tip	If the value of ADDITIVITY is TRUE, then the log events are processed by appenders that are found in the logger's hierarchy.

LEVEL=level

specifies the ranking, or level, of a log event message that the logger processes. The logger processes log events whose level is the same as or greater than level. The levels, from the lowest level to the highest level are TRACE, DEBUG, INFO, WARN, ERROR, and FATAL.

Restriction

LEVEL can be modified for a logger only if the logger’s IMMUTABILITY option in the logger configuration file is set to FALSE. If you cannot modify a logger’s LEVEL option, contact your system administrator.

Details

Logger Names

The logger name associates a logger with a log message. You can send log messages to be processed by a logger by specifying the logger name as the name argument in the LOG4SAS_LOGEVENT function.

A logger is an ancestor of another logger if the logger name, followed by a dot, is the prefix of the other logger. The following names are logger names:

Testing
Testing.MyProg
Testing.MyProg.TraceMsgs

Testing is the parent logger and the ancestor of the loggers MyProg and TraceMsgs. MyProg is the ancestor of TraceMsgs. The logger Testing.MyProg.TraceMsgs provides a message category that can be used to log trace messages when you are testing the program MyProg.

The hierarchical organization of loggers enables loggers to inherit levels and appenders from their ancestors. For information about configuring loggers in a hierarchy, see Hierarchical Logger Names.

Appender Reference and Additivity

The appenders that are in appender_name_list must be defined by using the LOG4SAS_APPENDER function or in a logging configuration file before the LOG4SAS_LOGGER function executes.

By default, each log event is passed to the appenders that are referenced by the logger and to the appenders that are referenced by loggers in the logger's hierarchy. This is the meaning of the term appender additivity.

For example, by default, when a log event is processed by the logger Testing.MyProg.TraceMsgs, the log message is also directed to the appenders that are referenced in the Testing.MyProg and Testing loggers. If ADDITIVITY=FALSE, the log message is directed to only the appenders that are referenced by Testing.MyProg.TraceMsgs.

Levels

A log event is applied if the level of the log event is the same or greater than the level of the logger. If the level of the log event is lower than the level of the logger, then the log event is discarded. For more information about levels, see Logging Thresholds.

If a logger does not define a level, the logger inherits the level from the next highest ancestor that has an assigned level.

Processing Loggers in the DATA Step

A logger needs to be created only one time for each DATA step. Because the DATA step uses the implicit loop to process observations in a data set, you can use the automatic variable _N_ in an IF statement to process the LOG4SAS_LOGGER function during the first DATA step iteration:

if _n_ = 1 then 
   do;
      rc=log4sas_logger("myLoggerName", "appender-ref=(functionAppender) level=info");
      if rc ne 0 then do;
         msg = sysmsg();
         put msg;
         ABORT;
         end;
   end;