Sunday 19 December 2010

Logging documentation for Python 3.2 reorganised

After comments that the length of logging documentation was making it hard to navigate, and after the addition of a new basic tutorial, the documentation has been reorganised. The library reference is supposed to be just that – a reference – so the tutorials have been moved to the HOWTO section. The configuration and handler documentation has also been moved into separate pages. The organisation of the Python 3.2 logging documentation is now as follows:

There’s a prominent sidebar at the start of the reference documentation pages pointing to the HOWTO sections.

I hope the results are easier to navigate and to understand. Please feel free to give your feedback.

6 comments:

  1. I've an unrelated question, and I don't know where I should ask it.

    Dozer provides a WSGI middleware that tries to capture all the logging output that happens during a request, and then shows that information in a popup on the HTML page. This is quite useful. But the way it's implemented, Dozer installs a handler to the root logger -- which means that if any other loggers set propagate to false, those messages cannot be seen.

    Is there a good way to capture _all_ logging messages?

    ReplyDelete
  2. If other loggers set propagate to False, logging assumes it must be for a reason - so it honours that setting.

    You can add the handler which Dozer adds to the root logger, to other loggers which set propagate to False, and so capture all log messages that way.

    Of course, that assumes you know which loggers are missing.

    ReplyDelete
  3. That's the problem with reusable middleware -- it can't know, unless you add an error-prone user configuration knob.

    Is there a way to enumerate all the currently known loggers? Logger.manager.loggerDict seems like an implementation detail, rather than part of the API.

    ReplyDelete
  4. There's no API currently for enumerating all existing loggers, and you're right that loggerDict is an internal detail. Even if there were such an API, it's not guaranteed to help you: some loggers in some library you're using may only be invoked (and hence created) in certain code paths, which you wouldn't necessarily exercise by your usage of that library.

    A good library should document its use of loggers, precisely because this is needed by application developers using the library.

    In specific scenarios you can use your own Logger subclass, this would allow you to e.g. set the propagation flag to False (just via a setter in the derived class). This affects all loggers and so care has to be exercised using this approach, and it shouldn't be done in a library.

    ReplyDelete
  5. Thank you for your answers!

    Is there a better venue for this kind of discussion in the future? A mailing list, perhaps?

    ReplyDelete
  6. Why not have the discussion on comp.lang.python? As it's the Python users mailing list, any discussion on there has the merit of involving lots of people and any solution to a problem (whether simple or complex) will be visible to everyone on the list.

    ReplyDelete