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

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>

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'>
+     &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>