#%RAML 1.0 DataType
displayName: Logs
description: |
    A log represents a stream of textual output from a step.
    The actual output is encoded as a sequence of :bb:rtype:`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 :py:meth:`~buildbot.data.logs.Log.addLog` based on the name, using :py:func:`~buildbot.util.identifiers.forceIdentifier` and :py:func:`~buildbot.util.identifiers.incrementIdentifier` to guarantee uniqueness.

    .. todo::

        .. bb: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.

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

            The log is complete.


    Update Methods
    --------------

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

    .. py:class:: buildbot.data.logs.Log

        .. py:method:: addLog(stepid, name, type)

            :param integer stepid: stepid containing this log
            :param string name: 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.

        .. py:method:: appendLog(logid, content):

            :param integer logid: the log to which content should be appended
            :param unicode content: 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``).

        .. py:method:: finishLog(logid)

            :param integer logid: the log to finish

            Mark the log as complete.

        .. py:method:: compressLog(logid)

            :param integer logid: the log to compress

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

properties:
    complete:
        description: true if this log is complete and will not generate additional logchunks
        type: boolean
    logid:
        description: the unique ID of this log
        type: integer
    name:
        description: the name of this log (e.g., ``err.html``)
        type: string
    num_lines:
        description: total number of line of this log
        type: integer
    slug:
        description: the "slug", suitable for use in a URL, of this log (e.g., ``err_html``)
        type: identifier
    stepid:
        description: id of the step containing this log
        type: integer
    type:
        description: log type, identified by a single ASCII letter; see :bb:rtype:`logchunk` for details.
        type: identifier
type: object
example:
    'logid': 60
    'name': 'stdio'
    'slug': 'stdio'
    'stepid': 50
    'complete': false
    'num_lines': 0
    'type': 's'
