Chapter 2. Logging

Table of Contents

1. Overview
2. Servlet container logging
3. Java IO streams
4. LPS logging
5. Log4j tidbits
5.1. Interactions between container and LPS logging
6. Using the LPS administrative console
7. Logging from within LZX
8. Caveats

This chapter describes how to monitor and configure LPS logging as well as how to log events from your LZX application. Some of the same details are covered in Chapter 4, Deploying OpenLaszlo Applications.

Conventions used in this chapter:

1. Overview

The LPS provides a highly configurable and efficient logging mechanism that you can use to debug and monitor server activities. The LPS relies on the well-known Log4j package and this chapter touches on only a handful of the Log4j details you may need or want to know. Before we go on to discuss the LPS log in some detail, we will first briefly go over the logging details provided by the servlet container. Chapter 1, OpenLaszlo Architecture explains what a container is and how LPS fits inside it.

2. Servlet container logging

The servlet container itself maintains logs of its activities that may be of interest for debugging or monitoring Laszlo applications. These include:

  • web application lifecycle events (and errors),

  • request/response details,

  • individual web-application logs, and,

  • other container-specific details.

The Jakarta Tomcat 5.0 container, by default, keeps its logs in $TOMCAT_HOME/logs. Depending on how tomcat was started, it may also display some of its logs in a console or terminal window as well. The Tomcat 5.0 configuration guide has details on its Logger configuration. In general, see the documentation on your container for details on how to locate and configure these logs.

Servlet containers do provide a mechanism for the LPS to write directly into the container logs. In general though, the LPS does not use this mechanism except at initialization time. When the LPS starts up, it logs a short list of initialization details to the container's log. In particular, it logs a message that describes where to find the detailed LPS log, that contains the remainder of the LPS log messages.

When the LPS is started successfully, you will see information such as the following in the container's log.

2004-04-20 15:58:23 LPS: LPS_HOME is c:\Program Files\Laszlo Presentation Server 2.2\Server\lps-2.2
2004-04-20 15:58:23 LPS: LPS config directory is: c:\Program Files\Laszlo Presentation Server 2.2\Server\lps-2.2\WEB-INF\lps\config
2004-04-20 15:58:24 LPS: Detailed LPS log is at C:/Program Files/Laszlo Presentation Server 2.2/Server/lps-2.2/WEB-INF/lps/work/logs/lps.log
2004-04-20 15:58:24 LPS: LPS log configured with c:\Program Files\Laszlo Presentation Server 2.2\lps-2.2\WEB-INF\lps\config\lps.xml

3. Java IO streams

Since ultimately a Java servlet container is just a Java process, it has standard IO streams, stdout and stderr, associated with it. Some containers may provide configuration for the location of the files that these streams are written to. In general, the LPS does not use these streams for logging. Your container may or may not use these streams. Other server code in your web application may use these streams. We mention them briefly here as they can be helpful in debugging configuration or installation problems.

If you have set certain Java debugging options, you may find debug information in the stderr stream. For example, if you are debugging Java $CLASSPATH and class loading issues, you may use JAVA_OPTS="-verbose:class" and you will want to locate the Java stderr stream for the verbose output. Jakarta Tomcat will often store these files its $TOMCAT_HOME/logs directory. (If you are on Windows and running Tomcat as an NT service, the location of these files will depend on how the NT service was created; these files are in C:\WINDOWS\system32\stderr.log and C:\WINDOWS\system32\stdout.log).

4. LPS logging

The LPS log (referred to above as the detailed LPS log) contains both request/response details as well as debugging information.

The default location for the LPS log file is inside the web applications WEB-INF directory at $LPS_HOME/WEB-INF/lps/work/logs/lps.log.

For some deployments, you may want to configure the log location to be something other than the default. The LPS Log4j configuration is read from $LPS_HOME/WEB-INF/lps/config/lps.xml. If $LPS_HOME/WEB-INF/lps/config/log4j.xml settings are read from this file instead.

The LPS ships with its logger configured at the INFO level. You may wish to change this to WARN or ERROR to see fewer details, or to DEBUG to see more details. You can do this by changing the priority attribute of the org.openlaszlo logger defined in the default lps.xml file. Below is an example of chaning the logger to DEBUG. The DEBUG level is extremely verbose.

Example 2.1. Changing LPS log to DEBUG

<logger name="org.openlaszlo" additivity="false">
  <priority value="debug"/>
  <appender-ref ref="lps"/>
</logger>

5. Log4j tidbits

If your container also uses Log4j to configure its own logging, there can be some interaction between the LPS logs and the container logs.

5.1. Interactions between container and LPS logging

If your container happens to also use Log4j as its logging mechanism (Tomcat 5.0 does), then you may see interactions between the container and LPS logging depending on how the Log4j appenders are configured for the LPS.

6. Using the LPS administrative console

The Administrative console will display the current Log4j configuration in XML. You can edit the configuration live in the console and press 'Update' to change the logging configuration w/out restarting the server. If you'd like these configuration changes to persist accross server restarts, you can select the save checkbox and the settings will be saved to $LPS_HOME/WEB-INF/lps/log4j.xml.

7. Logging from within LZX

You can log events from your application to the server quite simply. There are three steps.

  • Modify the log4j configuration

  • Create a logger jsp

  • Send messages to the logger from your LZX code

You may want to log directly into the LPS log file. Or you may want to log into a separate file. You can set up the Log4j configuration to best suit your needs. And the configuration can be changed after the application has been developed.

Log4j appenders can be used to control where log statements are emitted. The example below creates a new logger called mylogger that will append log statements to the C:\mylog.txt file. (If you wanted your applications log statements to go directly into the LPS log file, you would configure your logger to use the lps appender that is already declared.)

Example 2.2. Log4j configuration: creating your own logger

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j">

  <appender name="myappender" class="org.apache.log4j.RollingFileAppender">
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" 
             value="%d{dd MMM yyyy HH:mm:ss} %-5p - %m%n"/>
    </layout>	    
    <param name="File" value="c:\mylog.txt"/>
  </appender>

  <appender name="lps" class="org.apache.log4j.RollingFileAppender">
    <!-- ==================================================== -->
    <!-- By default, the LPS sets the log file in the servlet -->
    <!-- container's temporary directory. See servlet context -->
    <!-- log for the exact location.                          -->
    <!-- If you wish to place that file somewhere else, like  -->
    <!-- /var/adm/logs, then uncomment the line below.        -->
    <!-- ==================================================== -->
    <!--
    <param name="File" value="/var/adm/logs/lps.log"/>
    -->

    <!--
    <param name="MaxFileSize" value="10MB"/>
    -->
    <param name="MaxBackupIndex" value="10"/>

    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" 
               value="%d{dd MMM yyyy HH:mm:ss} (%x) %-5p %-20c{2} - %m%n"/>
    </layout>	    
  </appender>

  <logger name="mylogger" additivity="false">
    <priority value="debug"/>
    <appender-ref ref="myappender"/>
  </logger>

  <logger name="org.openlaszlo" additivity="false">
    <priority value="info"/>
    <appender-ref ref="lps"/>
  </logger>
</log4j:configuration>

The following is a simple JSP that can be used to talk to a Log4j logger of a given name and emit error, warn, info, or debug messages.

Example 2.3. Simple JSP logger

<%@ page import="java.util.*" %>
<%@ page import="java.io.*" %>
<%@ page import="org.apache.log4j.*" %>
<%
  response.setContentType("text/xml");
  response.setHeader("Expires", "Fri, 05 Oct 2001 00:00:00 GMT");

  String loggerName = request.getParameter("logger");
  Logger logger = Logger.getLogger(loggerName);
  String msg = request.getParameter("msg");
  String t = request.getParameter("type");

  if (t.equalsIgnoreCase("debug")) {
    logger.debug(msg);
  } else if (t.equalsIgnoreCase("info")) {
    logger.info(msg);
  } else if (t.equalsIgnoreCase("error")) {
    logger.error(msg);
  } else if (t.equalsIgnoreCase("warn")) {
    logger.warn(msg);
  } else {
    throw new Exception("unknown log type");
  }
%>
<status>ok</status>

[Warning] Warning

If you deploy something like the JSP above, you will likely want the JSP to require some authentication.

The following is a simple Laszlo application that can be used with the above JSP and log configuration to emit messages to the C:\mylog.txt file.

Example 2.4. Log from LZX to the server

<canvas>
  <dataset name="ds" src="http:logger.jsp"/>
  <form layout="axis: y" id="f">
    <edittext id="logger" width="200">mylogger</edittext>
    <edittext id="msg"    width="300">Your message here </edittext>
    
    <radiogroup id="t">
      <radiobutton>debug</radiobutton> 
      <radiobutton>warn</radiobutton> 
      <radiobutton>error</radiobutton> 
      <radiobutton>info</radiobutton> 
    </radiogroup> 
    <button isdefault="true">Log message to server
      <handler name="onclick">
        ds.setQueryParams({logger:logger.text, msg: msg.text, type:t.value}); 
          ds.doRequest();
      </handler>
    </button>
  </form>
</canvas>

8. Caveats

  • The precise format of the LPS log may change from release to release.