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?)