Logging

On the BlackBerry there are two Logging APIs implemented. Log4j and SLF4J. SLF4J delegates to Log4j so it can reuse the appenders for the BlackBerry. The advantage of SLF4J is it has Android compatibility.

Log4j

Javadocs

Javadocs for log4j can be found here.

Overview

Log4j is an apache project which is heavily documented here. To use the log4j on the BlackBerry import the log4j logger:

import m.org.apache.log4j.Logger;

and declare a logger in your class:

private static final Logger log = Logger.getLogger( MyClass.class );

You can then use the logger to log at any level:
log.debug("Purely for debugging.");
or
log.error("There was an error.");

When logging an error associated with an Exception you should pass the Exception in as the second argument:
log.error("Unable to perform an action", exception);
This will print the exception class and message in the log. If you caught Throwable on the BlackBerry it will also log the stack trace to the device event log.

See Apache's documentation on performance for details on when to use isDebugEnabled() and how performance impacts the different logging calls.

Configuring

On the BlackBerry, log4j is configured in a properties file. The log4j.properties file in the src/main/resources directory will be used for release builds. The file in the src/test/resources directory will be used for development builds. In the log file you can configure multiple appenders:

• ConsoleAppender - writes to standard out.
• MemoryLogAppender - writes to memory on a rolling buffer. This is useful for uploading to the server or writing to a file.
• EventLogAppender - writes to the BlackBerry event log.
  Here is a sample log4j.properties file:

  log4j.rootLogger=INFO, ROOTAPPENDER, MEMORYLOGAPPENDER
  
  log4j.appender.ROOTAPPENDER=m.org.apache.log4j.ConsoleAppender
  log4j.appender.ROOTAPPENDER.layout=m.org.apache.log4j.PatternLayout
  log4j.appender.ROOTAPPENDER.layout.ConversionPattern=[%d-%t][%c{1}][%-5p] - %m\n
  
  log4j.appender.MEMORYLOGAPPENDER=org.metova.mobile.rt.logging.MobileMemoryLogAppender
  log4j.appender.MEMORYLOGAPPENDER.layout=m.org.apache.log4j.PatternLayout
  log4j.appender.MEMORYLOGAPPENDER.layout.ConversionPattern=[%d-%t][%c{1}][%-5p] - %m\n
  
  log4j.logger.org.metova.mobile.util.Version=WARN
  log4j.logger.org.metova.mobile.event=WARN
  

The details of configuring log4j can be found in Apache's log4j's documentation.

SLF4J

SLF4J is documented on SLF4J's website. To use this on the BlackBerry just include SLF4J as a dependency. This will still require log4j to be configured.

Saving the Log file

If the MemoryLogAppender is enabled the last 2000-3000 lines of the log can be accessed in memory. They can be written to disk by calling:
new org.metova.mobile.rt.bb.logging.LogToFilePlatform().logToFile()
This will save the file to the SD Card if available.

Viewing the Log File on screen

You can view the current log on the screen by displaying a com.metova.bb.provisioning.ui.MetovaLogContainer.

Submitting a Log.

Applications which are dependent on metova-bb-provisioning and extend ProvisionedUiApplication will support log submission. You can submit a log to the Metova Provisioning Service in two ways:

• Pressing Alt-LLL to submit the log to the server directly (this will not be noticed in Jira, and should be a backup method only).
• Submitting an Issue via the IssueService. If configured this will submit an issue from the device to the Issue Tracking system with device details and the log in the issue description.

Metova's provisioning service is provided by Metova and must be turned on for your application.