Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see http://docs.buildbot.net/current/.

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 to errReceived, 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, the yield expression will raise a GeneratorExit 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.