From b02ece66c0a3132e79017f6056e904c19aa8dd39 Mon Sep 17 00:00:00 2001 From: Kristi Rifenbark Date: Wed, 11 Oct 2017 18:00:57 -0700 Subject: 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 Signed-off-by: Richard Purdie --- .../toaster-manual/toaster-manual-reference.xml | 164 +++++++++++++++++++++ 1 file changed, 164 insertions(+) (limited to 'documentation') 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 @@ + +
+ Remote Toaster Monitoring + + + 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 + REST + 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. + + +
+ Checking Health + + + 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: + + http://host:port/health + + Be sure to provide values for host + and port. + If the server is alive, you will get the response HTML: + + <!DOCTYPE html> + <html lang="en"> + <head><title>Toaster Health</title></head> + <body>Ok</body> + </html> + + +
+ +
+ Determining Status of Builds in Progress + + + Sometimes it is useful to determine the status of a build + in progress. + To get the status of pending builds, use the following call: + + http://host:port/toastergui/api/building + + Be sure to provide values for host + and port. + 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: + + {"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" + }] + } + + +
+ +
+ Checking Status of Builds Completed + + + Once a build is completed, you get the status when you use + the following call: + + http://host:port/toastergui/api/builds + + Be sure to provide values for host + and port. + 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: + + {"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" + }] + } + + +
+ +
+ Determining Status of a Specific Build + + + Sometimes it is useful to determine the status of a specific + build. + To get the status of a specific build, use the following + call: + + http://host:port/toastergui/api/build/ID + + Be sure to provide values for host, + port, and ID. + In order to provide the value for ID, + you must check the status of the completed build. + See the + "Checking Status of Builds Completed" + section for more information. + + + + 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: + + {"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" + } + } + + +
+
+
Useful Commands -- cgit v1.2.3-54-g00ecf