Adding a Logging Category | JBoss: A Developers Notebook

You've seen how appenders define logging destinations and filter log messages with a threshold. Now we will look at how to control the level of the log messages that are generated. Controlling the level of generated messages is important, both for performance and for keeping the server.log file from being flooded with messages that are more detailed than you need at any given time.

How do I do that?

All log messages are generated inside of named categories. Categories are hierarchical, allowing you to define appenders that cover a wide range of messages, and then turn around and define categories that target specific areas. The naming convention is similar to that used for Java classes and packages; category names are case-sensitive and use a dot as a separator. In fact, the standard convention is to name categories after the Java class or package in which they are being generated.

Here are a few categories from the log4j.xml file:

     <!-- Limit the org.apache category to INFO as its DEBUG is verbose -->     <category name="org.apache">         <priority value="INFO"/>     </category>     <!-- Limit the org.jgroups category to WARN as its INFO is verbose -->     <category name="org.jgroups">         <priority value="WARN"/>     </category>     <!-- Limit apache axis to INFO as its DEBUG is even more verbose -->     <category name="org.jboss.axis">         <priority value="INFO"/>     </category>

Note: All generated log messages go to server.log. Individual category definitions are the only filter on that file.

These categories specify the minimum priority of messages that will be generated. The purpose of the categories is to limit the log messages produced by components to a level that makes sense. Although you can control the threshold on the appender, INFO messages on one component may be significantly more verbose than DEBUG messages on another. Filtering at the category level allows you to compensate for that disparity.

The ToDo application does some very basic logging in the beans using log4j. In TaskBean, for example, a log4j Logger instance is obtained using the name of the bean class as the category name:

     import org.apache.log4j.Logger     // ...     static Logger logger = Logger.getLogger(TaskBean.class);

The ejbCreate( ) method logs its activity using the debug( ) method on the logger instance:

Note: JBoss provides an extension to the log4j Logger class in org.jboss.logging. Logger. The JBoss Logger provides access to the trace-level logging extension used in the server for log statements more detailed than normal DEBUG logging.

     /** @ejb.create-method */     public String ejbCreate(String user, String name)         throws CreateException     {         setId(TaskUtil.generateGUID(this));         setName(name);         setUser(user);         setStartedDate(new Date(  ));         logger.debug("creating task " + getId(  ) + " for user " + user);         return null;     }

When you access the application and create a task, the following statement gets logged to server.log showing the generated ID of the task being created:

     2005-04-11 20:59:30,782 DEBUG [com.oreilly.jbossnotebook.todo.ejb.TaskBean]     creating task 3421f6bfc0a80064009b0b39004cf63c for user pinky

If you decide that you don't want EJB debug messages generated at all, you need to add a category for the component that limits the generated messages. The following category limits EJB debug messages to INFO:

     <category name="com.oreilly.jbossnotebook.todo.ejb">         <priority value="INFO" />     </category>

Note: The message doesn't show up on the console since the threshold on the console is INFO.

Categories are hierarchical, and a category inherits its configuration from parent categories. You could also limit logging across the entire ToDo application by limiting a parent category:

     <category name="com.oreilly.jbossnotebook.todo ">         <priority value="INFO" />     </category>

The configuration on a category always takes precedence over the configuration on a parent category. It is possible to limit the application to INFO while allowing DEBUG messages from the EJB component, or to log the entire application at the DEBUG level while limiting only the EJBs to INFO, by providing configurations for both categories.

The inheritance chain goes all the way back to a special root category. The root category is configured using a root element. The JBoss-provided log4j.xml file contains a root element that looks like this:

     <root>         <appender-ref ref="CONSOLE" />         <appender-ref ref="FILE" />     </root>

In this case, the root category doesn't declare a default priority. If you need a default log level for the entire server you can configure it there, but it is generally advisable to be more specific with categories.