# RSE Logger API

To use the RSE logging framework, you must first decide if you want your own log file, or want to use the common RSE log file.

## Using Your Own Log File

The log file support is encapsulated in a separate plugin, `com.ibm.etools.systems.logging`, which defines the primary `com.ibm.etools.systems.logging.Logger` class that manages the log file. This log file support offers the ability to log the following types of log messages:

- Error. These are serious errors detected by your programming logic.
- Warning. These are warning situations detected by your programming logic.
- Information. These are informational messages you want to capture to help with problem determination.
- Debug. These are trace statements typically only enabled in development drivers.

To define your own logging file, in your plugin class:

1. Define a static variable to hold the Logger instance, as in:
   `protected static Logger log = null;`
2. Instantiate the Logger object, in your plugin class constructor, as in:
   `if (log == null) log = LoggerFactory.getInst(this);`
3. For convenience, offer fastpaths to the logXXX methods in your Logger instance:

           public static void logInfo(String message)
           {
           	log.logInfo(message);
           }
           public static void logWarning(String message)
           {
           	log.logWarning(message);
           }
           public static void logError(String message)
           {
           	log.logError(message, null);
           }
           public static void logError(String message, Throwable exception)
           {
           	log.logError(message, exception);
           }
           public static void logDebugMessage(String prefix, String message)
           {
               if (Logger.DEBUG)
               {
                  log.logDebugMessage(prefix, message);
               }
           }

4. In the `shutdown` method of your plugin class, close the log file: `LoggerFactory.freeInst(this);`

Typically your code will write a healthy number of messages to the log file, to help you determine what went wrong in an error situation in production. However, since this can result in a large number of messages in the log file, it is recommended that you offer the user's a preference page in which they can specify the types of messages to record in the log file, which should default to error messages only. In the event of a problem, they can then turn on a more verbose logging option and re-produce the problem, sending the log file to you for additional information. For example, for the Remote System Explorer, this preference page is supplied:

## Using The Common RSE Log File

To log your messages to the common RSE log file in `.metadata\plugins\com.ibm.etools.systems.core`, either base your plugin class on the `com.ibm.etools.systems.core.SystemBasePlugin` class and use the inherited logging methods, or instead of instantiating your own `Logging` object, re-use the RSE-supplied logging object by calling `getDefault().getLog()` in the `com.ibm.etools.systems.core.SystemBasePlugin` class.