Implementing std.log

[Jose Armando Garcia]

This is a review of std.log. Overall, I really like the API exposed by
this module because it allows efficient compile time and run time
configuration. I have limited the review to the API and how the API
affects the implementation. I will review the implementation once the
API is close to final.

1) I think this was pointed out before. I don't really like that the
module can only be configure through the command line by passing the
list of command line arguments. The user should be able to configure
the module programmatically.

2) Not a fan of the top level symbols logInfo, logFatal, etc but it is
not a big deal.

3) opCall and format used template arguments for file and line yet
they are never used at compile time. This leads to unnecessary
template instantiations.

4) I know that when() and every() are really cool features but should
they be first class citizens in a logging module? What if the user
wants 'whenTheMoonIsFull(country)'? Including as part of the module
could be better argued if std.log generates special messages for them
which is what I think glog does. I have been thinking of ways of doing
this in std.logging. E.g. 'logInfo.every(2)("Message")' would generate
the following log line "... 2nd call ... Message."

5) General thought that applies to both std.log and std.logging: It
would be interesting to allow some configuration after initialization.
For example it would be unreasonable to allow configuration of things
that were already externalized like the name of the log file. But
maybe the user should be able to change the severity level and vlog
configuration.

Overall it looks good. As I said before I have a lot of comments on
the implementation but will hold them until we have a final API.

Thanks,
-Jose

On Wed, May 18, 2011 at 10:00 AM, Jose Armando Garcia <jsancio at gmail.com> wrote:
> std.logging is still alive! After posting my first attempt at a
> logging module I went back and spent a lot of time on how I could
> improve the API. I would like to say that Andrei's std.log module had
> a great influence on the final outcome. There are some aspect of
> std.log's API that I really like. E.g. the ability to do fine grain
> compile time configuration. I'll go into detail in a subsequent review
> of std.log.
>
> I also think that having competing logging module is a good thing.
> This process will result in a better module for phobos and as a result
> a better module for the user.
>
> The best way to see what has changed is to look at the source code
> (https://github.com/jsancio/phobos/blob/master/std/logging.d) and the
> generated doc (http://jsancio.github.com/phobos/phobos/std_logging.html).
> Here are some highlights:
>
> 1) I tried to minimize the amount of code the compiler has to generate
> because of template. Template are only used when the module has/wants
> to make compiled time decision. If you spot places where templates are
> not needed please tell me.
>
> 2) Make logging decision as early as possible. Logging can be short
> circuited by either the severity level, the verbose level or an user
> defined condition. All those conditions are evaluated as soon as
> possible and only when required. E.g. the module doesn't evaluate user
> define condition if it already knows that it wont log because of the
> severity.
>
> 3) A module should do one thing an do it well. This module does
> logging so unlike std.log and glog it doesn't have built in mechanism
> for doing 'every', 'when', 'first', etc. Instead the log and vlog
> function provide a lazily evaluated bool parameter that the user can
> use to perform condition logging. There are plenty of example of this
> in the doc.
>
> At the top of the doc I provided an example similar to std.log's
> synopsis so you can compare the two APIs.
>
> Disclaimer: This is a draft. Once we agree on the main API (log and
> vlog). I will go back an finish the implementation, test and
> documentation.
>
> Enjoy! Let me know if you have any suggestions,
> -Jose
>
> On Wed, May 18, 2011 at 6:05 AM, Jacob Carlborg <doob at me.com> wrote:
>> On 2011-05-17 22:15, Andrei Alexandrescu wrote:
>>>
>>> On 5/17/11 4:02 AM, Jacob Carlborg wrote:
>>>>
>>>> On 2011-05-16 02:05, Andrei Alexandrescu wrote:
>>>>>
>>>>> Thanks for your work.
>>>>>
>>>>> I think there's an important distinction to be made. There are two
>>>>> "API"s being discussed. One is the client interface and the other is the
>>>>> extensibility interface.
>>>>>
>>>>> Jose looked into both: he provided a client interface that has
>>>>> formatting, levels, enabling, and such, and an extensibility interface
>>>>> that essentially is a simple output stream.
>>>>>
>>>>> My library explores the client interface and leaves the extensibility
>>>>> interface as an obvious piece of work that needs little agreement and
>>>>> minimal design effort.
>>>>>
>>>>> Finally, your library keeps the client interface to a minimum and
>>>>> focuses almost exclusively on the extensibility interface. In doing so,
>>>>> it makes few choices that I disagree with. Allow me to share some
>>>>> specific feedback.
>>>>
>>>> Note that my suggestion was just a simple and incomplete suggestion on
>>>> how the API could look like. I only provided "info", "warning" and
>>>> "error" methods as examples, I'm not saying the API should only have
>>>> these three levels.
>>>
>>> [snip]
>>>
>>> I thought about this some more and I understand I sounded unfair. There
>>> is a lot of merit and there are a lot of good ideas in your code (and of
>>> course Jose's), which I didn't mention for the simple but cold reason
>>> that negative feedback is more informative. But neglecting the merits is
>>> a mistake as well. I'll incorporate some of the ideas you suggested in
>>> the next pass through std.log.
>>>
>>>
>>> Thanks,
>>>
>>> Andrei
>>
>> No hard feelings, I also have a tendency to just give negative feedback.
>>
>> --
>> /Jacob Carlborg
>>
>