improving the manual pages

[Remko Popma <re...@yahoo.com>]

On the log4j user mailing list I encountered a user who had made a few wrong turns, config-wise, and had trouble getting back on track.

One issue was that by default the File appender is buffered but does not flush.
So his log file stayed empty and he had trouble figuring out why.

Should we change the examples a little?
* use bufferedIO=false in all File appender examples?

* add a comment that the root logger is mandatory (LOG4J2-219)

Also I would like to propose (and opinions may differ on this one)
to avoid using layouts that use location in the examples,
unless the example is used to explain how location works.
(E.g., the API > Flow Tracing page would need location layout examples.)

Currently most examples use %C and %M and I would greatly prefer that the examples use %c and other layouts that do not include location. 

I believe that many people will start using Log4j by copying an example and only read the manual when they get stuck.
I would hate to give first-time users the impression that Log4j is slow and have our own example configs to blame... :-)


On the same topic, in the layouts page I would like to add remarks describing performance impact to the attributes that include location.

Thoughts?

Re: improving the manual pages

[Ralph Goers <rg...@apache.org>]

Yes. But I was thinking there might be a section heading somewhere called Location Information that specifically identifies each of the location patterns and discusses the overhead of each. This is one area where I miss the C preprocessor as the location stuff could have been hidden in a macro so it could be passed along at compile time.

Sent from my iPad

On Apr 27, 2013, at 2:52 AM, Remko Popma <re...@yahoo.com> wrote:

> Ok, then to summarize my understanding for LOG4J2-219 the solution would be to:
> * internally create a root logger if one isn't explicitly configured (like in beta5)
> * this default root logger would have level ERROR  (like in beta5)
> * this default root logger would not have any appenders configured  (different from beta5)
> * named loggers in the config are picked up correctly and not ignored  (different from beta5)
> 
> Does that match what you had in mind?
> 
> About location, I was thinking that the majority of sample configs would be without location and a few would keep location layouts. For those we'd put a comment in the config XML as well as in the accompanying text that explains the performance impact. Does that sound ok?
> 
> 
> Sent from my iPhone
> 
> On 2013/04/27, at 15:09, Ralph Goers <ra...@dslextreme.com> wrote:
> 
>> It occurs to me that given the way Log4j and Logback work they probably always have a root logger that starts out not configured with an appender. I guess it would make sense for us to do the same.  I do think it makes sense to emit a warning when no root logger is specified.
>> 
>> I agree with your points about the use of location in the examples. It would probably make sense though to have a section that does have examples that clearly calls out the overhead of using them.
>> 
>> Ralph
>> 
>> On Apr 26, 2013, at 11:04 PM, Remko Popma wrote:
>> 
>>> On the log4j user mailing list I encountered a user who had made a few wrong turns, config-wise, and had trouble getting back on track.
>>> 
>>> One issue was that by default the File appender is buffered but does not flush.
>>> So his log file stayed empty and he had trouble figuring out why.
>>> 
>>> Should we change the examples a little?
>>> * use bufferedIO=false in all File appender examples?
>>> * add a comment that the root logger is mandatory (LOG4J2-219)
>>> 
>>> Also I would like to propose (and opinions may differ on this one)
>>> to avoid using layouts that use location in the examples,
>>> unless the example is used to explain how location works.
>>> (E.g., the API > Flow Tracing page would need location layout examples.)
>>> 
>>> Currently most examples use %C and %M and I would greatly prefer that the examples use %c and other layouts that do not include location. 
>>> 
>>> I believe that many people will start using Log4j by copying an example and only read the manual when they get stuck.
>>> I would hate to give first-time users the impression that Log4j is slow and have our own example configs to blame... :-)
>>> 
>>> On the same topic, in the layouts page I would like to add remarks describing performance impact to the attributes that include location.
>>> 
>>> Thoughts?
>> 

Re: improving the manual pages

[Remko Popma <re...@yahoo.com>]

Ok, then to summarize my understanding for LOG4J2-219 the solution would be to:
* internally create a root logger if one isn't explicitly configured (like in beta5)
* this default root logger would have level ERROR  (like in beta5)
* this default root logger would not have any appenders configured  (different from beta5)
* named loggers in the config are picked up correctly and not ignored  (different from beta5)

Does that match what you had in mind?

About location, I was thinking that the majority of sample configs would be without location and a few would keep location layouts. For those we'd put a comment in the config XML as well as in the accompanying text that explains the performance impact. Does that sound ok?


Sent from my iPhone

On 2013/04/27, at 15:09, Ralph Goers <ra...@dslextreme.com> wrote:

> It occurs to me that given the way Log4j and Logback work they probably always have a root logger that starts out not configured with an appender. I guess it would make sense for us to do the same.  I do think it makes sense to emit a warning when no root logger is specified.
> 
> I agree with your points about the use of location in the examples. It would probably make sense though to have a section that does have examples that clearly calls out the overhead of using them.
> 
> Ralph
> 
> On Apr 26, 2013, at 11:04 PM, Remko Popma wrote:
> 
>> On the log4j user mailing list I encountered a user who had made a few wrong turns, config-wise, and had trouble getting back on track.
>> 
>> One issue was that by default the File appender is buffered but does not flush.
>> So his log file stayed empty and he had trouble figuring out why.
>> 
>> Should we change the examples a little?
>> * use bufferedIO=false in all File appender examples?
>> * add a comment that the root logger is mandatory (LOG4J2-219)
>> 
>> Also I would like to propose (and opinions may differ on this one)
>> to avoid using layouts that use location in the examples,
>> unless the example is used to explain how location works.
>> (E.g., the API > Flow Tracing page would need location layout examples.)
>> 
>> Currently most examples use %C and %M and I would greatly prefer that the examples use %c and other layouts that do not include location. 
>> 
>> I believe that many people will start using Log4j by copying an example and only read the manual when they get stuck.
>> I would hate to give first-time users the impression that Log4j is slow and have our own example configs to blame... :-)
>> 
>> On the same topic, in the layouts page I would like to add remarks describing performance impact to the attributes that include location.
>> 
>> Thoughts?
> 

Re: improving the manual pages

[Ralph Goers <ra...@dslextreme.com>]

It occurs to me that given the way Log4j and Logback work they probably always have a root logger that starts out not configured with an appender. I guess it would make sense for us to do the same.  I do think it makes sense to emit a warning when no root logger is specified.

I agree with your points about the use of location in the examples. It would probably make sense though to have a section that does have examples that clearly calls out the overhead of using them.

Ralph

On Apr 26, 2013, at 11:04 PM, Remko Popma wrote:

> On the log4j user mailing list I encountered a user who had made a few wrong turns, config-wise, and had trouble getting back on track.
> 
> One issue was that by default the File appender is buffered but does not flush.
> So his log file stayed empty and he had trouble figuring out why.
> 
> Should we change the examples a little?
> * use bufferedIO=false in all File appender examples?
> * add a comment that the root logger is mandatory (LOG4J2-219)
> 
> Also I would like to propose (and opinions may differ on this one)
> to avoid using layouts that use location in the examples,
> unless the example is used to explain how location works.
> (E.g., the API > Flow Tracing page would need location layout examples.)
> 
> Currently most examples use %C and %M and I would greatly prefer that the examples use %c and other layouts that do not include location. 
> 
> I believe that many people will start using Log4j by copying an example and only read the manual when they get stuck.
> I would hate to give first-time users the impression that Log4j is slow and have our own example configs to blame... :-)
> 
> On the same topic, in the layouts page I would like to add remarks describing performance impact to the attributes that include location.
> 
> Thoughts?