Administering Logging for SAS Web Applications :: SAS(R) 9.3 Intelligence Platform: Middle-Tier Administration Guide, Third Edition

Logging for SAS Web Applications

The SAS Web applications use log4j to perform logging. As each Web application begins running, the log4j configuration file for the Web application is read from SAS-config-dir\Lev1\Web\Common\LogConfig. After the log4j configuration file is read, the Web applications that permit dynamic logging changes check for modifications that were set with the SAS Web Administration Console.

The following table identifies if customizations can be performed by editing the log4j configuration file, using the SAS Web Administration Console, or both:

Task	Log4j Configuration File	SAS Web Administration Console
Change the logging levels.	Yes	Yes
Add a logging category.	Yes	Yes
Changes persist after Web application server restarts.	Yes	No
Add or change an appender to log to console, file, socket, or ARM.	Yes	No
Change a log filename or location.	Yes	No
Change the layout pattern for the log message.	Yes	No
Track user logons. You can monitor usage patterns by logging activity for SAS Web application logons.	Yes	No

For information about the log4j configuration file, see http://logging.apache.org/log4j/index.html and http://logging.apache.org/log4j/1.2/manual.html.

Logging categories use the fully qualified class name of the class where the logging message originates. Categories for the following classes are common to all SAS Web applications:

com.sas
com.sas.services
com.sas.services.deployment
com.sas.services.discovery
com.sas.services.util

Tip

To troubleshoot SAS Logon Manager authentication, set the com.sas.svcs.authentication context to DEBUG level for SAS WIP Services. Set the com.sas.services.user context to DEBUG level for SAS Remote Services. You must restart SAS Remote Services and the Web application server.

Change the Location of the Log Files

To modify the location of a log file, follow these steps:

Change directory to SAS-config-dir\Lev1\Web\Common\LogConfig and edit the log4j file for the application to modify.
Locate the file appender and modify the value of the file parameter:
```
<appender 
        class="org.apache.log4j.FileAppender"
        name="SAS_FILE">
    <param
        name="append"
        value="true"/>
    <param
        name="file"
        value="C:/SAS/Config/Lev1/Web/Logs/SASLogon9.3.log"/>
    <layout
        class="com.sas.svcs.logging.CustomPatternLayout">
            <param
                name="ConversionPattern"
                value="%d [%t] %-5p [%u] %c - %m%n"/>
    </layout>
</appender>
```
Tip
The CustomPatternLayout that is provided by SAS accepts the log4j conversion characters and two conversion characters that are added by SAS. The %u conversion character is used to report the client identity that is in the security context. The %s conversion character is used to report the session identifier that is in the security context. The log4j conversion characters are described at http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html.
Restart the Web application so that it uses the new configuration.

Change the Logging Levels

Logging Level Descriptions

The log4j file has five levels of detail: DEBUG, INFO, WARN, ERROR, and FATAL. Enabling a level also enables the less detailed levels above the selected level. The default level is set to WARN, which means that WARN, ERROR, and FATAL messages are recorded. In large-scale deployments, the size of the log file can grow rapidly when INFO messages are enabled. However, you might want to enable the INFO messages during the development and testing phases.

CAUTION:

Excessive logging can degrade performance. Therefore, you should not use the DEBUG level unless you are directed to do so by SAS Technical Support.

If you need to debug a problem, it is recommended that you dynamically change the log output temporarily.

Here is a brief description of each level:

DEBUG

displays the informational events that are most useful for debugging an application.

INFO

displays informational messages that highlight the progress of the application.

WARN

displays potentially harmful situations.

ERROR

displays error events that might allow the application to continue to run.

FATAL

displays very severe error events that might cause the application to end abnormally.

Using log4j Files

To modify the logging level by editing a log4j configuration file, follow these steps:

Change directory to SAS-config-dir\Lev1\Web\Common\LogConfig and edit the log4j file for the application to modify.

Locate the category for the class that you want to modify and modify the value of the priority parameter:

<category
        additivity="false"
        name="com.sas.workflow">
    <priority
            value="WARN"/>
    <appender-ref
            ref="SAS_CONSOLE"/>
    <appender-ref
            ref="SAS_FILE"/>
</category>

Restart the Web application so that it uses the new configuration.

Using SAS Web Administration Console

Note: Changing the logging level with the SAS Web Administration Console is supported by some of the SAS Web applications.

Log on to SAS Web Administration Console.
Expand Application Management and then select the Web application.
Expand the Logging section.
Select the radio button for the class and logging level that you want to change.
Click Submit Changes. The change takes effect immediately. You do not need to restart the Web application.

Understanding How the Web Applications Provide a Logging Context

The SAS Web Infrastructure Platform implements a framework that provides separate logging contexts for the individual SAS Web applications. It is useful to understand how SAS implements individual logging contexts in case you need to modify any of the related configuration files. In addition, you might want to create a logging context for Web applications that are developed at your site.

The SAS Web applications implement this capability as follows:

The web.xml file for the Web application contains the following listener element:
```
<listener>
  <listener-class>com.sas.svcs.logging.LoggingContextListener
  </listener-class>
</listener>
```
The listener element must directly follow the filter and filter-mapping elements and directly precede the servlet element. This listener is added as the first listener within the <web-app> element if there are multiple listeners.

The web.xml file also contains this tag:
```
<context-param>
  <param-name>log4j-config-name-prefix</param-name>
  <param-value>YourWebAppName</param-value>
</context-param>
```
In the tag, YourWebAppName should be a name that contain no spaces or special characters (for example, SASWebReportStudio). This name is prefixed to -log4j.xml to form the filename of the application-specific log4j configuration file.
Web application servers use a JVM option, -Dcom.sas.log.config.url, that identifies the directory where the log4j configuration files are located. The framework within the SAS Web Infrastructure Platform uses this property to locate the log4j file for a particular Web application. The framework then loads the configuration into a private logging context for the Web application. Any loggers that the Web application obtains from a locally deployed Logging Service also share this same private logging context. Check your Web application server start-up script or configuration file to determine the appropriate directory location.

Here is an example directory for a default deployment:

SAS-config-dir\Levn\Web\Common\LogConfig

The name of the log4j file has this form:

YourWebAppName-log4j.xml

where YourWebAppName is the string that was provided in the <context-param> element of the web.xml file.
A copy of the sas.svcs.commons.jar, which contains the com.sas.svcs.logging.LoggingContextListener class, must be in the Web application's CLASSPATH. This is accomplished by placing the JAR file within the WEB_INF/lib directory for the Web application.