Logging guidelines » History » Revision 2
Revision 1 (Moritz Horsch, 06/13/2012 11:20 AM) → Revision 2/4 (Tobias Wich, 07/25/2012 11:31 AM)
h1. Logging guidelines
{{toc}}
h2. Framework
h3. SLF4J (Simple Logging Facade for Java)
"Documentation":http://www.slf4j.org/docs.html
h3. Maven
No dependency SHOULD be added to the module POM. The slf4j dependency is dependencies are already defined in the ecard client root POM.
slf4j needs a backend implementation. For the tests, logback-classic is pulled in by the root POM. For production use, the client artifact must pull in a compile dependency on a backend and configure it appropriately.
h3. Preamble
<pre>
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);
</pre>
h3. SLF4J with java.util.logging backend
*TODO:* rewrite for logback-classic
This code SHOULD only be using in TestNG. JUnit tests.
<pre>
// Reset configuration to avoid multiple log entries.
java.util.logging.LogManager.getLogManager().reset();
// Add new console handler
ConsoleHandler ch = new ConsoleHandler();
ch.setLevel(Level.ALL);
// Set logging level
LogManager.getLogger(MYCLASS.class.getName()).setLevel(Level.FINE);
// Log message as jdk logging level INFO
logger.info("Log logger.info(LoggingConstants.FINE, "Log my message: {}", message);
// Log message as jdk logging level FINE
logger.debug("Log logger.debug(LoggingConstants.FINE, "Log my message: {}", message);
// Log message as jdk logging level WARNING
logger.warn("Log logger.warn(LoggingConstants.FINE, "Log my message: {}", message);
// Log message as jdk logging level SEVERE
logger.error("Log logger.error(LoggingConstants.FINE, "Log my message: {}", message);
</pre>
h2. Levels
h3. Overview
Marker are specified in @org.openecard.client.common.logging.LoggingConstants@
* THROWING: [[Logging guidelines#Exceptions|Exceptions]]
* SEVERE:
* INFO:
* CONFIG:
* FINE: [[Logging guidelines#Exceptions|Messages]]
* FINER: [[Logging guidelines#Exceptions|Events]]
* FINEST:
h3. Exceptions
<pre>
import org.openecard.client.common.logging.LoggingConstants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);
try{
...
} catch (Exception e){
logger.error(ex.getMessage(), ex);
}
</pre>
Or set a descriptive message:
<pre>
try{
...
} catch (Exception e){ // <editor-fold defaultstate="collapsed" desc="log exception">
logger.error("Error while reading value X.", ex); logger.error(LoggingConstants.THROWING, "Exception", e);
// </editor-fold>
}
</pre>
h3. Messages
Messages including APDUs, eCard-API messages, PAOS messages.
<pre>
import org.openecard.client.common.logging.LoggingConstants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);
logger.debug("Message // <editor-fold defaultstate="collapsed" desc="log message">
logger.debug(LoggingConstants.FINE, "Message received:\n{}", message);
logger.debug("Message // </editor-fold>
// <editor-fold defaultstate="collapsed" desc="log message">
logger.debug(LoggingConstants.FINE, "Message sent:\n{}", message);
// </editor-fold>
</pre>
h3. Events
E.g. GUI events.
<pre>
import org.openecard.client.common.logging.LoggingConstants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);
logger.debug("Event: // <editor-fold defaultstate="collapsed" desc="log event">
logger.debug(LoggingConstants.FINER, "Event: {}", event);
// </editor-fold>
</pre>
h2. Notes
h3. Trace statements as the following example shows are omitted, because there is omitted
<pre>
logger.trace("Trace a message: {}", message);
</pre>
Will be replaced by "slf4j agent":http://www.slf4j.org/extensions.html#javaagent which can automate this task. extension":http://www.slf4j.org/extensions.html#javaagent.
h2. Examples
h3. APDU logging
<pre>
public void foo(Bar b) {
logger.trace("Enter function foo: {}", b);
... import org.openecard.client.common.ECardConstants;
import org.openecard.client.common.logging.LogManager;
java.util.logging.LogManager.getLogManager().reset();
ConsoleHandler ch = new ConsoleHandler();
ch.setLevel(Level.ALL);
LogManager.getLogger("org.openecard.client.ifd.scio.wrapper").addHandler(ch);
LogManager.getLogger("org.openecard.client.ifd.scio.wrapper").setLevel(Level.FINE);
</pre>