3.5.11. log

resource type: log
Attributes:

  • complete (boolean) – true if this log is complete and will not generate additional logchunks

  • logid (integer) – the unique ID of this log

  • name (string) – the name of this log (e.g., err.html)

  • num_lines (integer) – total number of line of this log

  • slug (identifier) – the “slug”, suitable for use in a URL, of this log (e.g., err_html)

  • stepid (integer) – id of the step containing this log

  • type (identifier) – log type, identified by a single ASCII letter; see logchunk for details

example

{
    "logid": 60,
    "name": "stdio",
    "slug": "stdio",
    "stepid": 50,
    "complete": false,
    "num_lines": 0,
    "type": "s"
}

A log represents a stream of textual output from a step. The actual output is encoded as a sequence of logchunk resources. In-progress logs append logchunks as new data is added to the end, and event subscription allows a client to “follow” the log.

Each log has a “slug” which is unique within the step, and which can be used in paths. The slug is generated by addLog based on the name, using forceIdentifier and incrementIdentifier to guarantee uniqueness.

Todo

event: build.$buildid.step.$number.log.$logid.newlog

The log has just started. Logs are started when they are created, so this also indicates the creation of a new log.

event: build.$buildid.step.$number.log.$logid.complete

The log is complete.

3.5.11.1. Update Methods

All update methods are available as attributes of master.data.updates.

class buildbot.data.logs.Log
addLog(stepid, name, type)
Parameters:

  • stepid (integer) – stepid containing this log

  • name (string) – name for the log

Raises:

KeyError – if a log by the given name already exists

Returns:

logid via Deferred

Create a new log and return its ID. The name need not be unique. This method will generate a unique slug based on the name.

appendLog(logid, content):
Parameters:

  • logid (integer) – the log to which content should be appended

  • content (unicode) – the content to append

Append the given content to the given log. The content must end with a newline. All newlines in the content should be UNIX-style (\n).

finishLog(logid)
Parameters:

logid (integer) – the log to finish

Mark the log as complete.

compressLog(logid)
Parameters:

logid (integer) – the log to compress

Compress the given log, after it is finished. This operation may take some time.

3.5.11.2. Endpoints

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_name}/logs
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

This path selects all logs for the given step.

GET
returns

collection of log

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_name}/logs/{log_slug}
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 log

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}/logs
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

This path selects all log of a specific step

GET
returns

collection of log

path: /builders/{builderid_or_buildername}/builds/{build_number}/steps/{step_number}/logs/{log_slug}
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

This path selects one log of a specific step

GET
returns

collection of log

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

  • buildid (number) – the id of the build

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

This path selects all logs of a step of a build

GET
returns

collection of log

path: /builds/{buildid}/steps/{step_number_or_name}/logs/{log_slug}
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

This path selects one log of a a specific step

GET
returns

collection of log

path: /logs/{logid}
Path Keys:

logid (number) – the id of the log

This path selects one log

GET
returns

collection of log

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

stepid (number) – the id of the step

This path selects all logs for the given step

GET
returns

collection of log

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

  • stepid (number) – the id of the step

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

GET
returns

collection of log