# 3.5.14. 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.14.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.14.2. Endpoints

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

    - builderid_or_buildername (number|string) – 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|string) – 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|string) – 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|string) – 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`