Proposed Logging Library review
* What is your evaluation of the design? I think the library is overdesigned, learning curve is too shallow & very difficult to comprehend for a casual user. Author has persevered with the notion of employing namespaces to encapsulate concepts - this leads to a profusion of unrelated names & types, apart from the arguable soundness of this approach.
* What is your evaluation of the implementation? Unwieldy & too reliant on preprocessor macros. Namespaces are over-used. Some important considerations have been overlooked (e.g. output encoding, state of
* What is your evaluation of the documentation? Comprehensive, but too informal. Ultimately insufficient to aid in understanding
* What is your evaluation of the potential usefulness of the library? I think that with a simplified design, discarding of maybe 25 out of the 30+ namespaces used, automatic defaults for typical tasks, no reliance on macros,
I reckon that the problem is that the author has designed the library to make complex tasks easy - e.g. if you wanted to use multiple filters controlling logging to mutiple destinations, this is probably the only library that would help you. But the cost of that power is that typical usage has become too complicated. the log destination, automatically logging exception conditions). But I am using code from the library just for the ability to log on a dedicated thread (with some changes). This alone is worth persevering with the library. I am satisfied that the code itself is stable and largely error-free - it has been running on a live web-server for a week now, without any issues (fingers-crossed). the implementation/usage details of the library. But my point is that the implementation is so scattered that any amount of documentation might be insufficient. this would be a very useful library for almost all C++ developers.
* Did you try to use the library? With what compiler? Did you have any problems? I did & do use it. ICL 10.1 on XP. I have interacted with the author to get some issues solved. I had to change the stream class to accept a flag that flushes on every write, when logging on a dedicated thread. Also, logging to file, cout etc are not possible with this library if the required code conversion is not supported by the locale. I attempted to create an object encapsulating the logger and the filter (since the library does not intend to provide one) but could not since the return type of the overloaded destination::<< is implicit - author did try to help but his suggestion did not work.
* How much effort did you put into your evaluation? A glance? A quick reading? In-depth study? All of the above, + 1 week integrating the library into my application.
* Are you knowledgeable about the problem domain? I am now :-)
And finally, every review should answer this question:
* Do you think the library should be accepted as a Boost library? Be sure to say this explicitly so that your other comments don't obscure your overall opinion.
Not in its current form. Withsupport for output encoding, provision for objects so user can just include the library and start dumping messages with having to create irrelevant objects (like optimized string - optimized for what? how?), the lib would have my unqualified support. I look forward to the outcome of the review, and offer my services for testing any revised implementations. Best Amit
From: "Amit" <contact.lipik@gmail.com>
* What is your evaluation of the design? I think the library is overdesigned, learning curve is too shallow & very difficult to comprehend for a casual user.
* What is your evaluation of the implementation? Unwieldy & too reliant on preprocessor macros. Namespaces are over-used. Some important considerations have been overlooked
* What is your evaluation of the potential usefulness of the library? I think that with a simplified design, discarding of maybe 25 out of the 30+ namespaces used, automatic defaults for typical tasks, no reliance on macros, this would be a very useful library for almost all C++ developers.
And finally, every review should answer this question:
* Do you think the library should be accepted as a Boost library?
Not in its current form.
Though I've only summarised certain aspects of Amit's review and will not be offering a full review of my own, I wanted to agree wholeheartedly with his critique. Thanks Amit. However, without trying to judge or prejudice the outcome of the review, I hope there is a way forward from here that doesn't outright reject a library that clearly has a huge number of positives. The world of logging is so diverse, its almost impossible to satisfy all aims simultaneously in elegant code. Usability and shallow learning curve, run-time optimisations, flexibility, modularity, extended use cases. If anything, I think the current submission is spreading itself too thin and I for one would love to see a consensus on a core set of capabilities defined with the value of John's experience in knowing how extending the core to a wider set of use cases would affect the core. Is it mainly a case that some syntactic sugar is needed to spruce up the way the logging library works. Its aims and capabilities seem invaluable even if the interface to them isn't quite right yet. Without trying to draw too close a parallel, Boost lost a great asset when Chris Diggins ( http://cdiggins.com/category/cpp/ ) decided 'the boost way' wasn't for him any more and I see the energy, enthusiasm and quality of John's work in a similar vein. I don't know John but I have a great deal of admiration for the can-do spirit. Thanks John for all your efforts. Good luck with the review. Paul Baxter
Hi Paul, ----- Original Message ----- From: "Paul Baxter" <pauljbaxter@hotmail.com> To: <boost@lists.boost.org> Sent: Tuesday, February 12, 2008 7:04 AM Subject: Re: [boost] Proposed Logging Library review
The world of logging is so diverse, its almost impossible to satisfy all aims simultaneously in elegant code.
A big yes to the diversity. I suspect that John's library is targeted at developers and the edit+compile+test cycle. Further down the track the same "logging" code might provide the engine for; * support information * operational alarms * formal audit trail for EIS analysis * billing * statistical samples * graphical instrumentation * integration with external logging systems It feels vaguely like the configurability of the library is supposed to fulfill any such unspoken requirement. It may or may not but expanding the scope to include items such as those above would choke the average hippo. For me this library would benefit from well advertised, intended goal "This is a tool for developers", shuffling of documentation and out-of- the-box configuration code. And it should be accepted or rejected on whether it delivers on that reworked intent. Yes Amit's review was great. Cheers.
For me this library would benefit from well advertised, intended goal "This is a tool for developers", shuffling of documentation and out-of- the-box configuration code. And it should be accepted or rejected on whether it delivers on that reworked intent.
"This is a tool for developers" - got it, will be there. Best, John -- http://John.Torjo.com -- C++ expert http://blog.torjo.com ... call me only if you want things done right
Not in its current form.
Though I've only summarised certain aspects of Amit's review and will not be offering a full review of my own, I wanted to agree wholeheartedly with his critique. Thanks Amit.
However, without trying to judge or prejudice the outcome of the review, I hope there is a way forward from here that doesn't outright reject a library that clearly has a huge number of positives.
Thinking over the feedback I got, what I want is another review in 3.5 months. Most requests are not that complex to achieve - it's just that I don't have time to do them right away.
The world of logging is so diverse, its almost impossible to satisfy all aims simultaneously in elegant code. Usability and shallow learning curve, run-time optimisations, flexibility, modularity, extended use cases.
Tell me 'bout it ;)
Is it mainly a case that some syntactic sugar is needed to spruce up the way the logging library works. Its aims and capabilities seem invaluable even if the interface to them isn't quite right yet.
Yup, couldn't agree more ;)
Thanks John for all your efforts. Good luck with the review.
Thanks, see you at the next review ;) Best, John -- http://John.Torjo.com -- C++ expert http://blog.torjo.com ... call me only if you want things done right
Hi Amit, Thanks for the review.
* What is your evaluation of the design?
I think the library is overdesigned, learning curve is too shallow & very difficult to comprehend for a casual user. Author has persevered with the notion of employing namespaces to encapsulate concepts - this leads to a profusion of unrelated names & types, apart from the arguable soundness of this approach.
I reckon that the problem is that the author has designed the library to make complex tasks easy - e.g. if you wanted to use multiple filters controlling logging to mutiple destinations, this is probably the only library that would help you. But the cost of that power is that typical usage has become too complicated.
Got that - will make it much simpler in the next version.
* What is your evaluation of the implementation?
Unwieldy & too reliant on preprocessor macros. Namespaces are over-used. Some
The idea about namespace = concept was a very easy way to look for possible implementations of a concept once you know it. Perhaps I did abuse it, though.
important considerations have been overlooked (e.g. output encoding, state of the log destination, automatically logging exception conditions).
About state of log destination : basically I'll ask people to vote for the features they'd like. Because I've got quite a few conflicting ones :) About logging exception conditions : what do you mean?
But I am using code from the library just for the ability to log on a dedicated thread (with some changes). This alone is worth persevering with the library. I am satisfied that the code itself is stable and largely error-free - it has been running on a live web-server for a week now, without any issues (fingers-crossed).
Thanks, keep me posted ;)
* What is your evaluation of the documentation?
Comprehensive, but too informal. Ultimately insufficient to aid in understanding
About informal - got it, will formalize it.
* What is your evaluation of the potential usefulness of the library?
I think that with a simplified design, discarding of maybe 25 out of the 30+ namespaces used, automatic defaults for typical tasks, no reliance on macros, this would be a very useful library for almost all C++ developers.
Yup, will do.
* Did you try to use the library? With what compiler? Did you have any problems?
I did & do use it. ICL 10.1 on XP. I have interacted with the author to get some issues solved. I had to change the stream class to accept a flag that flushes on every write, when logging on a dedicated thread. Also, logging to file, cout etc are not possible with this library if the required code conversion is not supported by the locale. I attempted to create an object encapsulating the logger and the filter (since the library does not intend to provide one) but could not since the return type of the overloaded destination::<< is implicit - author did try to help but his suggestion did not work.
About logger & filter in one - will be there. About code conversion - will talk privately.
And finally, every review should answer this question:
* Do you think the library should be accepted as a Boost library? Be sure to say this explicitly so that your other comments don't obscure your overall opinion.
Not in its current form. Withsupport for output encoding, provision for objects so user can just include the library and start dumping messages with having to create irrelevant objects (like optimized string - optimized for what? how?), the lib would have my unqualified support.
About irrelevant object - you're right, won't be there in the next version.
I look forward to the outcome of the review, and offer my services for testing any revised implementations.
I'm pretty sure of the outcome of the review :) But I'll ask for another review to take place in about 3.5 months. As for testing - I'll take you up on that offer ;) Best, John -- http://John.Torjo.com -- C++ expert http://blog.torjo.com ... call me only if you want things done right
Hi Amit Hi John,
Thanks for accepting my review in the constructive spirit. I am sure this library is potentally useful enough that it has to get into boost soon. Now to answer your questions:
About state of log destination : basically I'll ask people to vote for the features they'd like. Because I've got quite a few conflicting ones :) About logging exception conditions : what do you mean?
I think that if the library provides a high-level interface (i.e. provide a file name as a log destination), then it should either provide a way to let the user control the destination state, or explicitly state what can be assumed about the destination. As we have discussed previously, this is specially important for this lib since logs can be dumped asynchronously. Also, I would think that it would be useful to have a section in the docs where limitations, error conditions, fallback strategies are explicitly listed. E.g., if the destination file can't be written to due to a network failure, disk full etc - how does the library deal with such cases? Is it an error condition to close the destination while logging is in progress? What is the overhead of logging using various strategies? And so on. A suggestion is that the lib could optionally set unexpected()/terminate(), so unhandled exception conditions can be logged. Just knowing what exception occurred would be useful. Also, exception adapters that log automatically would be useful. I am thinking something like: logging_exception<E> : public E where E is a specialization of std::exception. I see that there has been a lot of discussion about macros. My point was that macros provide a shorthand for some instantiations/function calls. So OK to provide macros as a convenience, but the architecture should be such that lib can be easily understood/extended without macros as well. And doc should list examples without macros, but mention at the end that a macro can be used instead for brevity. This lets the reader understand what the library is doing. Now, if only people would think about the phrase 'learning curve' and realize steep implies good... :) Best Amit
participants (4)
-
Amit -
John Torjo -
Paul Baxter -
Scott Woods