Logging

Introduction


Some CLDR code has "optional" output that may normally want to be suppressed, for example, debugging output, or output that is useful to trace certain operational issues. Previously, the ad-hoc practice had been generous uses of `System.out.println()`, sometimes moderated by `if (DEBUG) …` where DEBUG is a static boolean, perhaps configured via a system property.

The purpose of this present document is to give an introduction to the recommended mechanism, and give some best practices within CLDR.

java.util.logging

The current recommendation is to use the java.util.logging mechanism, which was added in JDK 1.6. This mechanism operates through using multiple "Logger" instances. For our use, we will normally be creating one Logger per CLDR class.

The logger has the notion of "levels", encapsulated as the class java.util.logging.Level. For example, if the logger for the class "org.unicode.cldr.Foo" has level INFO, then log messages of the level FINE would be suppressed and not be recorded, but logs at level SEVERE or INFO would be recorded.

Basic Use

At the top of each class, add code similar to the following:

import java.util.logging.Logger;
class MyClass {
    static final Logger logger = Logger.getLogger(MyClass.class.getName());

(Note: some TestFmwk subclasses already have a "logger" instance field.)

Then, wherever you want to output some content, use one of the java.util.logging.Logger instance fields. Below are some examples.

logger.info("FYI, something happened");
logger.severe("Something bad happened!");

Changing the logged level

Tools / Tests

1. create a config file, "my-logging.properties" in some location. Here are some sample contents:

# output logging to stdout                                                                                             
handlers= java.util.logging.ConsoleHandler
# we want ConsoleHandler to dump out everything it gets                                                                
java.util.logging.ConsoleHandler.level = ALL
# Default level for all classes                                                                                        
.level = INFO
# Override the level for one class of interest                                                                         
org.unicode.cldr.MyClass.level = FINEST

2. When running your tool or test, set a system property to select that config file:

java -Djava.util.logging.config.file=/tmp/my-logging.properties -jar tools/cldr-code/target/cldr-code.jar org.unicode.cldr.MyClass

Within the SurveyTool

In `bootstrap.properties` or other mechanism for setting system properties, set the following to bump the log level:

com.ibm.ws.logging.trace.specification=org.unicode.cldr.web.MyClass.level=finest

You can also set the following in the server.xml file. 
(Note: If you change the live version, such as /var/lib/openliberty/usr/servers/cldr/server.xml then changes take effect immediately, while the server is running) 

<logging traceSpecification="org.unicode.cldr.web.MyClass.level=finest:org.unicode.cldr.SomethingElse=severe"/>



Documentation


Comments