Java - java.util.logging

1 - About

A logger since java 1.4.2, the JavaTM Logging APIs was introduced in package java.util.logging.

See also: Technote Logging Overview

3 - Model

3.1 - Logger

The main entity on which applications make logging calls. A Logger object is used to log messages for a specific system or application component.

Loggers are normally named entities, using dot-separated names such as “java.awt”. The namespace is hierarchical and is managed by the LogManager.

The namespace should typically be aligned with the Java packaging namespace, but is not required to follow it.

Loggers keep track of their parent loggers in the logging namespace. The root Logger (named “”) has no parent. If a Logger is called “a.b.c.d”, and a Logger called “a.b” has been created but no logger “a.b.c” exists, then a call of getParent on the Logger “a.b.c.d” will return the Logger “a.b”.

3.2 - LogRecord

LogRecord objects are used to pass logging requests between the logging framework and individual log Handlers.

3.3 - Levels

Logging levels are used to control logging output. Programs can be configured to output logging for some levels while ignoring output for others.

The Level gives a rough guide to the importance and urgency of a log message.

The Level class defines seven standard log levels, ranging from FINEST (the lowest priority, with the lowest value) to SEVERE (the highest priority, with the highest value).

The levels in descending order are:

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

The root logger defaults to Level.INFO, and as a ConsoleHandler attached to ti that also defaults to Level.INFO.

3.4 - Filter

Provides fine-grained control over what gets logged, beyond the control provided by log levels.

The logging APIs support a general-purpose filter mechanism that allows application code to attach arbitrary filters to control logging output.

3.5 - LogManager

The global LogManager object keeps track of global logging information. This includes:

  • A hierarchical namespace of named Loggers.
  • A set of logging control properties read from the configuration file. See section 1.8.

There is a single LogManager object that can be retrieved using the static LogManager.getLogManager method. This is created during LogManager initialization, based on a system property. This property allows container applications (such as EJB containers) to substitute their own subclass of LogManager in place of the default class.

3.6 - Handler

Logging messages will be forwarded to registered Handler objects, which can forward the messages to a variety of destinations, including consoles, files, OS logs, etc.

Exports LogRecord objects to a variety of destinations including memory, output streams, consoles, files, and sockets. A variety of Handler subclasses exist for this purpose.

Handlers of the API:

  • StreamHandler: A simple handler for writing formatted records to an OutputStream.
  • ConsoleHandler: A simple handler for writing formatted records to System.err
  • FileHandler: A handler that writes formatted log records either to a single file, or to a set of rotating log files.
  • SocketHandler: A handler that writes formatted log records to remote TCP ports.
  • MemoryHandler: A handler that buffers log records in memory.

Example:

//  The pattern "%t" means the system temporary directory.
Handler fh = new FileHandler("%t/myapp.log");
// Send logger output to our FileHandler.
logger.addHandler(fh);

Additional Handlers may be developed by third parties and delivered on top of the core platform.

3.7 - Formatters

Java SE also includes two standard Formatters:

  • SimpleFormatter: Writes brief “human-readable” summaries of log records.
  • XMLFormatter: Writes detailed XML-structured information.

As with Handlers, it is fairly straightforward to develop new Formatters.

4 - Example

5 - Configuration Management

5.1 - Global

The logging configuration can be initialized using a logging configuration file that will be read at startup.

This logging configuration file is in standard java.util.Properties format. See the logging.properties file in the annexe.

You can find the documentation over the properties file in the log Manager

Location:

  • By default, the LogManager reads its initial configuration from a properties file “lib/logging.properties” in the JRE directory.
  • Java parameter java.util.logging.config.file
java -Djava.util.logging.config.file=app.properties MainClass

5.2 - Dynamically

5.2.1 - Levels

5.2.1.1 - Logged

Which kinds of events are logged across all loggers. Not shown in the handler, there is another parameter.

// Request that every detail gets logged.
logger.setLevel(Level.ALL);
5.2.1.2 - Console Handler

Which kinds of event are shown

Handler consoleHandler = new ConsoleHandler();
consoleHandler.setLevel(Level.FINE);
LOGGER = Logger.getLogger(Thread.currentThread().getStackTrace()[0].getClassName()); // Generally a static field for the class
LOGGER.addHandler(consoleHandler);
LOGGER.setUseParentHandlers(false);
LOGGER.setLevel(Level.FINE);

In the properties file:

# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

6 - Logging

6.1 - Initialization

  • You need to give a hierarchical string formatted as a package
public class myClass {
     private static final Logger LOGGER = Logger.getLogger("com.gerardnico.myClass");
..........
}
  • Or dynamically:
public class myClass {
     private static final Logger LOGGER = Logger.getLogger(Thread.currentThread().getStackTrace()[1].getClassName());
..........
}

6.2 - Message

Logging a message:

// The main
logger.fine(String sourceClass, String sourceMethod, String msg);
// where sourceclass and method are there to locate the message
 
// Their are still easily way to log a message. The two below call are equivalent:
logger.log(Level.FINE,"My Fine log");
logger.fine("My Fine log");
// The Logging framework will make a "best effort" to determine which class and method called 
// into the logging framework and will add this information into the LogRecord. 

7 - Annexes

7.1 - logging.properties

############################################################
#  	Default Logging Configuration File
#
# You can use a different file by specifying a filename
# with the java.util.logging.config.file system property.  
# For example java -Djava.util.logging.config.file=myfile
############################################################
 
############################################################
#  	Global properties
############################################################
 
# "handlers" specifies a comma separated list of log Handler 
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
handlers= java.util.logging.ConsoleHandler
 
# To also add the FileHandler, use the following line instead.
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler
 
# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers.  For any given facility this global level
# can be overriden by a facility specific level
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level= INFO
 
############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################
 
# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
 
# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
 
# Example to customize the SimpleFormatter output format 
# to print one-line log message like this:
#     <level>: <log message> [<date/time>]
#
# java.util.logging.SimpleFormatter.format=%4$s: %5$s [%1$tc]%n
 
############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################
 
# For example, set the com.xyz.foo logger to only log SEVERE
# messages:
com.xyz.foo.level = SEVERE

8 - Documentation / Reference

lang/java/java.util.logging.txt · Last modified: 2017/08/09 20:57 by gerardnico