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