summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/toaster-manual/toaster-manual-reference.xml164
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 @@
719 </section> 719 </section>
720 </section> 720 </section>
721 721
722
723 <section id='remote-toaster-monitoring'>
724 <title>Remote Toaster Monitoring</title>
725
726 <para>
727 Toaster has an API that allows remote management applications to
728 directly query the state of the Toaster server and its builds
729 in a machine-to-machine manner.
730 This API uses the
731 <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink>
732 interface and the transfer of JSON files.
733 For example, you might
734 monitor a build inside a container through well supported
735 known HTTP ports in order to easily access a Toaster server
736 inside the container.
737 In this example, when you use this direct JSON API, you avoid
738 having web page parsing against the display the user sees.
739 </para>
740
741 <section id='checking-health'>
742 <title>Checking Health</title>
743
744 <para>
745 Before you use remote Toaster monitoring, you should do
746 a health check.
747 To do this, ping the Toaster server using the following call
748 to see if it is still alive:
749 <literallayout class='monospaced'>
750 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/health
751 </literallayout>
752 Be sure to provide values for <replaceable>host</replaceable>
753 and <replaceable>port</replaceable>.
754 If the server is alive, you will get the response HTML:
755 <literallayout class='monospaced'>
756 &lt;!DOCTYPE html&gt;
757 &lt;html lang="en"&gt;
758 &lt;head&gt;&lt;title&gt;Toaster Health&lt;/title&gt;&lt;/head&gt;
759 &lt;body&gt;Ok&lt;/body&gt;
760 &lt;/html&gt;
761 </literallayout>
762 </para>
763 </section>
764
765 <section id='determining-status-of-builds-in-progress'>
766 <title>Determining Status of Builds in Progress</title>
767
768 <para>
769 Sometimes it is useful to determine the status of a build
770 in progress.
771 To get the status of pending builds, use the following call:
772 <literallayout class='monospaced'>
773 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/building
774 </literallayout>
775 Be sure to provide values for <replaceable>host</replaceable>
776 and <replaceable>port</replaceable>.
777 The output is a JSON file that itemizes all builds in
778 progress.
779 This file includes the time in seconds since each
780 respective build started as well as the progress of the
781 cloning, parsing, and task execution.
782 The following is sample output for a build in progress:
783 <literallayout class='monospaced'>
784 {"count": 1,
785 "building": [
786 {"machine": "beaglebone",
787 "seconds": "463.869",
788 "task": "927:2384",
789 "distro": "poky",
790 "clone": "1:1",
791 "id": 2,
792 "start": "2017-09-22T09:31:44.887Z",
793 "name": "20170922093200",
794 "parse": "818:818",
795 "project": "my_rocko",
796 "target":
797 "core-image-minimal"
798 }]
799 }
800 </literallayout>
801 </para>
802 </section>
803
804 <section id='checking-status-of-builds-completed'>
805 <title>Checking Status of Builds Completed</title>
806
807 <para>
808 Once a build is completed, you get the status when you use
809 the following call:
810 <literallayout class='monospaced'>
811 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/builds
812 </literallayout>
813 Be sure to provide values for <replaceable>host</replaceable>
814 and <replaceable>port</replaceable>.
815 The output is a JSON file that itemizes all complete builds,
816 and includes build summary information.
817 The following is sample output for a completed build:
818 <literallayout class='monospaced'>
819 {"count": 1,
820 "builds": [
821 {"distro": "poky",
822 "errors": 0,
823 "machine":
824 "beaglebone",
825 "project": "my_rocko",
826 "stop": "2017-09-22T09:26:36.017Z",
827 "target": "quilt-native",
828 "seconds": "78.193",
829 "outcome": "Succeeded",
830 "id": 1,
831 "start": "2017-09-22T09:25:17.824Z",
832 "warnings": 1,
833 "name": "20170922092618"
834 }]
835 }
836 </literallayout>
837 </para>
838 </section>
839
840 <section id='determining-status-of-a-specific-build'>
841 <title>Determining Status of a Specific Build</title>
842
843 <para>
844 Sometimes it is useful to determine the status of a specific
845 build.
846 To get the status of a specific build, use the following
847 call:
848 <literallayout class='monospaced'>
849 http://<replaceable>host</replaceable>:<replaceable>port</replaceable>/toastergui/api/build/<replaceable>ID</replaceable>
850 </literallayout>
851 Be sure to provide values for <replaceable>host</replaceable>,
852 <replaceable>port</replaceable>, and <replaceable>ID</replaceable>.
853 In order to provide the value for <replaceable>ID</replaceable>,
854 you must check the status of the completed build.
855 See the
856 "<link linkend='checking-status-of-builds-completed'>Checking Status of Builds Completed</link>"
857 section for more information.
858 </para>
859
860 <para>
861 The output is a JSON file that itemizes the specific build
862 and includes build summary information.
863 The following is sample output for a specific build:
864 <literallayout class='monospaced'>
865 {"build":
866 {"distro": "poky",
867 "errors": 0,
868 "machine": "beaglebone",
869 "project": "my_rocko",
870 "stop": "2017-09-22T09:26:36.017Z",
871 "target": "quilt-native",
872 "seconds": "78.193",
873 "outcome": "Succeeded",
874 "id": 1,
875 "start": "2017-09-22T09:25:17.824Z",
876 "warnings": 1,
877 "name": "20170922092618",
878 "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
879 }
880 }
881 </literallayout>
882 </para>
883 </section>
884 </section>
885
722 <section id='toaster-useful-commands'> 886 <section id='toaster-useful-commands'>
723 <title>Useful Commands</title> 887 <title>Useful Commands</title>
724 888