Robust event
logging with Syslog - JavaWorld April
2001
Tutorial Details:
Robust event logging with Syslog
Robust event logging with Syslog
By: By Nate Sammons
Syslog is a fast, flexible, and easily extendable logging system
n important part of any project, logging can be used as a debugging tool during development, and a troubleshooting tool once a system has been deployed in a production environment. Because most developers only implement logging if time permits, it is often implemented haphazardly. However, logging provides a way to see what is happening, good or bad, inside a running system. As such, it should be addressed with care and forethought rather than as a last minute burden.
Syslog is an open source logging system that allows programmers to easily add diagnostic and status logging to their Java programs. It separates the act of logging an event from the actual handling of that event. Simple configurations may instruct Syslog to write all log messages to the console. In more elaborate configurations, Syslog can separate messages by almost any criteria, including severity, and send them to different files. These files can rotate based on time or file size and send email across a network via Remote Method Invocation (RMI) or Java Message Service (JMS). API calls allow configuration modification at runtime, and Syslog can save running configuration to an XML file for further refinement at a later time. In the case of application servers hosting multiple applications running in the same VM, message channels allow Syslog to route log messages coming from each application and handle them accordingly.
A list of log message handlers essentially constitutes Syslog. Each handler has a log policy that determines what messages it should consider. If the policy determines that the handler should deal with a given message, the logger uses a message formatter to prepare the message, and the handler then writes the message to a file or sends an email. The architecture is based on interfaces so that custom modules can replace each step.
Syslog provides the following features:
Simple, all-static logging API
Message severities
Pluggable log message handlers
Pluggable log-formatting modules for each handler
Pluggable log policy modules for each handler
Arbitrary log channels
A configuration that can be modified on the fly while running
A running configuration that can be written to a file for reload later
Email integration
Remote logging capabilities -- using RMI
JMS integration
Licensed under the GNU LGPL v2, Syslog is free for commercial and noncommercial use, with source code included. Though it was originally based loosely on the Unix Syslog facility, it now shares only its name. In this article, you'll learn how to easily integrate the Syslog package into your system by adding simple instrumentation to your Java code. You'll also uncover more elaborate ways to leverage Syslog in projects as an integral part of new system development. Syslog allows developers to concentrate on developing application code, not on how an operations department or hosting provider will handle logging.
Syslog for developers
Two groups of people will benefit from a logging system: developers and operations staffs. Developers need to be able to instrument their code with little effort; otherwise they'll never perform event logging. As you'll observe, you can instrument code with Syslog calls in a number of ways, ranging from the simple to the complicated.
Basic usage
Anytime developers want to issue a message to Syslog, they simply call a static method on the com.protomatter.syslog.Syslog class. There's no need to carry around a reference to an instance of Syslog to make calls. That greatly simplifies usage, as you also don't need to keep references to a logging object -- simply call static methods and that's it.
You can use 48 methods in the Syslog class to issue messages; however, it's unlikely that you will use most of them. All of those methods are pass-throughs to a single method that takes six arguments; the other 47 are simply included for convenience. Don't be intimidated by the large number: Syslog resembles a Swiss army knife in that respect -- though it features tools that you rarely use, they will release you from a jam when the time comes.
Developers usually mark up their code with log messages by peppering it with calls to System.out.println() ; they invariably have to go back and comment those calls out before the system goes into production. If some calls are missed, operations will ask why the system prints "I'm in here" continuously while running.
One way to become accustomed to working with Syslog is to replace code like this:
System.out.println("I'm in here");
with code like this:
Syslog.debug(this, "I'm in here");
That approach requires less work than calling System.out.println() -- you actually need fewer keystrokes; and it's also more useful. Instead of receiving output like this:
I'm in here
if Test.java made the call, Syslog will produce the code fragment below:
10:52:53 01/08 [DBUG] Test I'm in here
If Syslog is set to log the channel and thread name for each message, the output will look like this:
10:56:44 01/08 [DBUG] [DEFAULT_CHANNEL] [main] Test I'm in here
Later, when the system goes into production, messages at the "debug" severity level disappear, and nobody will wonder why the system prints "I'm in here" constantly.
Java code is often littered with exception-handling code and, unfortunately, many developers simply catch an exception and call its printStackTrace() method, which sends the stack trace to the System.err stream. Syslog features a utility method for exceptions: calling Syslog.log(this, x) where x is a java.lang.Throwable will produce output like the code below:
10:40:32 01/08 [EROR] Test java.lang.Exception: Crap!
java.lang.Exception: Crap!
at Test.bar(Test.java:37)
at Test.foo(Test.java:28)
at Test.main(Test.java:12)
The toString() method's output prints as the short description, a stack trace prints as the message detail, and the whole thing logs at the ERROR level. That proves a much better approach than spreading calls to x.printStackTrace() all over the code. As you'll see later, Syslog can route those kinds of messages to a separate log or even email them to a pager.
Message severity levels
Syslog messages each have an associated severity level that show the importance of each message. The levels are:
DEBUG
Generally referred to as breadcrumbs -- useful for letting the developer leave little hints here and there during the initial coding and debugging process.
INFO
Provides informational messages about what's happening, with notable events including user login and logout.
WARNING
Signifies that something bad has happened, but the system will attempt to recover from it. This message usually indicates that something is starting to go wrong.
ERROR
Indicates that something bad has happened, but the error won't cause the system to fail in general. A specific task may have failed, and some user may have received an error, but the system will keep running. Exceptions are generally logged at this level.
FATAL
Indicates that something horribly bad has happened, and most likely, the system is of little use to anyone. Someone should probably be paged, and sirens should sound.
It's important to actually use the different severity levels where they are appropriate. If you log every message in the system at the DEBUG level, the operations team will likely ignore all messages, even those that warrant immediate attention; that defeats the purpose of using severities in the first place.
API methods
Before we go further, let's look at the most commonly used logging methods that are available in the Syslog class. They fall into two groups:
xxx () and xxx ToChannel() : where xxx is DEBUG , INFO , WARNING , ERROR , or FATAL . These are shortcut methods for each severity and have the following forms:
xxx (Object logger, Object msg)
xxx (Object logger, Object msg, Object detail)
xxx ToChannel(Object logger, Object chan, Object msg)
xxx ToChannel(Object logger, Object chan, Object msg, Object
detail)
log() , which has the following forms:
log(Object logger, Throwable t)
log(Object logger, Throwable t, int level)
log(Object logger, Object msg, Object detail, int level)
log(Object logger, Object chan, Object msg, Object detail, int level)
Each of the above methods is also overloaded to take an InetAddress object as a parameter -- I have omitted them for clarity. It's fairly safe to assume that you will never use them, as Syslog uses them internally for remote logging. The rest of the methods' arguments are:
Object logger
The object making the log request. Generally, the logger argument is simply this , as in the example Syslog.debug(this, "I'm in here"); . If there's no this reference where the logging call is made, as in a static method, simply pass in the current class object. For example, in the MyClass class, simply pass in MyClass.class instead of this . If you pass in a String , it will be used rather than that class name.
Throwable t
The log methods above that explicitly take a Throwable as an argument are convenience methods. The toString() method on Throwable is called, and the result is used as the msg argument. If the method takes a Throwable and does not take a level argument, the level defaults to ERROR . The Throwable itself is used as the detail argument.
Object msg
A short description of the message. The toString() method of whatever passes in will be called.
Object detail
If included, this argument is treated as a longer explanation of the message. If the object passed as this argument inherits from Throwable , then a stack trace is used.
int level
The severity of the message. There are constants defined in the Syslog class: Syslog.DEBUG , Syslog.INFO , Syslog.WARNING , Syslog.ERROR , and Syslog.FATAL .
Object channel
The channel name for the message, which can be one of two things: St
Read
Tutorial at: Click here to view the tutorial
Rate Tutorial: Robust event
logging with Syslog - JavaWorld April
2001
View Tutorial: Robust event
logging with Syslog - JavaWorld April
2001
Related
Tutorials:
 SQLJ: The 'open
sesame' of Java database applications
SQLJ: The 'open
sesame' of Java database applications
|
Log it or loose
it
Log it or loose
it
|
Cut down on
logging errors with Jylog
Cut down on
logging errors with Jylog
|
J2EE or J2SE?
JNDI works with both
J2EE or J2SE?
JNDI works with both
|
Publish
Publish event-driven Web content with JSP custom tags
|
Create your own type 3 JDBC driver, Part 3
Create your own type 3 JDBC driver, Part 3
|
Java Tip 132: The
taming of the thread
Java Tip 132: The
taming of the thread
|
J2SE 1.4
breathes new life into the CORBA community, Part
4
J2SE 1.4
breathes new life into the CORBA community, Part
4
|
Customize
SwingWorker to improve Swing GUIs
Customize
SwingWorker to improve Swing GUIs
|
Test email components in your software
Test email components in your software
|
good
design pattern
good
design pattern
|
Tracing in a multithreaded, multiplatform environment
Tracing in a multithreaded, multiplatform environment
In \"Use a consistent trace system for easier debugging,\" Scott Clee showed you how to trace and log from a custom class to provide a consistent tracing approach across your applications. This approa
|
FindBugs, Part 2: Writing custom detectors
FindBugs, Part 2: Writing custom detectors
How to write custom detectors to find application-specific problems
In the first article in this series, I showed you how to set up and execute FindBugs. Now we'll take a look at FindBugs' most powerful fea
|
Handling Events in JavaServer Faces, Part 1
In this excerpt from the book, author Hans Bergsten looks at the JSF event model, using examples to help explain what\'s going on "under the hood."
|
Building Highly Scalable Servers with Java NIO
Building Highly Scalable Servers with Java NIO
I/O Event Handling
The I/O architecture of our router was strongly inspired by the Swing event-dispatch model. In Swing, events generated by the user interface are received by the JVM and stored in an even
|
Reporting Application Errors by Email
Reporting Application Errors by Email
It is common practice for server-side applications to log messages to files on the server's file system. These logs are a vital source of information for system administrators and the application development team. If
|
OIL (Objects in a Line)
OIL (Objects in a Lile) provides a queue API and its implementation which is required by many server applications which stores client requests permanently in order.
OIL provides:
Queue which provides sequential access.
Index which provides random acce
|
100 % java open-source cryptographic software libraries.
Cryptixtm is an international volunteer effort to produce robust, open-source cryptographic software libraries. Cryptix products are free, both for commercial and non-commercial use and are being used by developers all over the world. Development is ...
|
Write custom appenders for log4j
The Apache Software Foundation's log4j logging library is one of the better logging systems around. It's both easier to use and more flexible than Java's built-in logging system.
|
Open Source Web Frameworks in Java
Open Source Web Frameworks in Java
Open Source Web Frameworks in Java
Struts
Struts Frame work is the implementation of Model-View-Controller (MVC) design pattern for the JSP. Struts is maintained as a part of Apache Jakarta project and is open
|
|
|
|
