[Tutorial 2.1] The Logging Framework

WARNING: THIS DOCUMENTATION IS FOR CCRE v2, NOT CCRE v3!

See the readme on the main page for the correct documentation.

The Logging Framework

[Back to the previous tutorial]([Tutorial 1.6] Basic Autonomous)

Debugging messages

Normally, in small Java applications developers report what the code is doing using something like the following:

System.out.println("Something happened!");

In larger applications, large logging frameworks are used:

// At the start of the class
private static final Logger log = Logger.getLogger("packagename.ClassName");
// When logging a message
    log.log(Level.FINEST, "Something happened!");

Now, this can be overly verbose and require extra code, but in many ways working with logging frameworks can improve code. For example, everything that you log can be sent over the network automatically in a way that System.out messages can't easily. However, most common logging frameworks are too heavy-weight for FRC use, and many require features that the Squawk Virtual Machine doesn't support. So, the CCRE has its own logging system. Here's a simple use:

Logger.info("Something happened!");

This snippet of code will log the message "I live!". This message will go to the console that Eclipse displays for you, to a memory log, to a file, and over the network if you are using Cluck.

One quick note: This mechanism will put these into log files on the robot, but if there are too many log files, the robot starts taking a long time to start! (This is a known issue.) The CCRE will automatically download and remove these files every time that you download code.

Logging Levels

The CCRE's logger supports the following logging levels:

SEVERE
WARNING
INFO
CONFIG
FINE
FINER
FINEST

I will borrow the descriptions of these levels from here:

Level.SEVERE: In general SEVERE messages should describe
events that are of considerable importance and which will
prevent normal program execution.
Level.WARNING: In general WARNING messages should describe
events that will be of interest to end users or system
managers, or which indicate potential problems.
Level.INFO: Typically INFO messages will be written to the
console or its equivalent. So the INFO level should only be
used for reasonably significant messages that will make
sense to end users and system administrators.
Level.CONFIG: CONFIG messages are intended to provide a
variety of static configuration information, to assist in
debugging problems that may be associated with particular
configurations. For example, CONFIG message might include
the CPU type, the graphics depth, the GUI look-and-feel,
etc.
Level.FINE: In general the FINE level should be used for
information that will be broadly interesting to developers
who do not have a specialized interest in the specific
subsystem.
Level.FINER: FINER indicates a fairly detailed tracing
message.
Level.FINEST: FINEST indicates a highly detailed tracing
message. 

Please note that I didn't invent these log levels - I only copied them from the builtin logging system because they were useful.

Logging Methods

The primary way that messages will be logged is through the Logger class's static methods:

Logger.fine("Starting message subsystem.");
Logger.config("Port number set to 413");
Logger.info("Message subsystem reconnected to peer after timeout.");
Logger.severe("Message subsystem has lost connection to peer.");

As well, it often happens that you've caught an exception of some sort and want to report it:

Logger.warning("Exception while handling message!", exception);

All of the static methods on Logger can optionally take an exception that will be included in the log.

EventLogger

It occurs fairly often that you want to log a message whenever an event fires. Luckily, there's an easy way to do this!

EventLogger.log(catapultRearmedEvent, LogLevel.INFO, "The catapult has been rearmed!");

EventLogger.log takes an EventInput, LogLevel, and message to log when the event is fired.

EventLogger can also be used as an EventOutput:

EventOutput statusReporter = new EventLogger(LogLevel.INFO, "Status has been reported!");

Next: [Control Structures - ExpirationTimer, PauseTimer, MultipleSourceBooleanController, Ticker]([Tutorial 2.2] Control Structures - ExpirationTimer, PauseTimer, MultipleSourceBooleanController, Ticker)