Creating Loggers in a SAS Program

You create loggers in your SAS program by using either the %LOG4SAS_LOGGER autocall macro, the LOG4SAS_LOGGER function, or the logger object DECLARE statement. Loggers must be created after you define appenders and before you invoke log events.

A named logger can be created only once. In order to prevent the DATA step from processing the creation of the same logger in each iteration of the implicit loop, you can create a logger in only the first iteration of the implicit loop by using an IF-THEN statement:

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

When you create a logger, you specify the logger name and optional arguments for the message threshold and for one or more appender references. The logger name is case sensitive and can be a one-level or multiple-level name. The LEVEL argument specifies the message threshold that the logger processes. The logger-level threshold is the first level of message filtering. If a log event threshold is the same or greater than the logger threshold, the logger accepts the log event and the logging facility uses the appender arguments to process the log event. The thresholds, from lowest to highest, are TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. Loggers can be associated with one or more appenders by specifying appender names in the APPENDER-REF argument. You separate appender names with a space and enclose the appender names in parentheses.

A logger is defined for the duration of the SAS session. For information about loggers, see the following topics:

You can update a logger's attributes by using one of the language elements that creates loggers. To update logger attributes, you specify the logger creation language element by using the name of a logger that already exists and the new attributes. SAS updates the attributes of the logger with the new attributes.

When you create a logger in the SAS language, you create a category for messages that are logging messages. The message category is user-specified and is meaningful in your environment for the types of messages that you want to log. For example, if you are testing an existing SAS program where you have added new functionality, you might want messages in preexisting code to be logged as regression messages. Log messages for new code could be logged as new feature messages. Other logger categories might include department names, SAS program names, or analytical model names. For an example of logger category definitions, see Example of Creating Logger and Appender Categories.

Message categories that you create in the SAS language differ from the types of message categories for SAS servers in that the SAS language message categories are user-defined, and the SAS server message categories are defined by SAS.

You can create message categories in a hierarchy where the hierarchy levels are separated by a . (period). Here are examples: IT, IT.Pgm1, and IT.Pgm2. The attributes that are defined in the higher-level logger can be used by lower-level loggers when the lower-level logger does not define an attribute. For example, you could create a high-level logger IT for your IT department. The logger IT specifies the level as INFO. Loggers IT.Pgm1 and IT.Pgm2 do not specify a level attribute. Therefore, they inherit the level of the next highest logger, which in this case is IT. Because the logger IT specifies the level as INFO, when a log event specifies the IT.Pgm1 or IT.Pgm2 logger, the logger level INFO is compared to the log event message level. The logger definitions in this scenario might look like the following functions:

/* Create the context for logging regression messages.  */
/* Regression log events of level info or higher are written  * /
/* to the destination, specified by the appender to be defined as ITPgmRegression.  */
 
if _n_=1 then 
   do;
      rc=log4sas_logger("IT", "appender-ref=(ITPgmRegression) level=info");
      if rc ne 0 then do
         msg = sysmsg();
         put msg;
         ABORT;
         end;
   end;

 

/* Create the context for Pgm1 in the IT department.  */
/* Do not specify a level; use the IT logger level.  */

if _n_=1 then 
   do;
      rc=log4sas_logger("IT.Pgm1", "appender-ref=(ITPgm1Regression)");
      if rc ne 0 then do
         msg = sysmsg();
         put msg;
         ABORT;
         end;
   end;

/* Create the context for Pgm2 in the IT department.  */
/* Do not specify a level; use the IT logger level.  */
 
if _n_=1 then 
   do;
      rc=log4sas_logger("IT.Pgm2", "appender-ref=(ITPgm2Regression)");
      if rc ne 0 then do
         msg = sysmsg();
         put msg;
         ABORT;
         end;
   end;