mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-02-14 12:43:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

toaster-manual: Added new chapter "Remote Toaster Monitoring"

Browse Source 
Documented new direct JSON API with four subsections to let
you remotely monitor Toaster.

(From yocto-docs rev: 8b18ccffbcfe896f878dd912ea39b14557426b2c)

Signed-off-by: Kristi Rifenbark <kristi.rifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Kristi Rifenbark
2017-10-11 18:00:57 -07:00
committed by Richard Purdie
parent 2be2a1200e
commit b02ece66c0
1 changed files with 164 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
documentation/toaster-manual/toaster-manual-reference.xml
View File

@@ -719,6 +719,170 @@
</section>
</section>
<section id='remote-toaster-monitoring'>
<title>Remote Toaster Monitoring</title>
<para>
Toaster has an API that allows remote management applications to
directly query the state of the Toaster server and its builds
in a machine-to-machine manner.
This API uses the
<ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
interface and the transfer of JSON files.
For example, you might
monitor a build inside a container through well supported
known HTTP ports in order to easily access a Toaster server
inside the container.
In this example, when you use this direct JSON API, you avoid
having web page parsing against the display the user sees.
</para>
<section id='checking-health'>
<title>Checking Health</title>
<para>
Before you use remote Toaster monitoring, you should do
a health check.
To do this, ping the Toaster server using the following call
to see if it is still alive:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/health
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>
and <replaceable>port</replaceable>.
If the server is alive, you will get the response HTML:
<literallayout class='monospaced'>
&lt;!DOCTYPE html&gt;
&lt;html lang="en"&gt;
&lt;head&gt;&lt;title&gt;Toaster Health&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;Ok&lt;/body&gt;
&lt;/html&gt;
</literallayout>
</para>
</section>
<section id='determining-status-of-builds-in-progress'>
<title>Determining Status of Builds in Progress</title>
<para>
Sometimes it is useful to determine the status of a build
in progress.
To get the status of pending builds, use the following call:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/building
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>
and <replaceable>port</replaceable>.
The output is a JSON file that itemizes all builds in
progress.
This file includes the time in seconds since each
respective build started as well as the progress of the
cloning, parsing, and task execution.
The following is sample output for a build in progress:
<literallayout class='monospaced'>
{"count": 1,
"building": [
{"machine": "beaglebone",
"seconds": "463.869",
"task": "927:2384",
"distro": "poky",
"clone": "1:1",
"id": 2,
"start": "2017-09-22T09:31:44.887Z",
"name": "20170922093200",
"parse": "818:818",
"project": "my_rocko",
"target":
"core-image-minimal"
}]
}
</literallayout>
</para>
</section>
<section id='checking-status-of-builds-completed'>
<title>Checking Status of Builds Completed</title>
<para>
Once a build is completed, you get the status when you use
the following call:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/builds
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>
and <replaceable>port</replaceable>.
The output is a JSON file that itemizes all complete builds,
and includes build summary information.
The following is sample output for a completed build:
<literallayout class='monospaced'>
{"count": 1,
"builds": [
{"distro": "poky",
"errors": 0,
"machine":
"beaglebone",
"project": "my_rocko",
"stop": "2017-09-22T09:26:36.017Z",
"target": "quilt-native",
"seconds": "78.193",
"outcome": "Succeeded",
"id": 1,
"start": "2017-09-22T09:25:17.824Z",
"warnings": 1,
"name": "20170922092618"
}]
}
</literallayout>
</para>
</section>
<section id='determining-status-of-a-specific-build'>
<title>Determining Status of a Specific Build</title>
<para>
Sometimes it is useful to determine the status of a specific
build.
To get the status of a specific build, use the following
call:
<literallayout class='monospaced'>
http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/build/<replaceable>ID</replaceable>
</literallayout>
Be sure to provide values for <replaceable>host</replaceable>,
<replaceable>port</replaceable>, and <replaceable>ID</replaceable>.
In order to provide the value for <replaceable>ID</replaceable>,
you must check the status of the completed build.
See the
"<link linkend='checking-status-of-builds-completed'>Checking Status of Builds Completed</link>"
section for more information.
</para>
<para>
The output is a JSON file that itemizes the specific build
and includes build summary information.
The following is sample output for a specific build:
<literallayout class='monospaced'>
{"build":
{"distro": "poky",
"errors": 0,
"machine": "beaglebone",
"project": "my_rocko",
"stop": "2017-09-22T09:26:36.017Z",
"target": "quilt-native",
"seconds": "78.193",
"outcome": "Succeeded",
"id": 1,
"start": "2017-09-22T09:25:17.824Z",
"warnings": 1,
"name": "20170922092618",
"cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
}
}
</literallayout>
</para>
</section>
</section>
<section id='toaster-useful-commands'>
<title>Useful Commands</title>