3.5.10. logchunk

resource type: logchunk
Attributes:

  • content (string) – content of the chunk

  • firstline (integer) – zero-based line number of the first line in this chunk

  • logid (integer) – the ID of log containing this chunk

A logchunk represents a contiguous sequence of lines in a logfile. Logs are not individually addressable in the data API; instead, they must be requested by line number range. In a strict REST sense, many logchunk resources will contain the same line.

The chunk contents is represented as a single unicode string. This string is the concatenation of each newline terminated-line.

Each log has a type, as identified by the “type” field of the corresponding log. While all logs are sequences of unicode lines, the type gives additional information of interpreting the contents. The defined types are:

  • t – text, a simple sequence of lines of text

  • s – stdio, like text but with each line tagged with a stream

  • h – HTML, represented as plain text

  • d – Deleted, logchunks for this log have been deleted by the Janitor

In the stream type, each line is prefixed by a character giving the stream type for that line. The types are i for input, o for stdout, e for stderr, and h for header. The first three correspond to normal UNIX standard streams, while the header stream contains metadata produced by Buildbot itself.

The offset and limit parameters can be used to select the desired lines. These are specified as query parameters via the REST interface, or as arguments to the get method in Python. The result will begin with line offset (so the resulting firstline will be equal to the given offset), and will contain up to limit lines.

Following example will get the first 100 lines of a log:

from buildbot.data import resultspec
first_100_lines = yield self.master.data.get(("logs", log['logid'], "contents"),
    resultSpec=resultspec.ResultSpec(limit=100))

Following example will get the last 100 lines of a log:

from buildbot.data import resultspec
last_100_lines = yield self.master.data.get(("logs", log['logid'], "contents"),
    resultSpec=resultspec.ResultSpec(offset=log['num_lines']-100))

Note

There is no event for a new chunk. Instead, the log resource is updated when new chunks are added, with the new number of lines. Consumers can then request those lines, if desired.

3.5.10.1. Update Methods

Log chunks are updated via log.

3.5.10.2. Endpoints

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_name}/logs/{log_slug}/contents
Path Keys:

  • builderid_or_buildername (number|identifier) – the ID or name of the builder

  • build_number (number) – the number of the build within the builder

  • step_name (identifier) – the slug name of the step

  • log_slug (identifier) – the slug name of the log

GET
returns

collection of logchunk

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}/logs/{log_slug}/contents
Path Keys:

  • builderid_or_buildername (number|identifier) – the ID or name of the builder

  • build_number (number) – the number of the build within the builder

  • step_number (number) – the number of the step

  • log_slug (identifier) – the slug name of the log

GET
returns

collection of logchunk

path: /builds/{buildid}/steps/{step_number_or_name}/logs/{log_slug}/contents
Path Keys:

  • buildid (number) – the id of the build

  • step_number_or_name (identifier|number) – the name or number of the step

  • log_slug (identifier) – the slug name of the log

GET
returns

collection of logchunk

path: /logs/{logid}/contents
Path Keys:

logid (number) – the id of the log

GET
returns

collection of logchunk

path: /steps/{stepid}/logs/{log_slug}/contents
Path Keys:

  • stepid (number) – the id of the step

  • log_slug (identifier) – the slug name of the log

GET
returns

collection of logchunk