Function Reference

LOG4SAS_LOGGER Function

Creates a logger.

Category:	Logging
Featured in:	Logging Example Using Functions

Syntax
Arguments
Details
	Logger Names
	Appender Reference and Additivity
	Levels
	Processing Loggers in the DATA Step
See Also

Syntax

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

Arguments

"name"

specifies a name for the logger.

Requirements:	The name must be enclosed in double quotation marks.
Tip:	Requests to create a logger are ignored if they use the name of an existing logger.
Tip:	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

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

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 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. If ADDITIVITY=FALSE, the log event is processed only by the logger.

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