[boost] Logging library review.

From: Jurko Gospodnetiæ (jurko.gospodnetic_at_[hidden])
Date: 2008-02-17 22:42:15

   Hi.

   Unfortunately I did not get enough free time to play around with this 
library as much as I would have liked. But here's what I have so far.

   I'll skip topic I feel were already covered sufficiently during this 
review and/or John already accepted to correct/change them.

----------------------------------------
* What is your evaluation of the design?
----------------------------------------

   Natural. :-) Logging is one of those topics in which everything has 
been done before, things seem to be added one by one as needed to this 
one...

   There are some things I find no simple way to implement:

   * Filtering based on logged data. E.g. imagine logging airplane 
takeoffs and landings and wanting to log only landings for airplanes 
coming in from Frankfurt.

   * Filtering log messages so that they end up getting written to only 
some destinations. E.g. specifying at run-time that you want information 
about those same airplanes from Frankfurt logged to the output screen 
while all output, including this one, gets logged to the main network 
logging server.

------------------------------------------------
* What is your evaluation of the implementation?
------------------------------------------------

   Have not delved much into the implementation details so here are just 
a few comments.

   Should spell out variable/function/class names without using short 
forms like 'idx' for 'index'.

   OK, maybe the code needing to be written can not get smaller... but 
when I look at the examples and the code I wrote I just get a gut 
feeling that 'something smells' there. Just seems like there is room for 
improvement. Exactly what it is... only usage will tell... :-)

   Should be reviewed carefully to make sure it does not to allow 
throwing exceptions from destructors.

   As I mentioned in another post (and never got John's answer to that 
one) - why not make logger initialization simpler by doing the following:

   * Remove the mark_as_initialized() function.
   * Allow loggers to be enabled or disabled.
   * When disabled, allow loggers to cache or ignore their log messages 
(subject to regular filtering).
   * Create loggers as active by default.
   * Allow the user to create loggers inactive and activate them later 
when appropriate.

   This way the most common use case when you do not need log caching 
would be simple and intuitive... and when someone needs caching - they 
will have no objection to having to enable it - and will even be glad 
that they have that functionality available. :-) This effectively solves 
the problem with users not being aware they need to call 
mark_as_initialized().

-----------------------------------------------
* What is your evaluation of the documentation?
-----------------------------------------------

   Good enough for getting an overview of the library.

   Too informal.

   All the information I needed was in there, but it was sometimes a bit 
hard to track down. I read the documentation first and then it often 
happened that I knew I saw something in there but had not idea where to 
look for it again. Looking at the main index did not help narrow down 
the choices. Long live grep! :-)

   Should explicitly document possible exception throws.

   Comparison between different logging solutions would be nice.

   Nothing about the documentation is a show-stopper. It should become 
much better 'naturally' with a few people reading through it and giving 
feed-back.

   Oh yeah... just another 'nitpicking detail'... the new changes page 
(http://torjo.com/log2/doc/v3/html/page_changelog.html) has a messed up 
header for release v0.22.7. :-)

---------------------------------------------------------------------
* What is your evaluation of the potential usefulness of the library?
---------------------------------------------------------------------

   Enormous.

   I believe that a logging library that managed to get into boost would 
be instantly grabbed by a large and high quality user base. Existing 
solutions are mostly hand-crafted and no packaged logging library I ever 
tried had all the functionality I needed (OK, most of them had it on 
paper, but caused crashes and such when you attempted to use it. :-))

   The main problem with existing libraries I tried is that they left me 
with a feeling that 'no-one is developing them'. Most of them seem dead 
and others give only responses like 'that does not work at the moment, 
no one is working on it but if you need it - you can implement it 
yourself'. IMHO, they just did not have a large enough quality user base 
and development effort behind them to push them forward.

----------------------------------------------------------------------
* Did you try to use the library? With what compiler? Did you have any
problems?
----------------------------------------------------------------------

   MSVC 7.1. and there were no problems that I could blame the library 
for except perhaps that it just seemed easy to make a mistake and have 
something 'not work'. But every such mistake was easy enough to locate 
and correct.

   As before - the library will get better at this as it matures.

----------------------------------------------------------------------
* How much effort did you put into your evaluation? A glance? A quick 
reading? In-depth study?
----------------------------------------------------------------------

   Read the documentation, tried out several simple test logging 
scenarios and played out others on paper comparing them to the library's 
documentation.

-------------------------------------------------
* Are you knowledgeable about the problem domain?
-------------------------------------------------

   Somewhat. Implemented several simple logging solutions. Thought about 
the subject a lot. Involved in maintaining several active applications 
where logging is of tremendous use.

----------------------------------------------------------------
* What more do you wish to see changed/added/implemented in this 
library? How would you like to be able to use it?
----------------------------------------------------------------

   I would like it to provide simple non-throwing logging support so 
logging can be made safe in destructors without having to fear my 
program crashing because of a failed log.

   I would like to see additional effort to make it difficult for 
logging messages to be lost accidentally, e.g. using preallocated 
storage for log messages, leaving log messages queued in the 
preallocated storage in case their output fails and retrying the output 
at a bit later time, together with a message that the original output 
failed. At the very least, I would like a message logged stating that 
some log messages got
lost if this happens (possibly with the exact number of lost messages).

   The v1 functionality with specifying multiple loggers as a group 
using the hierarchical string syntax should be restored. I have used 
hand-crafted logging code supporting it before and it is a great feature 
allowing you to specify what to log and where to log it to at run-time 
and with different scope.

-----------------------------------------------------------------
* Do you think the library should be accepted as a Boost library?
-----------------------------------------------------------------

   My vote would be 'Yes, accept it'. It seems good enough for me.

   This library's has one thing special about it and it seems both a 
curse and a blessing. It is the fact that the library, once accepted, is 
likely to get a huge user base. With such a user base it should be easy 
for it to evolve, but it will also create more and more pressure to 
provide a stable interface and backward compatibility. That and the fear 
of John stopping developing the library before it finds a new maintainer 
are pretty much the only reasons why I considered voting 'No'.

   Logging is such a 'wide' topic, with many interested parties, every 
one of them having its own vision of what logging is supposed to be. As 
a result - I believe we have a chicken & egg problem here. :-) It does 
not seem likely it will be possible to satisfy everyone just by 
'designing' the library but on the other hand it needs to evolve by 
receiving actual user feedback. The current solution seems 'good enough' 
for me, and IMHO for any logging library there will always be someone 
who will think it is not 'good enough'. Keeping it rapidly evolving 
seems like the only way to go, and I'd rather use and contribute to a 
Boost library than other solutions I've tried so far.

   One thing did bother me during this review. I would like to see 
different logging library authors working more closely and possibly on a 
single logging library. Maybe its just me, but I did not like the 
tension/antagonism I sensed between them. :-(

   That said, John seems highly enthusiastic about completing this 
library and I do have faith that he will update the library with respect 
to all the suggestions collected during this review.

   Kudos to him on the work done so far, great enthusiasm and not 
buckling beneath all pressure caused by a Boost review of such complex 
topic as logging.

   Best regards,
     Jurko Gospodnetiæ