Server Logging Configuration

Introduction

The logging facility is a flexible, configurable framework used for collecting, categorizing, and filtering events that are generated by processes and writing events to a variety of output devices. The dfs_log.xml configuration file controls the destination, contents, and formats of the logging facility log for SAS Federation Server. The configuration file specifies options for loggers, appenders, levels, filters, and the layout of log messages. You can change logging levels dynamically without stopping the server.

Initial Logging Configuration

The default logging facility configuration for SAS Federation Server includes a definition for the RollingFileAppender. The appender routes events to a rolling log file.

The rolling log file is configured as follows:

A new log is created when the date changes and when a new server process is started.
Events are written by using a layout that includes the current date, current time, logging level, process ID, the user identity that is associated with the event, and a message.
The name of the rolling log file follows the following convention:
```
dfs_%d_%S{pid}.log
```
where %d is the date and %S{pid} is the process ID number (PID) for SAS Federation Server.
The rolling log files are placed in the /var/logdirectory.
When a new rolling log file is created, a heading is written to the file. The heading identifies the server's host machine, operating system, and server start-up command.

The following table lists the loggers that reference the RollingFileAppender:

Logger Name	Logging Level	Description
Admin	Info	processes log events that are relevant to system administrators or computer operators.
App	Info	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.
App.Server	Info	Server top-level object run-time and interface events.
	Debug	Method call and return events.
	Trace	Method parameters.
App.Session	Info	Session object run-time and interface events.
	Debug	Method call and return events.
	Trace	Method parameters.
App.Connection	Info	Connection object run-time and interface events
	Debug	Method call and return events.
	Trace	Method parameters.
App.Statement	Info	Statement object run-time and interface events
	Debug	Method call and return events.
	Trace	Method parameters.
App.Program	Info	General application independent events including errors and warnings from arbitrary services or the OS
Audit	Info	Processes log events to be used for auditing. These events include updates to public metadata objects, user access to SAS libraries, accepted and rejected user authentication requests, and administration of users, groups, and access controls.
Audit Authentication	Info	Authentication provider events.
Audit Table	Info	Federation server specific events.
Audit Table Connection	Info	Audit events related to server connections, including connection pooling and dynamic connections.
Audit.Table.Security	Info	Federation Server authorization events.
Audit.Table.Security.Provider	Info	Detailed authorization services run-time events relating to user identity management and access control logic and enforcement decisions.
Logging	Error	SAS logging facility configuration and run-time events.
Logging.Appender	Error	Appender-specific configuration and run-time events.
Logging.Appender.DB	Error	DB Appender-specific events (used in SQL Logging).
Cradle	Info	General server process framework services, start-up and termination events.
IOM	Info	Processes log events for servers that use the Integrated Object Model (IOM). 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.
IOM.Proxy	Info	Server to server outcall events.
	Debug	Method call and return events.
	Trace	Method parameters.
IOM.PE	Warn	Communication protocol engine events.
Perf	Error	Processes log events that are related to system performance.
Perf.ARM	Error	Application Response Measurement performance events.
Perf.ARM.IOM.Session	Error	Session API performance events.
Perf.ARM.IOM.Environment	Error	Environment API performance events.
Perf.ARM.IOM.Connection	Error	Connection API performance events.
Perf.ARM.IOM.Statement	Error	Statement API performance events.
Perf.ARM.FederationServer	Warn	Federation server API independent performance events.
Perf.ARM.SQLServices	Warn	Local SQL services performance events.
<root>	Error	All events produced from SAS® Federation Server.

Logging Thresholds

The SAS logging facility provides six thresholds: TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. Thresholds are used to ignore log events that are lower than a particular level, or to filter messages so that only a single message level is logged.

When a log event occurs, up to three levels of filtering can take place:

filtering log events by comparing the log event level to the log event's logger level.
filtering log events by comparing the log event level to the appender's threshold.
filtering log events by comparing the log event level to the threshold that is specified in the filter definition, which is a part of the appender configuration.

In the first two cases, if the log event level is lower than the logger or appender threshold, the logging facility ignores the log event. Otherwise, processing of the log event continues.

In the third case, the log event level is compared to the filter threshold. If there is a match, the log event can be either accepted or denied. If there is no match, the filtering process continues to the next filter in the filtering policy.

The logging levels, from the lowest to the highest, are as follows:

Level	Description
TRACE	Produces the most detailed information about your application. This level is primarily used by SAS Technical Support or development.
DEBUG	Produces detailed information that you use to debug your application. This level is primarily used by SAS Technical Support or development.
INFO	Provides information that highlights the progress of an application.
WARN	Provides messages that identify potentially harmful situations.
ERROR	Provides messages that indicate that errors have occurred. The application might continue to run.
FATAL	Provides messages that indicate that severe errors have occurred. These errors will probably cause the application to end.

Note: The logging level must be enclosed in quotation marks.

By default appenders do not have a threshold but a threshold can be configured. When set, all log events that have a level lower than the threshold are ignored by the appender.

Modifying the Server Logging Configuration

You can modify the logging facility configuration for SAS Federation Server by modifying the dfs_log.xml file located in the /etc directory of the installation path. Before modifying the file, be sure to make a backup copy.

Here are some examples of changes that you might want to make:

configure RollingFileAppender to use a different log filename, to roll over log files more or less frequently, or to roll over log files based on file size rather than date.
specify additional appenders.
use filters to limit the events that are written to an appender.
configure a different message layout for an appender.

Trace Log

By tracing each internal API routine that is called by the application, a trace log records transactions that can be used for debugging connection and processing issues. For example, you can request information that traces the FedSQL statements that are submitted to a data service.

Note: By default, tracing is not activated for server logging. You should not activate tracing unless you are instructed to do so by Technical Support.

Tracing can be activated by using the following methods:

connection string options
server start-up options
data service connection arguments
system options

When you activate tracing, you also specify the physical location where the transaction records are saved. Because SAS Federation Server supports one root file trace log directory and multiple subdirectories, you can group trace logs if necessary.