[hibernate-dev] Loggers and categories

[Steve Ebersole]

So a few follow ups question here.

First, wrt @MessageLogger/@LogMessage versus @MessageBundle do we want to
split these?  The cliff notes version is that @MessageBundle (and
@Message) is used to define parameterized messages for translation;
@MessageLogger/@LogMessage further says that resulting message is logged
(rather than returned to build an exception, etc).  Personally I think I
prefer to keep them together functionally.  Previously I only listed
DeprecationLogger, but UrlMessageBundle shows a mixed usage:


@MessageLogger( projectCode = "HHH" )
@ValidIdRange( min = 10000001, max = 10001000 )
public interface UrlMessageBundle {
  public static final UrlMessageBundle URL_LOGGER = Logger.getMessageLogger(
  UrlMessageBundle.class,
            "org.hibernate.orm.url"
  );

    /**
     * Logs a warning about a malformed URL, caused by a {@link
URISyntaxException}
  *
  * @param jarUrl The URL that lead to the {@link URISyntaxException}
  * @param e The underlying URISyntaxException
  */
  @LogMessage( level = WARN )
  @Message( value = "Malformed URL: %s", id = 10000001 )
  void logMalformedUrl(URL jarUrl, @Cause URISyntaxException e);

    ...

    /**
  * Access to the exception message used when a URL references names a file
that does not exist.
  * <p/>
  * TODO : detail when this is a warning {@link #logFileDoesNotExist}
versus an exception...
  *
  * @param filePart The "file part" that we gleaned from the URL
  * @param url The given URL
  *
  * @return The message
  */
  @Message( value = "File [%s] referenced by given URL [%s] does not
exist", id = 10000005 )
  String fileDoesNotExist(String filePart, URL url);
}

I think that "mixed" part is ok.  Anyone feel any different?

As Hardy and I discussed on the Pull Request (thanks for your thoughts
Hardy!)... we will need to do a good job identifying the reserved ids.
 Probably this involves a registry of the reserved keys on a wiki or
document somewhere, probably linking to the FQN of the MessageLogger that
reserved the range (along with a discussion of the loggers intent).  But I
wonder too if we want to categorize the ids in any way.  What I mean by
that is like what SQL does for its "error codes".  I don't have any clear
idea of categories atm; just throwing it out there.





On Thu, May 8, 2014 at 9:49 AM, Steve Ebersole <steve at hibernate.org> wrote:

> 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.
>>
>>
>