Logging in the Joseki Server

This document describes the use of logging with a Joseki server. It covers information for both people configuring and deploying a server as well as those writing query processors and other modules.

Joseki uses the Jakarta Common Logging package. This is an API for code to be independent of the choice of logging environment. Supported environments include Log4j and java logging introduced in Java 1.4.

Early versions of Joseki (up to v2.0) just used Java logging – more convenient use in Tomcat prompted the change to Jakarta Commons Logging. Jena also uses Jakarta Commons Logging.

Logging Policy

This is just applying the general logging recommendations found in the Jakarta Commons Logging user guide.

Level Usage

trace The lowest level: can be very verbose.

debug Detailed information about the configuration of the server and execution of requests. Normally disabled but enabled for tracking down problems with a server.

info Normally a server will run with this level enabled. It is used to record, briefly, configuration and all requests, roughtly one logging entry per successful request, or one logging entry for a failed request.

warn Used to note server problems which do not stop the request from proceeding. This is not the same as a failed request. They get logged as .info

error Used to record (internal) problems that stop the request being processed or when internal inconsistences are deteched. The server may be able to continue processing some requests (e.g. on other models).

fatal A problem has arisen that causes the whole server to cease functioning correctly.

Level	Usage
trace	The lowest level: can be very verbose.
debug	Detailed information about the configuration of the server and execution of requests. Normally disabled but enabled for tracking down problems with a server.
info	Normally a server will run with this level enabled. It is used to record, briefly, configuration and all requests, roughtly one logging entry per successful request, or one logging entry for a failed request.
warn	Used to note server problems which do not stop the request from proceeding. This is not the same as a failed request. They get logged as .info
error	Used to record (internal) problems that stop the request being processed or when internal inconsistences are deteched. The server may be able to continue processing some requests (e.g. on other models).
fatal	A problem has arisen that causes the whole server to cease functioning correctly.

Notes

Logging in the standalone server

Joseki defaults to using log4j because Joseki comes with a copy of log4j and standard way Jakarta Commons Logging decides which logging system to use is first to check for log4j. You can choose the logging implementation you want by setting the system property org.apache.commons.logging.Log

Java logging: org.apache.commons.logging.impl.Jdk14Logger
Log4j: org.apache.commons.logging.impl.Log4JLogger

Some sample logging configurations are given in the etc/ directory.

Logging in Tomcat

Tomcat uses Jakarta Commons Logging. If you want to use log4j with Tomcat, you can just drop in the log4j jar. If a web application, like Joseki, has its own private copy as well, this will create its own initialization of log4j just for that web application.
To set the configuration file, either place log4j.properties on the classpath (it is not found as a file), such as in WEB-INF/classes/log4j.properties or set the system property when starting Tomcat:
export CATALINA_OPTS="-Dlog4j.configuration=file:<your config file>"

Log4j

Levels trace and debug are both mapped to log4j level DEBUG. Example log4j property files are to be found in etc/.

Java Logging

There is a stream handler that writes to stdout, and then always flushes messages and also a one line formatter (it formats messages to be like the form for the one line log4j PatternLayout used intge log4j examples) in the package org.joseki.logging.java. Example logging property files are to be found in etc/.

Module Implementers

Implementers of Joseki modules should read the Jakarta Commons Logging user guide and folow the guidelines on levels. They are only guidelines - just remember your module may be running inside a large system so don't output too much by default. The server will log once per request. It is a judgement call.