diff options
-rw-r--r-- | documentation/toaster-manual/toaster-manual-reference.xml | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml index 2a1b92daeb..6c51ad1d24 100644 --- a/documentation/toaster-manual/toaster-manual-reference.xml +++ b/documentation/toaster-manual/toaster-manual-reference.xml @@ -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'> + <!DOCTYPE html> + <html lang="en"> + <head><title>Toaster Health</title></head> + <body>Ok</body> + </html> + </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> |