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.
Parmaterized & Localized Message
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 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.
|Level||Description||Event Code Required||Localized|
|FATAL||A fatal error indicates a critical service failure. This indicates to the user that requests from the module issuing this message can not be serviced.||Y||Y|
|ERROR||An 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.||Y||Y|
|WARN||A 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.||Y||Y|
|INFO||A 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"||Y||Y|
|DEBUG||A 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.||N||N|
|TRACE||A 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 level||N||N|
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.
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|
Registered Subsystem Codes
|WELD||Weld project related events||Pete Muir|
|HHH||Hibernate Core||Steve Ebersole|
|HSEARCH||Hibernate Search||Emmanuel Bernard|
|HV||Hibernate Validator||Emmanuel Bernard|
|JBT||JBoss Tools (eclipse)||Max Andersen|
|HCANN||Hibernate Commons Annotations||Emmanuel Bernard|
Seam (prefix only, modules append
to this, e.g. SMSEC = Seam Security)
|JBAS||JBoss Application Server||James Perkins|
|OGM||Hibernate OGM||Emmanuel Bernard|