[Twisted-Python] Log output formatting (was Re: logging question)

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Wed Nov 30 08:20:41 EST 2011

On 29 Nov, 06:44 pm, ddwiggins at advpubtech.com wrote:
>On 11/17/2011 3:26 PM, exarkun at twistedmatrix.com wrote:
>>`msg` doesn't really care about what you give it. It doesn't support
>>the `format` keyword in any particular way.  It's the job of a log
>>observer to handle that sort of thing.  So it could certainly be
>>documented, but don't mix things together that are unrelated.
>True, but I was motivated by a different concern: when I first started
>using msg, I was unable to trace through the API docs to the place 
>I could find what I've quoted; Chris' message gave me the hint I needed
>to complete my detective work.  I'd like to spare future users of the
>method the trouble I had.
>Looking at the source of log.py, I'm at a bit of a loss to reconcile
>these two forces.  Certainly, the two log observers implemented there
>use textFromEventDict, but one could create a different observer that
>does things entirely differently.
>The best idea I can come up with is, in the documentation for msg, 
>to the documentation for the chosen log observer; then, in each log
>observer's documentation, describe how the formatting is done, either
>explicitly, or by reference to textFromEventDict.  (And maybe in the
>documentation for ILogObserver, recommend strongly that each
>implementation be explicit about message formatting.)  There should
>probably also be something in the logging howto.
>Any better suggestions?

I'm not sure what you mean by "refer to the documentation for the chosen 
log observer".  The only interpretation I can think of involves changing 
the documentation dynamically at runtime, which doesn't make any sense, 
so I don't think it's what you meant. :)

Adding something about observers to the twisted.python.log.msg 
documentation does seem like it makes sense.  Maybe that could be a link 
to most-used observers that Twisted comes with, or maybe to a document 
about observers in general.

The second part of your suggestion, having each observer document what 
kind of events it expects to consume, sounds great.

Extending the logging howto also sounds great.

And a long-standing related issue, twisted.python.log.msg not appearing 
in the API documentation, would also be nice to resolve.


More information about the Twisted-Python mailing list