[hibernate-dev] Loggers and categories

[Steve Ebersole]

For those that did not see the Scanning/Jandex Pull Request I sent earlier,
it includes some initial proofing along these lines.

Essentially I started creating a set of distinct, functional-based
MessageLoggers which log to dedicated categories per functional area.
 Samples are by far the best way to explain this I think.  So in the
initial work related to Jandex building and Scanner changes I defined 2
such functional MessageLoggers:  DeprecationLogger and UrlMessageBundle[1].

@MessageLogger( projectCode = "HHH" )

@ValidIdRange( min = 90000001, max = 90001000 )

public interface DeprecationLogger {

    public static final DeprecationLogger DEPRECATION_LOGGER =
Logger.getMessageLogger(

            DeprecationLogger.class,

            "org.hibernate.orm.deprecation"

    );


    /**

     * Log about usage of deprecated Scanner setting

     */

    @LogMessage( level = INFO )

    @Message(

            value = "Found usage of deprecated setting for specifying
Scanner [hibernate.ejb.resource_scanner]; " +

                    "use [hibernate.archive.scanner] instead",

            id = 90000001

    )

    public void logScannerDeprecation();

}


First notice the DEPRECATION_LOGGER member.  This defines the distinct
category ("org.hibernate.orm.deprecation") that these message will be
logged to.  This is the change from using the names of the Class from which
this method gets called.  Each of these message logger categories will be
documented in the logging topical guide, which altogether makes it easier
for users to enable/disable these messages and get the information.

Notice I also started making use of the @ValidRange annotation to identify
the message ids each logger "reserves".


[1] The difference in naming is because I am not really yet sure how to
best handle the schizophrenic nature of these "loggers" that also just
format (with i18n) mesages for creating exceptions.  To me a call like
`throw new SomeException( someLogger.someMessage() )` just "feels" wrong.
 FWIW I did change the convention up a little in terms of the method names
(well i actually started a convention) such that methods that log start
with the prefix `log`; e.g. logMalformedUrl(..) versus just malformedUrl(..)



On Thu, Apr 17, 2014 at 11:05 AM, Steve Ebersole <steve at hibernate.org>wrote:

> Wanted to revisit something that's been bothering me ever since we moved
> to JBoss Logging : the definition of loggers.
>
> While I think we have always understood that there are really 2 different
> audiences for log messages, I think I have come to have a more clear
> understanding of what that means and its implications.
>
> We have log messages intended for usage scenarios and log messages
> intended for debugging scenarios.  To me, the first groups is represented
> by the JBoss Logging MessageLogger messages.  The second group are the
> things we simply "pass through" to the underlying log backend (trace, debug
> messages).
>
> In both cases we currently use the name of the Class initiating the log
> message as the "category name".  While I think that is absolutely the
> correct thing to do in the case of that second group, what about the first
> group?  For that first group I wonder if its better to have "logical
> category names" more like 'org.hibernate.orm.deprecations' and
> 'org.hibernate.orm.mapping'...  The idea being that its easier to switch
> these grouped categories on/off.
>
>