3.10.16. LogObservers
- class buildbot.process.logobserver.LogObserver
This is a base class for objects which receive logs from worker commands as they are produced. It does not provide an interface for reading logs - such access should occur directly through the Data API.
See Adding LogObservers for help creating and using a custom log observer.
The three methods that subclasses may override follow. None of these methods may return a Deferred. It is up to the callee to handle any asynchronous operations. Subclasses may also override the constructor, with no need to call
LogObserver
’s constructor.- outReceived(data):
- Parameters:
data (unicode) – received data
This method is invoked when a “chunk” of data arrives in the log. The chunk contains one or more newline-terminated unicode lines. For stream logs (e.g.,
stdio
), output to stderr generates a call toerrReceived
, instead.
- errReceived(data):
- Parameters:
data (unicode) – received data
This method is similar to
outReceived
, but is called for output to stderr.
- headerReceived(data):
- Parameters:
data (unicode) – received data
This method is similar to
outReceived
, but is called for header output.
- finishReceived()
This method is invoked when the observed log is finished.
- class buildbot.process.logobserver.LogLineObserver
This subclass of
LogObserver
calls its subclass methods once for each line, instead of once per chunk.- outLineReceived(line):
- Parameters:
line (unicode) – received line, without newline
Like
outReceived
, this is called once for each line of output received. The argument does not contain the trailing newline character.
- errLineReceived(line):
- Parameters:
line (unicode) – received line, without newline
Similar to
outLineReceived
, but for stderr.
- headerLineReceived(line):
- Parameters:
line (unicode) – received line, without newline
Similar to
outLineReceived
, but for header output.
- finishReceived()
This method, inherited from
LogObserver
, is invoked when the observed log is finished.
- class buildbot.process.logobserver.LineConsumerLogObserver
This subclass of
LogObserver
takes a generator function and “sends” each line to that function. This allows consumers to be written as stateful Python functions, e.g.,def logConsumer(self): while True: stream, line = yield if stream == 'o' and line.startswith('W'): self.warnings.append(line[1:]) def __init__(self): ... self.warnings = [] self.addLogObserver('stdio', logobserver.LineConsumerLogObserver(self.logConsumer))
Each
yield
expression evaluates to a tuple of (stream, line), where the stream is one of ‘o’, ‘e’, or ‘h’ for stdout, stderr, and header, respectively. As with any generator function, theyield
expression will raise aGeneratorExit
exception when the generator is complete. To do something after the log is finished, just catch this exception (but then re-raise it or return).def logConsumer(self): while True: try: stream, line = yield if stream == 'o' and line.startswith('W'): self.warnings.append(line[1:]) except GeneratorExit: self.warnings.sort() return
Warning
This use of generator functions is a simple Python idiom first described in PEP 342. It is unrelated to the generators used in
inlineCallbacks
. In fact, consumers of this type are incompatible with asynchronous programming, as each line must be processed immediately.
- class buildbot.process.logobserver.BufferLogObserver(wantStdout=True, wantStderr=False)
- Parameters:
wantStdout (boolean) – true if stdout should be buffered
wantStderr (boolean) – true if stderr should be buffered
This subclass of
LogObserver
buffers stdout and/or stderr for analysis after the step is complete. This can cause excessive memory consumption if the output is large.- getStdout()
- Returns:
unicode string
Return the accumulated stdout.
- getStderr()
- Returns:
unicode string
Return the accumulated stderr.