DECLARE Statement, Logger Object

Declares a logger object; creates an instance of a logger object and initializes data for a logger object.

Valid in:	DATA step
Category:	Action
Type:	Executable
Alias:	DCL

Table of Contents

Syntax

DECLARE LOGGER logger-object ("logger-name" <, ADDITIVITY: TRUE | FALSE>
<, LEVEL: "level">
<, APPENDERREF:" appender-name"<…, APPENDERREF: "appender-name">> );

Required Arguments

logger-object: specifies the name of the logger object.

logger-name

specifies the name of the logger to which the specified options are applied.

Requirement	The name must be enclosed in double quotation marks.
Tip	You can specify the root logger by setting name equal to either 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.

ADDITIVITY: "TRUE | FALSE"

specifies whether to pass a log event only to the appender that is associated with the logger or to all the appenders in the logger's hierarchy.

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.
Tip	You can also specify this optional argument by using the ADDITIVITY Attribute after the logger instance has been created.

APPENDERREF: "appender-name"

specifies the name of the appender to which log events are passed.

Requirement	The appender name must already exist. Appender names are created by using the DECLARE Statement, Appender Object or are defined in a logging configuration file.
Interaction	If the ADDITIVITY argument is set to TRUE, the log events are also passed to all the appenders that are associated with the logger's hierarchy.
Tips	You can specify more than one appender for each logger.
Tips	You can also specify this optional argument by using the APPENDERREF attribute after the logger instance has been created. For more information, see APPENDERREF Attribute.
See	DECLARE Statement, Appender Object

LEVEL: "level"

specifies the level at which a logging request is applied for the specified logger object. Valid values 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.
Requirement	The level must be enclosed in double quotation marks.
Tip	You can also specify this optional argument by using the LEVEL Attribute after the logger instance has been created.

Details

Logger Names

A logger instance is said to be an ancestor of another logger instance if the logger instance name, followed by a dot, is the prefix of the other logger.

In the following example, IOM is the parent logger, IOM is an ancestor of the APP logger, and both IOM and IOM.APP are ancestors of the WORKSPACE logger.

logobj.name="IOM";
logobj.name="IOM.APP";
logobj.name="IOM.APP.WORKSPACE";

The hierarchical organization of loggers enables them to inherit log event levels and appenders from their ancestors.

Additivity

By default, each log event is passed to the appenders that are associated with the logger and to the appenders that are associated with 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 Iom.App.Workspace, the log message is also directed to the appenders that are referenced in the Iom.App and Iom loggers. If ADDITIVITY=FALSE, the log message is directed only to the appenders that are referenced by Iom.App.Workspace.

Levels

A logging request is applied if its level is greater than the level of the logger. Otherwise, the logging request is ignored. Loggers that do not have an explicitly assigned level inherit their level from the hierarchy. For more information about the logging levels, see Logging Thresholds.

Example

The following example creates a logger object, logobj.

data _null_;
   if _n_ = 1 then do;
      declare appender appobj("myappd", "FileRefAppender", "fileref=myfref");
      appobj.threshold="trace";
      declare logger logobj("mylog");
      logobj.appenderref="myappd";
   end;
   logobj.level="trace";
   logobj.debug("Test debug message");
   logobj.level="info";
   logobj.info("Test info message");
run;