Documenting logging levels

[august782]

Concerning pull request #3, we should have some documentation of what different logging levels log.

[owolabileg]

What would be a good place to put this? README?

[august782]

Might be good for now. Later, as the project grows even more, we may need some bigger form of documentation, like some web page or something.

[cptwonton]

Logging

Intro

Logging in STARTS is a customized (read: simpler) version of java.util.logging (JUL).

The code for logging is located in starts-core/src/main/java/edu/illinois/starts/util/Logger.java

For any piece of starts that you'd like to add logging to, begin by adding two import statements at the top:

• import edu.illinois.starts.util.Logger;
• import java.util.logging.Level;
  note: you may need to make minor changes to the positioning of these two import statements to ensure checkstyle does not break. place edu.illinois.starts.util.Logger directly underneath the other imports with the same package name, and do the same with java.util.logging.Level. additionally, ensure you have a newline separating different package names

Next, instantiate your Logger as a class variable:

• protected static final Logger logger = Logger.getGlobal();

Levels

There are 7 logging levels (excluding OFF and ALL), just like JUL:

• SEVERE (highest value)
• WARNING
• INFO
• CONFIG
• FINE
• FINER
• FINEST (lowest value)

To set the logging level of your log, use the setLoggingLevel(Level level) method.
i.e.
logger.setLoggingLevel(Level.CONFIG);

To check the logging level, use the getLoggingLevel() method, which will return an object of type Level.
i.e.
Level currentLevel = logger.getLoggingLevel();

Writing messages

There are two methods you can use to log that differ only in the number of arguments you pass in.

public void log(Level lev, String msg, Throwable thr)

should be used when you want to have a custom message AND an exception message

public void log(Level lev, String msg)

should be used when you only want to have a custom message

i.e. logger.log(Level.SEVERE, "houston we have a problem");

In both cases above, the provided message will only be logged if the specified logging Level is equal to or higher in severity than the Level the logger is set to.
For example, if logger.setLoggingLevel(Level.SEVERE);, then only logger.log() messages with Level.SEVERE will be spit out.
Similarly, if logger.setLoggingLevel(Level.CONFIG);, then logger.log() with Level.INFO will be output, but not Level.FINER.

Where will messages be output?

Standard Output (System.out)

[owolabileg]

Hi @jayfurrie, this is an excellent start! Would you mind to (1) create a PR which adds your current documentation to a STARTS-LOGGING.md file in the root directory? (2) add Logging-related documentation from the STARTS tool paper (see "Controlling STARTS Artifact Storage"); that's the kind of documentation that @august782 was originally requesting.

[cptwonton]

done!
i'm still new to git and have trouble isolating this logging stuff from pending pull requests in my fork, such as my IT fix for Windows and Travis YML stuff :(. Are you able to only merge the STARTS-LOGGING.md file rather than all my previous changes?