Syslog:	White Paper	FAQ	Examples	JavaDoc	Classloader

Protomatter Syslog FAQ

Nate Sammons - January, 2002
Covers Release 1.1.7

Table of contents

Do you have any examples of XML configuration files?

Yes. They are over here.

I tried the code examples and they didn't compile or run.

Make sure that the Protomatter Classes jar file (protomatter-version.jar) is in your system (or IDE's) CLASSPATH environment variable. If it isn't there, you can't compile or run any of the examples.

I can't see any output and I'm calling .info() and .debug() logging methods.

By default, Syslog ignores messages below the WARNING level. To change this, you must reconfigure the policy. If you don't want to mess with config files yet, then you can put the following code in your application:


  import com.protomatter.syslog.Syslog;  

  ...

  Syslog.setLogMask("DEBUG");

This instructs Syslog to log messages at or above the DEBUG severity.

If you're using XML configuration files, your default Syslog configuration looks like this:


  <?xml version="1.0" encoding="UTF-8"?>
  <Syslog defaultMask="WARNING">
    <Logger name="PrintWriterLog.err" class="com.protomatter.syslog.PrintWriterLog">  
      <Format class="com.protomatter.syslog.SimpleSyslogTextFormatter">
        <showChannel>false</showChannel>
        <showThreadName>false</showThreadName>
        <showHostName>false</showHostName>
        <dateFormat>HH:mm:ss MM/dd</dateFormat>
        <dateFormatCacheTime>1000</dateFormatCacheTime>
        <dateFormatTimeZone>America/Denver</dateFormatTimeZone>
      </Format>
      <Policy class="com.protomatter.syslog.SimpleLogPolicy">
        <channels>ALL_CHANNEL</channels>
        <logMask>INHERIT_MASK</logMask>
      </Policy>
      <stream>System.err</stream>
    </Logger>
  </Syslog>

You can get this default configuration from Syslog by typing the following command:


  java com.protomatter.syslog.xml.SyslogXML

The areas to change are highlighted in red. If you change the WARNING value, it will affect all loggers that have their logMask value set to INHERIT_MASK. If you change just the INHERIT_MASK value, then it just affects the logger you change it on.

If you set this value to the name of a log level (DEBUG, INFO, WARNING, ERROR or FATAL), then messages at or above that level will be logged.

You can also set it to a list of levels to pay attention to. If, for example, you set it to "=INFO,=ERROR" then only message at the INFO or ERROR levels are logged.

After saving a changed version of the configuration file, you can configure Syslog at runtime using the file by executing the following code in your application:


  import java.io.File;
  import com.protomatter.syslog.xml.SyslogXML;

  ...

  SyslogXML.configure(new File("filename.xml"));

If you're using an application server or a servlet container, you may be able to use either the SyslogInitServlet or SyslogT3Startup may be able to configure Syslog when your server or WebApp initializes.

What's the story with buffering and file-related loggers?

In version 1.1.6 and later versions, by default each logger flushes its buffer every time a message is sent to it. This was not the case in 1.1.5, where buffering was on by default. Loggers that write to files (FileLog, LengthRolloverLog and TimeRolloverLog) can also use buffered output streams to be more efficient while writing to files.

The problem with using buffers is that if messages suddenly stop coming into the logger (your web application gets less traffic, for instance), it won't flush its buffer. Maybe there's no messages in it, but maybe there's 5 or 10 -- who knows? There's no good way to determine if a buffer should be flushed (because it's impossible to know that a log message will be coming soon and that it might be better to wait 50ms before flushing the buffer).

To solve this problem, you can do a couple of things:

Add the <autoFlush>true</autoFlush> configuration element to the XML configuration info for the loggers. This will cause the log to be written to each time a message comes in. This is the same as calling the setAutoFlush(true) method on the logger if you're configuring things programatically.
Add the flushThreadInterval attribute (measured in milliseconds) to your XML file's <Syslog> element. This has the same effect as calling the Syslog.setFlushThreadInterval(timeout) method.

If you choose to turn off buffering (the default) then the log will always be completely up to date with the latest messages that have arrived. If you want to do buffering, using the flush thread sleep interval parameter will cause syslog to start a background thread that continuously flushes the buffers in all loggers and then sleeps for the number of milliseconds you tell it to.

The effect of using this is that you'll get buffered I/O to log files, and the log will never be farther behind than the sleep interval. Be careful not to set this value too low (below 5000 is probably not a good idea).

Does Syslog work with JBoss?

Yes. The code in the jmx package takes care of loading and configuring Syslog when JBoss boots.

Does Syslog work with <insert-random-application-server-here>?

Almost certainly. However, the only application server that Syslog has a hook into is BEA WebLogic Server (using the SyslogT3Startup class).

If the application server you're working with supports the idea of a class that's loaded and run when the server starts, you should be able to write your own Syslog initializer class to tie into your application server. Basically, the class should call SyslogXML.configure(...) to configure Syslog from an XML file.

If your application server supports the Servlet 2.2 specification, then you can use the SyslogInitServlet to initialize syslog when a WebApp starts. Please see the JavaDoc for that class for more information. Please note that even if you aren't building a web-based application, you can still use the servlet to configure Syslog when your app server boots.

I get an exception saying something about SAX parsers when configuring Syslog using XML files -- help!

Sometimes, the JDom SAXBuilder class can get confused about what parser to use -- this is generally caused by JAXP being confused. Anyway, it's then possible for Syslog to try and use the wrong XML parser. Fixing this is easy. Just add the following command-line option when running your application:


  java ... -DSyslog.xml.parser=org.apache.xerces.parsers.SAXParser ...

If you're using the SyslogXML.configure(File) method to configure Syslog, you can pass the name of the SAX parser class into that method, like this:


  File file = new File("config.xml");
  SyslogXML.configure(file, "org.apache.xerces.parsers.SAXParser");

That should fix the problem.

What needs to be done to localize Syslog?

Localizing Syslog is easy -- figure out the name of your locale (look at the JavaDoc for java.util.Locale), and then create a file called "com/protomatter/syslog/Syslog_locale.properties" and place it in your CLASSPATH. You should take a copy of com/protomatter/syslog/Syslog.properties and translate each message into the new language.

You can test your translation by using the MessageConstants utility like this:


  java com.protomatter.syslog.MessageConstants

That program will look through all the message constants and display their value for the current locale. You will see output like this:


  Constants class: com.protomatter.syslog.MessageConstants  
  Locale:          en_US

  Variable name:   FLUSH_LOGGERS_MESSAGE
          value:   FlushLoggers
       property:   Flushing all loggers

  Variable name:   SHUTDOWN_SYSLOG_MESSAGE
          value:   ShutdownSyslog
       property:   Shutting down Syslog

  ...

  Variable name:   JMX_CANNOT_LOAD_FILE_MESSAGE  
          value:   JMX.CannotLoadFile
       property:   {0}: Cannot load file "{1}"

This will allow you to debug the messages and make sure they are all there for the new locale.

I'm getting errors using the MailLog with MS Exchange.

The MailLog can't talk to MS Exchange servers if they require authentication to relay SMTP mail traffic. You need to allow non-authenticated SMTP connections.