The SAS Logging Facility

Loggers

A logger is a named entity that identifies a message category. A logger's attributes consist of a level and one or more appenders that process the log events for the message category. The level indicates the threshold, or lowest event level, that will be processed for this message category.

Loggers are specified in log events to associate the log event with a message category. By categorizing log events, the logger can write messages of the same category to the same destinations. When a log event occurs, the log event message is processed by the appender that is associated with the logger that is named in the event log if the log event level is the same or higher than the level that is specified for the logger.

Loggers are organized hierarchically and inherit the attributes of their ancestor logger. Hierarchical logger names are separated by a period (.) (for example, Admin.Meta.Security). The root logger is the highest level logger. All loggers inherit the root logger's attributes. The logging configuration file defines several message categories that are immediate descendants of the root logger. These high-level categories, Admin, App, Audit, IOM, and Perf, are used for SAS server logging and can be referenced by log events in SAS programs.

You configure loggers in a logging configuration file for SAS server logging or by using SAS language elements in a DATA step or macro program. If you perform a planned deployment, then the SAS Deployment Wizard provides logging configuration files for your SAS servers. You can dynamically adjust thresholds by using the server management features of SAS Management Console. For more information, see "Administering Logging for SAS Servers" in the SAS Intelligence Platform: System Administration Guide.

For more information, see Logging Thresholds and Appenders.

XML Elements for Configuring Loggers

In a logging configuration file, a logger has the following structure:

<logger name="logger-name">
    <level value=threshold/>
    <appender-ref ref="appender-name"/>
</logger>

Syntax Description:

name="logger-name": specifies the name of a message category name. The logger name is specified in a log event to associate a message with a message category.
<level value="threshold"/>: specifies one of the following levels, from lowest to highest: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. You use the threshold to filter log events. If the log event diagnostic level is the same or higher than the threshold that is specified for the log event's logger, the logging facility continues to process the log event. If the log event diagnostic level is lower than the logger's threshold, the log event is ignored.
<appender-ref ref="appender-name"/>: specifies the name of an appender to record messages for this logger's message category.

Hierarchical Logger Names

The logger architecture enables logger names to be multiple levels so that descendant loggers can inherit thresholds and appender references from their parent loggers, therefore omitting the appender reference and threshold in the descendant logger definition. You separate hierarchical logger names with a period (.).

As an example, suppose that your logging facility configuration file defines the Admin logger with an appender reference value of MyRollingFile and a threshold of Info. A second logger definition, Admin.MyPgm, specifies the logger name and a threshold of Debug. Because no appender reference is specified in Admin.MyPgm, the appender reference is inherited from its parent, the Admin logger. The appender reference MyRollingFile logs messages for Admin log events whose level is INFO or higher, as well as Admin.MyPgm log events whose level is DEBUG or higher.

These loggers might be defined using the following logger elements in the logging configuration file:

<logger name="Admin">
   <level value="Info"/>
   <appender-ref ref="MyRollingFile"/>
</logger>

<logger name="Admin.MyPgm">
   <level value="Debug"/>
</logger>

<root>
   <level value="Error"/>
   <appender-ref ref="SystemRollingFile">
</root>

If a log event specifies a hierarchical logger name that does not exist, the logging facility checks for a parent logger definition. If the parent logger exists, the log event is processed by the parent logger. If a logger definition does not exist for the parent, the root logger processes the log event.

Consider the example logger definitions in this section. If a log event specifies the logger Admin.Special, the logging facility determines that the logger Admin.Special does not exist. The logging facility then checks for the Admin logger. In this case, the Admin logger exists and the log event is processed by the Admin logger. If the Admin logger was not defined, the root logger would process the log event.

SAS Server Logger Names

Log events for SAS servers use a hierarchical logger name where each name in the hierarchy identifies a category such as an operation, a server, and a server operation. For example, log events that specify the Admin.OLAP.Security logger indicate that the message is an OLAP server security message that is intended for a system administrator or computer operator.

SAS server logger names begin with one of the following logger categories:

Admin: processes log events that are relevant to system administrators or computer operators.
App: processes log events that are related to specific applications. For example, metadata servers, OLAP servers, stored process servers, and workspace servers use loggers that are named App.class.interface.method to record method calls that are issued to the server.
Audit: processes log events that are related to user authentication (including accepted and rejected authentication requests) and to security administration (including the administration of users, groups, and access controls).
IOM: processes log events for servers that use the Integrated Object Model (IOM) workspace interface. The IOM interface provides access to Foundation SAS features such as the SAS language, SAS libraries, the server file system, results content, and formatting services. IOM servers include metadata servers, OLAP servers, stored process servers, and workspace servers.
Perf: processes log events that are related to system performance.

The second category in a hierarchical logger name can indicate a type of server or some type of event, such as authentication. In most cases, however, the categories are self-explanatory. The following list gives some examples of server categories for the logging facility.

Logging Facility Server Category	SAS Server
Connect	SAS/CONNECT Server
Meta	SAS Metadata Server
ObjectSpawner	SAS Object Spawner
OLAP	SAS OLAP Server

In most cases, the categories are self-explanatory. Here is a list of some of the loggers that the logging facility uses for SAS servers:

Admin.Operations: processes log events that are related to server operations, such as starting, pausing, and stopping an instance of a workspace server.
Admin.Session: processes log events that are related to starting and stopping batch, windowing, and SAS/CONNECT server sessions.
Audit.Authentication: processes log events for server authentication requests.
App.Program: processes log events that are related to running a program using the SAS language.
IOM: processes log events that are related to client interactions.
IOM.PE: processes log events that are related to packets that are processed by the BRIDGE and COM protocol engines.
Perf.ARM: processes log events that are related to ARM 4.0 transactions.

Loggers in the SAS Language

You create loggers in SAS programs by using the following SAS language elements:

%log4sas_logger( ) autocall macro for macro programming
log4sas_logger function in a DATA step
DCL Logger object constructor in a DATA step

See the following reference documents for information about defining loggers in the SAS language:

If you are writing SAS programs, you can write log events for loggers that are defined in one of the logging configuration files or you can write log events for loggers that you create by using the SAS language.

Loggers that are created by using the SAS language exist for the duration of the SAS session.

Top of Page