Java Doc for Syslog.java in  » Development » protomatter » com » protomatter » syslog » Java Source Code / Java DocumentationJava Source Code and Java Documentation

java.lang.Object    com.protomatter.syslog.Syslog Syslog public class Syslog (Code) This class implements a system-wide logging utility. Please read the Syslog Whitepaper for more information. It allows a program to log messages and objects at different severity levels in a standardized way. The implementation of the log is specified by an object which implements the Syslogger interface. You can have multiple log implementations, and each can have it's own log mask or can inherit it's log mask from Syslog (this is the default behavior). There are 5 severity levels: DEBUG, INFO, WARNING, ERROR, FATAL. They correspond to the numbers 0, 4, 8, 12, and 16, respectively. You can enable logging for any combination of these levels. The default setting logs only WARNING and above. Quickie introduction and usage: Anywhere you're doing this: System.out.println("Some message"); Do this instead: Syslog.debug(this, "Some message"); If you're in a static method, do this: Syslog.debug(MyClass.class, "Some message"); If you like what this gets you, start playing around with different log levels (call "Syslog.info(...) " and others). If you like that, start playing around with channels and configuring the loggers and other things. Syslog has a very robust API and can be bent around to do all sorts of things, but it does not have to be complicated to use even though it can be configured in all sorts of complicated ways. More involved usage examples:

// log simple message at DEBUG level // pass 'this' as the object performing the logging Syslog.log(this, "simple message", null, Syslog.DEBUG); // this performs toString() on object 'obj', and prints a message Syslog.log(this, "logging object", obj, Syslog.INFO); // logs 'exception' and its stack trace at ERROR level Syslog.log(this, exception); // here's how you log in a static method -- pass the class object Syslog.log(MyClass.class, "logging in MyClass"); // shortcuts for each log level Syslog.debug(this, "foo"); Syslog.debug(this, "foo", bar); Syslog.info(this, "foo"); Syslog.info(this, "foo", bar); // log to multiple channels (the "foo" and "bar" channels) Syslog.infoToChannel(this, new String[]{"foo", "bar"}, "My message");

There are basically three types of methods on this class for issuing log messages. Whenever a channel name is not specified, the channel DEFAULT_CHANNEL is used.

Whenever a channel is specified, it is an Object . This argument can either be a String or an array of String (in which case, the message will be sent out to multiple channels).

log(...);


They have 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);
log(InetAddress host, Object logger, Throwable t);
log(InetAddress host, Object logger, Throwable t, int level);
log(InetAddress host, Object logger, Object msg, Object detail, int level);
log(InetAddress host, Object logger, Object chan, Object msg, Object detail, int level);


xxx(...);


Where "xxx " is "debug ", "info ", " warning ", "error ", or "fatal " These are shortcuts to the log(...) method for each log level. They have the following forms:

xxx(Object logger, Object msg);
xxx(Object logger, Object msg, Object detail);
xxx(InetAddress host, Object logger, Object msg);
xxx(InetAddress host, Object logger, Object msg, Object detail);


xxxToChannel(...);


Where "xxx " is "debug ", "info ", " warning ", "error ", or "fatal " These are shortcuts to the log(...) method for each log level, and to a specific channel. They have the following forms:

xxxToChannel(Object logger, Object chan, Object msg);
xxxToChannel(Object logger, Object chan, Object msg, Object detail);
xxxToChannel(InetAddress host, Object logger, Object chan, Object msg);
xxxToChannel(InetAddress host, Object logger, Object chan, Object msg, Object detail);

You may want to look at the Channel class. Some people prefet its API.

When the Syslog class is loaded, the following happens:

1. If the Syslog.level system property is set, it is passed to Syslog.setLogMask(...) (otherwise it defaults to WARNING ).

2. A PrintWriterLog named "PrintWriterLog.err " is added using Syslog.addLogger(...) and connected to the System.err PrintStream.

3. If the Syslog.file system property is set, it is interpreted as a filename and another PrintWriterLog is added and connected to that file. The logger is named "PrintWriterLog.file ".

If you want to change these defaults, you can use the getLoggers() , addLogger(...) , removeLogger(...) and removeAllLoggers() methods to change what loggers are registered with Syslog .

Syslog provides background work queues for loggers that need to perform their operations asynchronously. For instance, the MailLog performs its policy check synchronously and then if it decides that a message will actually need to be sent, it asks syslog to perform the operation asynchronously. This is far more efficient than doing everything in the background because the amount of synchronization necessary to add work to a queue is usually larger than a policy check.

Please read the Syslog Whitepaper for more information on Syslog.

author:
   nate
See Also:   Syslogger
See Also:   SyslogChannelAware