How to log in JBoss projects

Core Message Format

All user directed logging messages (INFO or higher) that are produced by JBoss frameworks must follow the same format described below.  Messages generated by thirdparty code should be caught by the consumer, which will typically be a JBoss project. The consumer should then map the thirdparty framework error into something that is both meaningful to the user and follows this convention.

 

Severity
Category
Event ID

Parmaterized & Localized Message

 

Example:

 

ERROR [EARDeployer] DEPLOY045434 Application name was not specified in the application.xml deployment descriptor.

 

One Message per Error

For any distinct problem, there should appear in the logs exactly one ERROR (or FATAL) level message and it should convey information useful to the user rather than low level information.  However, any number of debug level messages could occur since they are not typically observed by users. To use an example, if a series of JGroups errors happen that all indicate loss of an AS peer, instead of logging a bunch of confusing message like "suspect verified", the AS clustering code should handle the error and instead say something like "Member foo of the AS cluster X has stopped responding".

 

Stack Traces

Stack traces are not useful to administrators unless they indicate an actual bug in JBoss. Most user errors (validation, bad configuration, etc) should not dump a stack trace. Instead specifics about the problem are more useful (e.g. Invalid attribute specified in foo.xml:5) The obvious exception is when an exception thrown by user code is passed to the log, this should of course be preserved. In the case that a user exception is passed through, the user exception should be at the top of the trace, and not in a caused-by. This essentially means don't wrap a user exception unless you have to, and when you do, correct the stack trace.

 

Severity

 

Level
Description
Event Code Required
Localized
FATALA fatal error indicates a critical service failure. This indicates to the user that requests from the module issuing this message can not be serviced.YY
ERRORAn error indicates a problem that requires the attention of the user to. It must have a clear message that describes the problem from the user's perspective.YY
WARNA warning indicates that a potential non-fatal problem has been identified and the user needs to be notified. A typical use-case is catching conflicting/unusual configuration values. The warning should clearly indicate the source, for example a specific file, etc.YY
INFOA message used to convey crucial information about the state of a service. Action from the user is not required. A typical example is lifecycle information, such as "Web Server Started"YY
DEBUGA debugging message for JBoss internal use that provides extra information about the global state of a service. It should never be used to log information triggered by an individual request. This prevents load triggered log growth.NN
TRACEA JBoss internal debugging message that is directly correleated to the handling of a request. When this severity level is enabled, log file growth will become directly proportional to the number of requests processed by the service. Since generation of these messages impacts request processing time, the enabled error level must be checked before logging at trace levelNN

 

Category Format

A category may be either a class name, or a generic category. The preferred approach is the latter since it allows for log messages to survive code restructuring. Categories can also be reused by different projects / modules.

 

Owning Package
.
Category

 

Examples:

org.jboss.xnio.ssl

org.jboss.as.configuration

 

Event ID Format

Event IDs are globally unique identifiers that can be used to quickly communicate the problem, as well as allow access to detailed support materials relating to the event. In addition they function as the "resource key" for localized messages. Event IDs represent the combination of a unique subsystem code, and a subsystem specific event code. All subsystem codes must be registered by an owner, and documented on this page. A subsystem owner is responsible for maintaining the list of allowed event codes for the owner's  subsystem. Event codes are zero padded to improve readability.

 

Subsystem/Project Code
Zero Padded 6 Digit Event Code

 

 

Examples:

CL001234

DEPLOY045434

BOOT000001

 

 

Registered Subsystem Codes

Subsystem Code
Description
Owner
WELDWeld project related eventsPete Muir
HHHHibernate CoreSteve Ebersole
HSEARCHHibernate SearchEmmanuel Bernard
HVHibernate ValidatorEmmanuel Bernard
ARJUNAJBossTSJonathan Halliday
JBTJBoss Tools (eclipse)Max Andersen
RFRichFacesJay Balunas
IJIronJacamarJesper Pedersen
TTALETattletaleJesper Pedersen
HCANNHibernate Commons AnnotationsEmmanuel Bernard
ISPNInfinispanGalder Zamarreño
SM

Seam (prefix only, modules append

to this, e.g. SMSEC = Seam Security)

Shane Bryzak
JBASJBoss Application ServerJames Perkins
MODEModeShapeRandall Hauch
OGMHibernate OGMEmmanuel Bernard
JGRPJGroupsBela Ban