The Level javadoc should contain this info; this can then be extracted into the manual. The current javadoc is clear if terse.
Gary -------- Original message -------- From: Paul Benedict <pbened...@apache.org> Date:01/24/2014 15:47 (GMT-05:00) To: Log4J Developers List <log4j-dev@logging.apache.org> Subject: Re: Levels added in revision 1560602 We should ensure that both the Javadocs and the user guide explain recommended usages for these. Mailing lists are for the most die-hard development fans. :-) On Fri, Jan 24, 2014 at 2:38 PM, Gary Gregory <garydgreg...@gmail.com> wrote: There have been descriptions of what the levels are for... see Ralph ' message, many of mine and others. I know it can be tedious to go back through various threads but the info is there. If you want more info, feel free to ask ;) Gary -------- Original message -------- From: Christian Grobmeier Date:01/24/2014 14:20 (GMT-05:00) To: Log4J Developers List Subject: Re: Levels added in revision 1560602 What I miss in this discussion are actually good examples of what the (new) log levels are intended for. In example, Gary mentioned he is on a wireshark level with "trace". That's fine, because it would give some idea when to use verbose (maybe entering method). Maybe I missed it when what I ask for was already written, but I believe if we can give concrete example how log levels should be used then we are a step further. I was asked quite a log what should be logged with which level. I think making the difference between trace and debug is already difficult for a lot of users. In the past two years i asked a lot of people how they log. The answer was: exceptions on error, the rest on debug. What we lack is a good recommendation how log levels should be used. Something which is on our front page and which lets the "average" Java programmer fully understand when he uses what, and maybe even why. If we have something like that it is much easier to argue pro/contra the new log levels. On 24 Jan 2014, at 18:36, Scott Deboy wrote: > To be fair, I think we represent a reasonable fraction of the > users..some won't touch new predefined levels, some will use it - > that's the reason for adding it - we hit a significant portion of use > cases with small additional number of built-in levels. > > The two solutions don't provide the same thing, do they? If they do, > I wouldn't be pressing the issue. > > If there is a way for us, via annotations or whatever mechanism we > define for 'custom levels', to add support easily for the newly > pre-defined levels, then we should do it. > > Specifically, I'm ok with any mechanism (even using the new custom > level mechanism, but provide by log4j itself), where log4j users are > able to call: > > logger.notice(something); > > Anything else and it won't meet my expectations for usability. > > By the way, while we're at it, let's remove fatal. > > Scott > > > On 1/24/14, Remko Popma <remko.po...@gmail.com> wrote: >> I'm not questioning your experience, and I believe you when you say >> that >> the proposed levels would be a perfect match for your current work >> environment. >> >> However, out of the eight people that participated in the discussion >> on >> adding levels, four expressed strong reservations about adding >> pre-defined >> levels. We are all programmers on this list. So I think we can >> reasonable >> assume that a large fraction of users would also not like this >> change. >> >> On top of that, we have a more powerful and elegant alternative >> solution >> that makes adding pre-defined levels unnecessary. >> Sorry, but I veto the commit. >> >> >> >> >> On Sat, Jan 25, 2014 at 1:49 AM, Gary Gregory >> <garydgreg...@gmail.com>wrote: >> >>> On Thu, Jan 23, 2014 at 10:18 PM, Ralph Goers >>> <ralph.go...@dslextreme.com>wrote: >>> >>>> Gary, although Remko hasn’t said it I think he is implying that >>>> he is >>>> vetoing the code commit. Unfortunately, unless you can convince >>>> Remko >>>> otherwise you are going to have to revert the commit. >>>> >>>> Remko, if that isn’t your intention then please say so as it will >>>> save >>>> Gary a bunch of work. >>>> >>> >>> Hello, hello, >>> >>> Wow, what a pickle of religious debate this has turned into! >>> >>> Before I do indeed do more work: >>> >>> >>>> >>>> >>> >>>> Ralph >>>> >>>> On Jan 23, 2014, at 6:34 PM, Remko Popma <remko.po...@gmail.com> >>>> wrote: >>>> >>>> >>> >>> I wish you had a story of some kind to show why you are so strongly >>> opposed to the new levels. I just wonder then why you are not >>> arguing for >>> fewer levels? Is 6 levels just the perfect number in your mind? If >>> you >>> designed a new logging system right now in a clean room approach, >>> what >>> would you devise? >>> >>> FWIW, I do consider Log4j2 a brand new system, granting us the >>> freedom to >>> break APIs with version 1, which we've obviously done, but not in a >>> way >>> that will make it too difficult to port client code. For custom >>> appenders, >>> I've not tried to port my version 1 appenders yet... >>> >>> >>>> To clarify my position on the proposed DIAG, VERBOSE, NOTICE log >>>> levels: >>>> I don't think these levels should be added to the Log4J API. >>>> Here is my thinking: >>>> >>>> 1. The current five levels are a de facto. standard. (For example, >>>> they >>>> match the SLF4J levels.) >>>> >>>> But they do not match JUL, which is more of a standard since it is >>>> in >>>> the >>> JRE; albeit a _brain-dead_ standard; no DEBUG level JUL? Really? >>> So clearly we care about certain kinds of standard but not others. >>> Since the Slf4j author created Log4j1, I would not expect otherwise >>> and >>> it >>> should not make it the best solution moving forward by default. >>> >>> >>>> They are sufficient for the vast majority of log4j users. We should >>>> be >>>> hesitant to change this. My position would be to not change this >>>> unless >>>> we >>>> all think this is a really good idea. (The bar should be high for >>>> this >>>> change.) >>>> >>>> What are you afraid of? Confusing developers and users with 3 new >>>> levels? >>> Let's give them more credit than that! ;) >>> >>> >>>> 2. From a practical point of view, making. levels an Extensible >>>> Enum >>>> provides a more powerful alternative solution, making the proposed >>>> levels >>>> unnecessary. >>>> 3. From an engineering/aestical POV, I feel the proposed levels are >>>> arbitrary and the Extensible Enum solution is more elegant. >>>> >>>> >>> AGAIN, there are different features, why are they mutually >>> exclusive? >>> >>> >>>> 4. The proposed levels are not only unnecessary, I think they are >>>> actually detrimental (for lack of a better word. I mean, not having >>>> them >>>> would be better). >>>> The discussion in the "Web Issues, Logging Levels, and GA" thread >>>> shows >>>> how much opinions can differ about naming, strength, and intended >>>> usage, >>>> *even in our small group*. How can we predict what levels other >>>> users >>>> may >>>> want? >>>> >>>> >>> How about using your own experience as a guideline? How have the >>> current >>> levels confused your users? Would fewer levels been better for them? >>> >>> I've creating a logging system before Log4j1 existed, ported our >>> server >>> to >>> Log4j1 and then extended Log4j1 for our servers and tools at work. >>> Believe >>> you me, if I've taken the time to write the code, I will use it in >>> our >>> apps >>> instead of the inconsistent various workarounds that have propagated >>> in >>> our >>> code base. These are not "oh, these would be nice to have in >>> theory", >>> theses are "I know I can change my code now to use the new levels". >>> Granted, I am an advanced user. But like any system, I started using >>> a >>> few >>> features and then more and more. >>> >>> We do use TRACE for some method entry and exit. And we use DEBUG a >>> lot. >>> But we need a level, among other things, for wire level hex dumps in >>> all >>> the different parts of the systems where many loggers are used. A >>> level >>> between TRACE and DEBUG would be a perfect solution. I and others >>> have >>> made >>> a good case for the NOTICE level as well, which some wanted as >>> CONFIG. >>> >>> I see the new levels as a refinement based on experience. >>> >>> Is this now a religious debate in which there is 0 chance of >>> convincing >>> you? Or is there 1 chance? >>> >>> >>>> The proposed levels can easily confuse users or get in the way of >>>> users >>>> wanting to use these names at different strengths or with a >>>> different >>>> intended usage. >>>> >>>> >>> Whaaat? How can you presume to know users like that? Give people >>> more >>> credit than that, we are talking about programmers here. For our end >>> users, >>> our support folks tell them "Set the level to X and run the program, >>> then >>> send us the log" where they use a GUI to generate log config files. >>> Our >>> consultants (some are programmers) that go onsite, know the software >>> and >>> what the levels mean. They and the users will be ecstatic if I say >>> that >>> the >>> giant logs given by DEBUG will be smaller because all the hex dumps >>> will >>> be >>> at the VERBOSE levels. The TRACE level is for developers debugging >>> very >>> low >>> level code. FWIW, we had started to use different loggers for hex >>> dumps >>> but >>> this was hard to enforce and harder to configure, so no more of >>> that. >>> >>> So before I revert anything please answer these questions and try to >>> convince _me_ :) >>> >>> Alternatively, feel free to reply with "I VETO this commit" and will >>> revert the commit. >>> >>> Thank you kindly for considering these opinions, >>> >>> Gary >>> >>> >>>> >>>> The fact that changes for these levels have already been committed >>>> is >>>> IMHO not an argument in its favor. On the contrary, I was surprised >>>> at >>>> the >>>> timing of this commit: it was clear that many people were opposed >>>> to >>>> this >>>> approach. To me it was also clear that we had started exploring >>>> extensible >>>> enums as a mechanism that would allow us to *avoid* adding >>>> pre-defined >>>> levels. >>>> >>>> >>>> To repeat my position: I don't think these levels should be added >>>> to the >>>> Log4J API. >>>> >>>> Remko >>>> >>>> On Friday, January 24, 2014, Remko Popma <remko.po...@gmail.com> >>>> wrote: >>>> >>>>> I'm fine with Nick's proposal to have two separate votes. >>>>> Remko >>>>> >>>>> On Friday, January 24, 2014, Nick Williams < >>>>> nicho...@nicholaswilliams.net> wrote: >>>>> >>>>>> There has obviously been some serious discussion about these >>>>>> topics. >>>>>> We're not going to come to a total agreement on this. I propose: >>>>>> >>>>>> - We have a committers-only vote in the "Enums and Custom Levels" >>>>>> thread on whether to make Level an extensible enum. >>>>>> - AFTER having that vote, we have a committers-only vote in this >>>>>> thread >>>>>> on whether to add these three levels. >>>>>> - We only roll back this revision AFTER the second vote is >>>>>> complete >>>>>> and >>>>>> IF the vote rejects the new levels. >>>>>> >>>>>> Nick >>>>>> >>>>>> On Jan 23, 2014, at 7:58 AM, Paul Benedict wrote: >>>>>> >>>>>> On Thu, Jan 23, 2014 at 11:54 AM, Scott Deboy >>>>>> <scott.de...@gmail.com>wrote: >>>>>> >>>>>>> We don't need to scuttle the new levels to support extensible >>>>>>> levels. >>>>>>> >>>>>> >>>>>> >>>>>> Of course. The two things are not technically related. That's not >>>>>> what >>>>>> this is about, though. Since there are camps for and against the >>>>>> new >>>>>> levels, I was hoping the "extensible enum" feature would bring >>>>>> about a >>>>>> compromise. >>>>>> >>>>>> >>>>>>> >>>>>>> Gary's change is essentially a 'usability enhancement' - if >>>>>>> anything >>>>>>> close to 80% of the folks who might want custom levels can use >>>>>>> new >>>>>>> built-in levels, that's an API win in my book. Custom levels >>>>>>> help >>>>>>> the >>>>>>> other 20%, and I'm supportive of that. >>>>>>> >>>>>>> Also please keep in mind this doesn't really add to our >>>>>>> maintenance >>>>>>> burden, which I think may be contributing to the concern about >>>>>>> adding >>>>>>> new levels. Gary already did the heavy lifting, and the change >>>>>>> to >>>>>>> something other than an enum for levels would just be a bit more >>>>>>> work >>>>>>> because of this addition. >>>>>>> >>>>>>> Scott >>>>>>> >>>>>>> On 1/23/14, Paul Benedict <pbened...@apache.org> wrote: >>>>>>>> Let's not lose sight why the "extensible enum" discussion >>>>>>>> occurred. >>>>>>>> Speaking solely for myself, I am not fond of the new logging >>>>>>>> levels; >>>>>>> but I >>>>>>>> don't want the framework from preventing them. The intention >>>>>>>> behind >>>>>>> this >>>>>>>> proposal was to get agreement by scuttling the new levels but >>>>>>> allowing >>>>>>>> anyone to add them in their own private code. >>>>>>>> >>>>>>>> >>>>>>> >>>>>> >>>>>> Paul >>>>>> >>>>>> >>>>>> >>>> >>> >>> >>> -- >>> E-Mail: garydgreg...@gmail.com | ggreg...@apache.org >>> Java Persistence with Hibernate, Second >>> Edition<http://www.manning.com/bauer3/> >>> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> >>> Spring Batch in Action <http://www.manning.com/templier/> >>> Blog: http://garygregory.wordpress.com >>> Home: http://garygregory.com/ >>> Tweet! http://twitter.com/GaryGregory >>> >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: log4j-dev-unsubscr...@logging.apache.org > For additional commands, e-mail: log4j-dev-h...@logging.apache.org --- http://www.grobmeier.de The Zen Programmer: http://bit.ly/12lC6DL @grobmeier GPG: 0xA5CC90DB --------------------------------------------------------------------- To unsubscribe, e-mail: log4j-dev-unsubscr...@logging.apache.org For additional commands, e-mail: log4j-dev-h...@logging.apache.org -- Cheers, Paul
