wiki:Screwtape

Version 3 (modified by Screwtape, 4 years ago) (diff)

More things to document.

Notes on twisted.python.log documentation.

Someday I'll have to go through and actually file tickets for all this stuff.

While scanning through the documentation for #4568, I've found a number of things I wish were mentioned somewhere (either in the howto or in docstrings) but aren't. In no particular order:

  • startLogging's first parameter is technically "whatever is acceptable input to FileLogObserver", but the useful answer is "a file-handle, file-like object, or an instance of one of the special classes in t.p.logfile. It would be nice to have this spelled out somewhere.
  • There should be documentation describing what happens if you call startLogging multiple times, and whether it's a good idea or not (it doesn't look like it would break anything, but the code doesn't look like it was ever intended to be called multiple times).
  • Perhaps I should file a ticket to create an IFileLog interface that defines what FileLogObserver requires, and declare the various t.p.logfile classes as implementing it.
  • There's actually a second way to configure where log messages go, which is to find an Observer class (say, PythonLoggingObserver or SyslogObserver) and call .start() on it.
    • This should be mentioned in some hypothetical "list of ways to configure where log messages go".
    • Since these classes are spread around the Twisted tree (some are in t.p.log, one's in t.p.syslog, there may be others), there should be a document listing what observers are available.
    • Confusingly, although these classes share a common suffix, they have nothing to do with the ILogObserver interface. That should be documented somewhere.
    • Perhaps I should file a ticket to create an ILogObservatory interface that describes this common interface, and mark all the relevant classes as implementing it.
    • There needs to be documentation of how these observer classes interact with startLogging (hint: they don't replace the previous log observer).
  • There's a third way to configure where log messages go, which is to call t.p.log.addObserver and hand it a callable. This should be mentioned in the "list of ways to configure logging".
  • There's even a fourth way to configure where log messages go: startLoggingWithObserver which is a combination of the first and third methods (actually startLogging instantiates an observer of the second kind, converts it to an observer of the third kind, then hands it to startLoggingWithObserver).
  • Something needs to record that Twisted's logging system is actually a notification broadcast system, not limited to appending lines of text to a file.
  • Something needs to document the tricks of implementing a log observer:
    • textFromEventDict does all the heavy lifting.
    • You should be careful to filter out events that aren't obviously intended to be logged to files; in particular, ignore things that have neither "message" nor "format" keys (is this actually right?)