august782 commented 7 years ago

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

owolabileg commented 7 years ago

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

august782 commented 7 years ago

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 commented 6 years ago

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 commented 6 years ago

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.