# The Logging API

The SBLIM CIM Client for Java has a log & trace API that is extensible by application. Since the CIM client is always running in the context of an application it is not desired that it writes its own log files. Therefore the SBLIM CIM Client for Java offers listener interfaces for log & trace messages to which the application can subscribe and forward the messages to the application's logger.

## Log & Trace

The client distinguishes between log & trace. The audience of the log is an admin at the customer site. The log is localized and contains only the most important messages. The messages are listed in a catalog. The audience of the trace are service engineers and support people. It is not localized, but always in English and may contain the most detailed trace messages desired. The trace is always a superset of the log, which means all messages sent to the log are sent to the trace as well.

The trace is a tool for problem determination that shouldn't be active in normal operation. Tracing at levels of FINE and below creates much more messages than logging. Moreover for every entry in the trace file the stack trace is analyzed to identify the originating method. Having full tracing active therefore will degrade performance.

## Levels

The message levels are taken from `java.util.logging.Level` (decreasing severity):

- SEVERE
- WARNING
- INFO
- CONFIG
- FINE
- FINER
- FINEST

All messages with a Level less than CONFIG will be sent to the trace only.

## Listeners

An application can register itself as a listener for log and/or trace messages. In order to do so it must implement the `LogListener` and/or `TraceListener` interfaces and call `addLogListener()`/ `addTraceListener()` on the `LogAndTraceManager` instance.

The following code snippet gives an example:

    LogAndTraceManager manager = LogAndTraceManager.getManager();

    manager.addLogListener(new LogListener() {
      public void log(Level pLevel, String pMessageKey, String pMessage,
        Object[] pParameters) {
          System.out.println("Log message "+pMessageKey+" (Level="+pLevel+"): "
            +MessageFormat.format(pMessage, pParameters));
      }
    });

    manager.addTraceListener(new TraceListener() {

      public void trace(Level pLevel, StackTraceElement pOrigin, String pMessage) {
        System.out.println("Trace message (Level="+pLevel+") from "
          +String.valueOf(pOrigin)+": "+pMessage);
      }

      public void trace(Level pLevel, StackTraceElement pOrigin, String pMessage,
        Throwable pThrown) {
          System.out.println("Trace message (Level="+pLevel+") from "
            +String.valueOf(pOrigin)+": "+pMessage);
          pThrown.printStackTrace();
      }
    });

The `System.out.println()` would of course be replaced with the API calls of the applications logger

## CIM-XML Trace Listeners

An application can register itself as a listener for CIM-XML trace messages. In order to do so it must implement the `CIMXMLTraceListener` interface and call `addCIMXMLTraceListener()` on the `LogAndTraceManager` instance.

The following code snippet gives an example:

    LogAndTraceManager manager = LogAndTraceManager.getManager();

    manager.addCIMXMLTraceListener(new CIMXMLTraceListener() {

      public void trace(Level pLevel, String pMessage, boolean pOutgoing) {
        System.out.println("CIM-XML "+(pOutgoing ? "sent" : "received")
          +" by client at level "+pLevel+": "+pMessage);
      }
    });

The `System.out.println()` would of course be replaced with the API calls of the applications logger

## Classic Logging

You say "That's interesting stuff, but I just want my plain old log files back." No problem, the SBLIM CIM Client for Java offers this as well. Via configuration properties you can set up classical file logging out of the box. See the configuration document for details on how to set configuration properties. The `sblim-cim-client2.properties` file contains documentation on all properties.

Note: If you want to set up the logging via `System.setProperty()` calls, make sure that this happens before any CIM client class is loaded by the classloader. The classic logging is set up in static initializers.