Three Mintute Intro

Installation

Copy the bin jar to the [JRE_HOME]/lib/ext folder. For instance, if your Java runtime is in /opt/jdk1.6/jre, the logging jar would be placed in /opt/jdk1.6/jre/lib/ext.

Note that on Windows, the JRE is the default Java used to run programs and this is often installed in "Program Files" even if you install it as part of the JDK and install the JDK elsewhere.

General Configuration

By default, the JDK will load the logging.properties file in the [JRE_HOME]/lib folder to configure the logging system.

If you want to create a custom configuration file, you can tell the logging system to use this custom configuration file by setting the System Property java.util.logging.config.file to the name of the file. For examle, if you created a file called app-logging.properties you'd invoke java using the command line option -Djava.util.logging.config.file=app-logging.properties.

General Template Options

The two formatters use a pattern of tokens to determine how the log record will be output. The tokens that you can use in the pattern include:

%p

the logging level

%d

the date/time of the log record, the default date format is HH:mm:ss.SSSS, if you wish to define another, put it in braces immediately after the %d token (i.e. %d{HH:mm:ss})

%l

the full logger name

%L

the simple logger name (without package name, if any)

%c

the full class name that generated the log record

%C

the simple class name (without package name, if any)

%M

the name of the method that generated the log record

%t

the name of the thread that the formatter is running in (which is likely the same thread as the class which generated the log record, but not necessarily so

%m

the log message

%T

the log record's exception

%n

line separator

For example, if you supplied the pattern:
At %d we say %m
you might see a log line like:
At 15:34:29.102 we say Customer registration and notification is starting.

Template Formatter

The template formatter substitutes tokens in a supplied pattern with attributes of the log record to be published. By default this formatter does not add a line feed at the end of a line. Your pattern should end with a %n token if you want one added (likely that is the case).

Example

To use the templating formatter, put lines like the following in your logging.properties file.

java.util.logging.ConsoleHandler.formatter =org.bifrost.logging.TemplateFormatter
org.bifrost.logging.TemplateFormatter.pattern=%d %p [%t] %C.%M()%n%m%T%n

You can then test your logging configuration using the line:

java org.bifrost.logging.LoggingTest

If you get a ClassNotFoundException then you don't have the logging jar properly installed in your Java runtime - it should be in the [JRE_HOME]/lib/ext folder.

If everything is configured properly, you'll see something like:

15:45:07.0844 FINER [main] LoggingTest.main()
A message at finer level
15:45:07.0919 FINE [main] LoggingTest.main()
A message at fine level
15:45:07.0921 CONFIG [main] LoggingTest.main()
A message at config level
15:45:07.0930 INFO [main] LoggingTest.main()
A message at info level
15:45:07.0931 WARNING [main] LoggingTest.main()
A message at warning level
15:45:07.0934 SEVERE [main] LoggingTest.main()
A message at severe level
15:45:07.0935 SEVERE [main] LoggingTest.main()
An exception at servere level
java.lang.Exception: ooops, an error
org.bifrost.logging.LoggingTest.main(LoggingTest.java:34)

Single Line Formatter

The single line formatter substitutes tokens in a supplied pattern with attributes of the log record to be published. By default this formatter does add a line feed at the end of a line.

Example

To use the templating formatter, put lines like the following in your logging.properties file.

java.util.logging.ConsoleHandler.formatter =org.bifrost.logging.SingleLineFormatter
org.bifrost.logging.SingleLineFormatter.pattern=%d %p [%t] %C.%M() - %m%T
org.bifrost.logging.SingleLineFormatter.lineSeparator=|

If everything is configured properly, you'll see something like by running LoggingTest:

15:59:33.0704 FINER [main] LoggingTest.main() - A message at finer level
15:59:33.0779 FINE [main] LoggingTest.main() - A message at fine level
15:59:33.0780 CONFIG [main] LoggingTest.main() - A message at config level
15:59:33.0789 INFO [main] LoggingTest.main() - A message at info level
15:59:33.0791 WARNING [main] LoggingTest.main() - A message at warning level
15:59:33.0793 SEVERE [main] LoggingTest.main() - A message at severe level
15:59:33.0795 SEVERE [main] LoggingTest.main() - An exception at servere \
level|java.lang.Exception: ooops, \
an error|org.bifrost.logging.LoggingTest.main(LoggingTest.java:34)|

The last line will not split, however, it is presented that way to make it readable.

Email Handler

The email handler asynchronously emails log records to a specific email address. The inner workings of the handler warrant some explanation so head over to the documentation for a little more information.

Example

To use the email handler, put lines like the following in your logging.properties file.

In the Global properties section of the file, add the handler to the list of handlers:

handlers= java.util.logging.ConsoleHandler,org.bifrost.logging.EmailHandler

and then add the following lines somewhere below.

org.bifrost.logging.EmailHandler.level=INFO
org.bifrost.logging.EmailHandler.smtphost=localhost
org.bifrost.logging.EmailHandler.smtpport=25
org.bifrost.logging.EmailHandler.clientDomain=your_company.com
org.bifrost.logging.EmailHandler.subject=Error %p from %C
org.bifrost.logging.EmailHandler.from=help@your_company.com
org.bifrost.logging.EmailHandler.to=support@your_company.com
org.bifrost.logging.EmailHandler.pacing=1000
org.bifrost.logging.EmailHandler.pause=10000
org.bifrost.logging.EmailHandler.formatter=org.bifrost.logging.TemplateFormatter
org.bifrost.logging.TemplateFormatter.pattern=%d %p [%t] %C.%M()%n%m%T%n

This will cause all log records of level INFO and higher to be emailed to the address support@your_company.com. Note that you can include log record tokens in the subject configuration.