Review of Jose Armando Garcia Sancio's std.log

[Robert Jacques]

On Tue, 06 Mar 2012 17:20:29 -0600, Jose Armando Garcia <jsancio at gmail.com> wrote:
> On Tue, Mar 6, 2012 at 2:03 PM, Robert Jacques <sandford at jhu.edu> wrote:
>> On Tue, 06 Mar 2012 13:41:32 -0600, Jose Armando Garcia <jsancio at gmail.com>
>> wrote:
>>>
>>> On Tue, Mar 6, 2012 at 10:11 AM, Robert Jacques <sandford at jhu.edu> wrote:
>>>>
>>>> On Tue, 06 Mar 2012 11:44:13 -0600, Jose Armando Garcia
>>>> <jsancio at gmail.com>
>>>> wrote:
>>>>>
>>>>>
>>>>> On Tue, Mar 6, 2012 at 9:32 AM, Robert Jacques <sandford at jhu.edu> wrote:
>>>>>>
>>>>>>
>>>>>> On Tue, 06 Mar 2012 11:01:19 -0600, Jose Armando Garcia
>>>>>> <jsancio at gmail.com>
>>>>>> wrote:
>>>>>>
>>>>>>> On Wed, Feb 29, 2012 at 4:13 PM, Richard van Scheijen
>>>>>>> <dlang at mesadu.net>
>>>>>>> wrote:
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> When logging the severity level should convey a certain insight that
>>>>>>>> the
>>>>>>>> developer has about the code. This can be done with a 3 bit field.
>>>>>>>> These
>>>>>>>> are: known-cause, known-effect and breaks-flow.
>>>>>>>>
>>>>>>>> This creates the following matrix:
>>>>>>>>
>>>>>>>> KC KE BF Severity
>>>>>>>> =================
>>>>>>>> 1  1  0  Trace
>>>>>>>> 0  1  0  Info
>>>>>>>> 1  0  0  Notice
>>>>>>>> 0  0  0  Warning
>>>>>>>> 1  1  1  Error
>>>>>>>> 0  1  1  Critical
>>>>>>>> 1  0  1  Severe
>>>>>>>> 0  0  1  Fatal
>>>>>>>>
>>>>>>>> A known cause is when the developer knows why a log event is made.
>>>>>>>> e.g.:
>>>>>>>> if
>>>>>>>> you cannot open a file, you do not know why.
>>>>>>>> A known effect is when he/she knows what happens after. Basically,
>>>>>>>> you
>>>>>>>> can
>>>>>>>> tell if it is a catch-all by this flag.
>>>>>>>>
>>>>>>>> When a severity should only be handled by a debugger, the normal
>>>>>>>> debug
>>>>>>>> statement should be used. This is in essence a 4th bit.
>>>>>>>>
>>>>>>>> I hope this helpful in the search for a good level system.
>>>>>>>>
>>>>>>>
>>>>>>> Interesting observation on logging. I like your theoretical
>>>>>>> observation and explanation. To me the most important thing is
>>>>>>> usability and unfortunately people are used to log levels as a order
>>>>>>> concept. Meaning error is higher severity than info so if I am logging
>>>>>>> info events I should probably also log error events.
>>>>>>>
>>>>>>> If we go with a mechanism like the one you describe above there is no
>>>>>>> order so the configuration is a little more complicated or verbose I
>>>>>>> should say. Instead of saying we should log everything "greater" than
>>>>>>> warning the user needs to say that they want to log known-cause,
>>>>>>> known-effect, breaks-flow events. This mean that there are 27 (= 3^3)
>>>>>>> configuration combinations. To implement this we need 3 configuration
>>>>>>> nobs with 3 values (on, off, both).
>>>>>>>
>>>>>>> Thoughts?
>>>>>>> -Jose
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> There are only 8 possible configurations and they are nicely ordered in
>>>>>> terms of severity. So I don't see this as a problem. Also, if you went
>>>>>> with
>>>>>> a combinatorial approach, shouldn't it be 2^8 = 256, not 3^3 = 27
>>>>>> values?
>>>>>
>>>>>
>>>>>
>>>>> Yes. If you want to enable and disable each individual "level" then
>>>>> you need 8 configuration options which leads to 2^8.
>>>>>
>>>>> I suggested 3^3 as a more reasonable options that matches how the
>>>>> developer is logging but doesn't give you as much expressiveness as
>>>>> the 2^8 option.
>>>>
>>>>
>>>>
>>>> In practice, all you'd need to take is a flag with the desired levels.
>>>> i.e.
>>>>
>>>> // Automatically set logging levels using the standard severity ordering
>>>> config.minSeverity(Severity.Warning);
>>>>
>>>> // Manually set the logging levels
>>>> config.setSeverities(Severity.Warning|
>>>>                    Severity.Error|
>>>>                    Severity.Critical|
>>>>                    Severity.Severe|
>>>>                    Severity.Fatal);
>>>>
>>>> I don't see the problem with including both methods and a large advantage
>>>> to
>>>> having a standardized severity framework.
>>>
>>>
>>> Interesting. If you find this useful, I think we can add this in a
>>> future release as it shouldn't break existing modules that maybe using
>>> the library.
>>
>>
>> This began as a discussion regarding Richard's organization of logging
>> severity. That organization isn't something that can be trivially included
>> at a later date.
>
> Please be explicit in what you are requesting... If you have an API even better.
>

Richard proposed an organizational framework for logging severity, which many people including myself and yourself found valuable. In another thread I proposed a logical extension of this framework to make the logging call self documenting. You criticized both as having being overly complex with regard to setting the runtime severity level, to which I proposed a reasonable counter argument. Your response to the counter argument is to suggest making one aspect of it a possible future extension. ?? This seemed to ignore Richard's original suggestion and the extreme value of having a set of well-documented and standardized logging guidelines so that multiple code monkeys / projects 'play well' together. Better yet, by specifying those levels in terms of their conceptual components at the call site, code reviewers can instantly see the nature of what is being logged, without having to remember what each of those log levels mean. And not having to remember the classifications reduces  
the radius of comprehension needed to use / review the library (http://pragprog.com/magazines/2010-04/tangled-up-in-tools).

P.S.
You could also set config options using method chaining / fluent interfaces:

config.logWarnings.logErrors.logCriticals.logSevers.logFatals;