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 third-party code should be caught by the consumer, which will typically be a JBoss project. The consumer should then map the third-party framework error into something that is both meaningful to the user and follows this convention.
| Severity | Category | Event ID | Parameterized & 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 |
|---|---|---|---|
| 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 correlated 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 |
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 |
|---|---|---|
| WELD | Weld project related events | Pete Muir |
| HHH | Hibernate Core | Steve Ebersole |
| HSEARCH | Hibernate Search | Emmanuel Bernard |
| HV | Hibernate Validator | Emmanuel Bernard |
| ARJUNA | JBossTS | Jonathan Halliday |
| JBT | JBoss Tools (eclipse) | Max Andersen |
| RF | RichFaces | Jay Balunas |
| IJ | IronJacamar | Jesper Pedersen |
| TTALE | Tattletale | Jesper Pedersen |
| HCANN | Hibernate Commons Annotations | Emmanuel Bernard |
| ISPN | Infinispan | Galder Zamarreño |
| SM | Seam (prefix only, modules append to this, e.g. SMSEC = Seam Security) | Shane Bryzak |
| JBAS | JBoss Application Server | James Perkins |
| MODE | ModeShape | Randall Hauch |
| OGM | Hibernate OGM | Emmanuel Bernard |
| JGRP | JGroups | Bela Ban |
Comments