/
logchunk.raml
61 lines (44 loc) · 2.67 KB
/
logchunk.raml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
#%RAML 1.0 DataType
description: |
A logchunk represents a contiguous sequence of lines in a logfile.
Logs are not individually addressible 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 :bb:rtype:`log`.
While all logs are sequences of unicode lines, the type gives additional information fo 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
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 :py:meth:`~buildbot.data.connector.DataConnector.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.
Update Methods
--------------
Log chunks are updated via :bb:rtype:`log`.
properties:
content:
description: content of the chunk
type: string
firstline:
description: zero-based line number of the first line in this chunk
type: integer
logid:
description: the ID of log containing this chunk
type: integer
type: object