6:05 p.m.
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.
4:49 p.m.
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(a)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.
7:19 p.m.
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(a)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(a)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.
>
>
8:20 p.m.
On 8 Jan 2014, at 19:19, Steve Ebersole <steve(a)hibernate.org> wrote:
So a few follow ups question here.
First, wrt @MessageLogger/@LogMessage versus @MessageBundle do we want to
split these?
For what it’s worth, we do the split in Validator. I think I prefer it this way, but have
no strong
feeling about it.
—Hardy
3892
days inactive
3913
days old
3 comments
2 participants
participants (2)
-
Hardy Ferentschik -
Steve Ebersole