# 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.

## 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.