This tutorial will guide through the process of setting up and using the SlapOS Monitor, a tool to observe the health of a SlapOS network.
Think of SlapOS providing a macro view on a network and the Monitor giving the corresponding micro view into underlying process, logs and Promises.
This tutorial requires to have a computer with a SlapOS node installed and as well as access to an account on a SlapOS Master (install SlapOS Master). It is also mandatory to have a Frontend Slave to access the SlapOS Master (the steps are included in the setup of the SlapOS node (COMP-0).
The SlapOS Monitor is a stand-alone application hosted on Nexedi's OfficeJS appstore (more information on OfficeJS).
The Monitor can connect to and observe any SlapOS deployment. It covers network and individual computers status as well as partition processes running. Once connected with a SlapOS deployment, the Monitor is tightly integrated into the SlapOS Master Dashboard and can be accessed in multiple ways which are alos shown in this section.
The easiest way to access the monitor is via the Access button on the side menu of the SlapOS Dashboard. Click Access Monitor in the left menu.
The Monitor has a different side panel than the SlapOS Dashboard:
By default, the Monitor is not connected to any application. It is necessary to load a deployment configuration (called data sources) to "feed" the Monitor with the network parameters to observe. This configuration can be provided directly (using Settings Content) or via a remote storage.
To continue select SlapOS Master ERP5 and click Proceed
The monitor requires the configuration of your instance to sync. To provide it, paste the the Frontend url of your SlapOS Master and append /hateoas/. In the example, this is https://master.slaptest.erp5.net/hateoas/.
The Frontend url can be found in the connection parameters of the Frontend Slave being used to access the SlapOS Master. Note, it is not possible to use the monitor with the default IPv4 address.
Click Proceed to launch synchronisation of SlapOS Master and the monitor.
Once synchronisation finishes the Monitor will load and display the list of Promises for the SlapOS Master.
Promises in SlapOS are executables doing arbitrary tasks and exiting with exit code 0 ("it works") or greater ("it doesn't work"). Everything in SlapOS is based on such Promises in order to automate the management of a SlapOS network. In case a Promise fails (eg a computer not responding), a ticket will be created on the SlapOS Master in order for a user to follow up with this failing promise (more info in Understanding SlapOS Promises).
Note, that the Monitor reports detailed instance status but does not provide any management functions such as handling of tickets. This has to be done in the SlapOS Master Dashboard which in turn only displays the global status of an instance (green, orange, red). Also note that the Monitor works autonomously from the SlapOS Master, so even if the Master is down, the Monitor will continue working.
Finally, as the Monitor was not accessed for a specific computer or instance, it will show the global network status. Clicking on one of the red/yellow/green computer or instance buttons will load the monitor with a scope set on the respective computer/instance.
You can use the Filter button in the subheader and the search field to filter the list of promises.
One common use case for the filter is to display only erroring promises by filtering for the status field with exact match ERROR. This helps to keeping track of what to fix only.
Head back to the SlapOS Dashboard to see the different ways to accessing the monitor.
On the map displaying your sites (how to classify computers in a network), click on the small screen icon next to the site name (next to FIRST-SITE on the map!).
This will list all promises for software instances deployed on this computer. In the example, the computer is the COMP-0 machine which runs an instance of the Re6st Registry for connecting nodes in a network, the Frontend (Apache) for managing access between nodes and the monitor as well as the Frontend Slave (providing the url we used to connect to the monitor). The status of all instances can be monitored here.
Head back to the SlapOS Master Dashboard
In the side menu, click on Services to access all services on your SlapOS Network. Click on one of the Instances buttons on a service.
This will show the list of Hosting Subscriptions of this service (a Hosting Subscription is the instantiation of an installed software on a computer partition of a SlapOS node) along with their status.
Head back to the SlapOS Master Dashboard.
In the side menu, click on Servers to access all services on your SlapOS network. Click on one the Computers without any partitions (instances).
If the server is still "empty" (no instances of software have been installed yet), the monitor will not report anything.
This section will show how the monitor can be used to analyse data collected from a SlapOS network.
Stay in the Monitor and click Software Instances to access the list of all instances in the network. A software instance is one instantiated and configured instance of a software available on the SlapOS Master and installed on a computer).
Click on any of the available software instances (the table at the bottom).
The detailed view of an instance will provide configuration and promise status information for this instance. All promises are listed in the bottom table, the global promise status is shown on top.
Click on of the promises in the bottom table.
This is the overview of the history of promise failures (similar to the graph displayed on the previous menu).
Go back to the software instance (clicking on the header). Then click on Processes in the subheader.
This will show details on this specific Promise and the processes it contains.
Click on "Resources" in the subheader.
This will show details on the resource consumption.
You can switch back to the processes by clicking Processes in the subheader, then click in the top navigation to access the main instance view again.
Click on Access Private Files.
This allows to access the private files of this computer partition.
Click on log to continue
This will open the folder of log files. Open one of the files.
Accessing instances like this allows to easily monitor and dig down into log files of a specific service in case of a failing Promise for example.