Logging

Logging

Log messages should be based on java.util.logging.

Earlier use of SLF4J, Log4J, Apache.commons.logging and others is deprecated. While they each may have some slight advantage, we do want to limit a spread of logging library dependencies.

Obtaining a Logger

Use a logger that reflects the plugin name, which typically is possible by using the package name of a class.

In most cases, creating just one logger for each plugin with the name of the plugin is most effective:

class MyPluginActivator
{
    final private static String ID = "org.csstudio.my.plugin"; // Plugin ID
    final private static Logger logger = Logger.getLogger(ID);

In some cases, having more detailed loggers associated with a class is useful:

class MyClass
{
    final private static Logger logger = Logger.getLogger(getClass().getName());

As for using class.getName(), this will provide the full package name. For nested (inner) classes, it will return a name that is harder to read like org.csstudio.my.plugin.MyClass$1, but this information can be used by developers to locate the inner class.

class.getSimpleName() will not include the package name and should NOT be used to obtain a logger.

class.getCanonicalName() will be NULL for anonymous inner classes and it therefore less useful.

http://stackoverflow.com/questions/15202997/what-is-the-difference-between-canonical-name-simple-name-and-class-name-in-jav

Log Patterns

When encountering an exception, log the exception information which will result in a complete stack trace, including nested 'Caused by' exceptions:

catch (Exception ex)
{
    logger.log(Level.WARNING, "Something terrible happened", ex);

Log Levels

SEVERE: Exceptions, errors that cause CS-Studio to fail in a way that is irrecoverable and will result in further errors across multiple applications. Will require a restart of CS-Studio, usually after a configuration problem has been fixed.

WARNING: Exceptions, errors that developers and site administrators might need to investigate. Users will notice that something doesn't "work", but CS-Studio continues to run

INFO: Messages that are reasonably significant to end users and system administrators. Not an error.

CONFIG: Configuration detail, usually logged on startup, that might help to debug the configuration of CS-Studio.

FINE, FINER, ..: Debug messages, for example logging the steps of the application logic, which are only of interest to developers when trying to analyze the detailed behavior of their code.