Logs
====

.. bb:rtype:: log

    :attr integer logid: the unique ID of this log
    :attr string name: the name of this log (e.g., ``err.html``)
    :attr slug: the "slug", suitable for use in a URL, of this log (e.g., ``err_html``)
    :type slug: 50-character :ref:`identifier <type-identifier>`
    :attr integer stepid: id of the step containing this log
    :attr boolean complete: true if this log is complete and will not generate additional logchunks
    :attr character type: log type, identified by a single ASCII letter; see :bb:rtype:`logchunk` for details.

    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.LogResourceType.newLog` 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.

    .. bb:rpath:: /log/:logid

        :pathkey integer logid: the ID of the log

        This path selects a specific log.

    .. bb:rpath:: /step/:stepid/log

        :pathkey integer stepid: the ID of the step

        This path selects all logs for the given step.

    .. bb:rpath:: /step/:stepid/log/:log_slug

        :pathkey integer stepid: the ID of the step
        :pathkey integer log_slug: the slug for the log

        This path selects a specific log.

    .. bb:rpath:: /build/:buildid/step/:step_name/log

        :pathkey integer buildid: the ID of the build
        :pathkey string step_name: the name of the step within the build

        This path selects all logs for the given step.

    .. bb:rpath:: /build/:buildid/step/:step_name/log/:log_slug

        :pathkey integer buildid: the ID of the build
        :pathkey identifier step_name: the name of the step within the build
        :pathkey identifier log_slug: the slug for the log

        This path selects a specific log in a step

    .. bb:rpath:: /build/:buildid/step/:step_number/log

        :pathkey integer buildid: the ID of the build
        :pathkey integer step_number: the number of the step within the build

        This path selects all logs for the given step.

    .. bb:rpath:: /build/:buildid/step/:step_number/log/:log_slug

        :pathkey integer buildid: the ID of the build
        :pathkey integer step_number: the number of the step within the build
        :pathkey identifier log_slug: the slug for the log

        This path selects a specific log in the given step.

    .. bb:rpath:: /builder/:builderid/build/:build_number/step/:name/log

        :pathkey integer builderid: the ID of the builder
        :pathkey integer build_number: the number of the build within the builder
        :pathkey identifier name: the name of the step within the build

        This path selects all logs for the given step.

    .. bb:rpath:: /builder/:builderid/build/:build_number/step/:name/log/:log_slug

        :pathkey integer builderid: the ID of the builder
        :pathkey integer build_number: the number of the build within the builder
        :pathkey identifier name: the name of the step within the build
        :pathkey identifier log_slug: the slug for the log

        This path selects a specific log in the given step.

    .. bb:rpath:: /builder/:builderid/build/:build_number/step/:step_number/log

        :pathkey integer builderid: the ID of the builder
        :pathkey integer build_number: the number of the build within the builder
        :pathkey integer step_number: the number of the step within the build

        This path selects all logs for the given step.

    .. bb:rpath:: /builder/:builderid/build/:build_number/step/:step_number/log/:log_slug

        :pathkey integer builderid: the ID of the builder
        :pathkey integer build_number: the number of the build within the builder
        :pathkey integer step_number: the number of the step within the build
        :pathkey identifier log_slug: the slug for the log

        This path selects a specific log in the given step.

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

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

.. py:class:: buildbot.data.logs.LogResourceType

    .. py:method:: newLog(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.
