A light-weight HTTP-based monitoring application.
- Client nodes push data to a server via HTTP POST.
- Server tracks that the data is kept up to date and remains within expected boundaries.
- Clients interact via simple HTTP requests and require no special software, just curl (or wget) and crontab.
- All communication is HTTPS and each node being monitored has its own access credentials.
- A simple Android application provides warning notifications by polling the API every 15 minutes to check for warnings.
This README is a work in progress. Feel free to ask questions.
Monitoring the uptime of a server requires a small shell script to collect the data and make the request. For example, on a node called 'pi0' you could have:
#!/bin/bash set -eu DATA="uptime=$(cat /proc/uptime | cut -d ' ' -f 1)" curl -d "$DATA" -u "pi0:1234567890abcdefghijklmno" "https://lookfar.example.com/update/pi0"
The can them be scheduled to run every 5 minutes in crontab:
*/5 * * * * /home/pi/bin/lookfar >> /home/pi/log/lookfar.log 2>&1
Since it is expect that this datum will be refreshed every 5 minutes, lets change the the expire time from the default of 24 hours to 15 minutes (leave room for reboots) so that we are alerted more promptly if it stops working:
curl -u "user_name:shared_password" https://lookfar.example.com/admin/node/pi0/uptime/expire -d "15m"
And we are finished. In Lookfar's UI this will now look something like this:
| node | updated | key | value | threshold | expire | flag | pi0 | 2012-09-15 09:05:02 | uptime | 208185.41 | - | 15m | OK
This example assumes that the node for pi0 was already configured. A threshold can be defined to trigger when a variable no longer meets expectations. The full API is detailed below.
More detailed examples for monitoring backup systems, home automation, etc. can be written up on request.
- Currently Lookfar does not support multi-tenant and a separate install is required for each user.
- There is one password that is used restrict access to the UI and admin functions.
- Each node that submits data has its own password issues by the server that can not be used for any other function.
The server is a simple Java application with an embedded Jetty HTTP server that can be deployed to most places. Lookfar is currently geared towards deploying on Heroku but it is easy to run elsewhere, just export the SAME environment variables that Heroku would. Lookfar should report any misconfigurations on startup.
A launch script is provided that will trigger the Maven build and then launch the application. This requires Maven and the Ruby gem 'foreman' to be installed.
The environment variable "PORT" can be set to change the port it will listen on. Environment variables can be set in $HOME/.lookfar and this file will be read in on start up.
./foreman-start
Postgresql is required to store the last value of each datum and the associated expire time and threshold.
create table nodes (node VARCHAR(16), updated TIMESTAMP, pass VARCHAR(96)); create table updates (node VARCHAR(16), updated TIMESTAMP, key VARCHAR(255), value VARCHAR(255), threshold VARCHAR(255), expire VARCHAR(255));
The database connection is configured by setting an environment variable, for example:
DATABASE_URL="postgres://user:password@mydbserver.example.com:5432/mydbname"
Lookfar has a minimalistic UI that can be used in a browser or on a command line:
curl -u "user_name:shared_password" https://lookfar.example.com/admin/text
List nodes:
curl -u "user_name:shared_password" https://lookfar.example.com/admin/node
Create a node or reset a node's password:
curl -u "user_name:shared_password" -X PUT https://lookfar.example.com/admin/node/exampleNode
Delete a node:
curl -u "user_name:shared_password" -X DELETE https://lookfar.example.com/admin/node/exampleNode
List all updates in text format:
curl -u "user_name:shared_password" https://lookfar.example.com/admin/text
List all updates in JSON format:
curl -u "user_name:shared_password" https://lookfar.example.com/admin/updates
Reset an update back to pending:
curl -u "user_name:shared_password" -X PUT https://lookfar.example.com/admin/node/exampleNode/var1
Delete an update:
curl -u "user_name:shared_password" -X DELETE https://lookfar.example.com/admin/node/exampleNode/var1
Tail updates via websocket (https://einaros.github.io/ws/):
npm install -g ws wscat --auth "user_name:shared_password" -c https://lookfar.example.com/admin/tailupdates
Write an update:
curl -u "exampleNode:node_password" -d "var1=123&var2=456" https://lookfar.example.com/update/exampleNode
Default expire period is 1d. Set custom expire times using strings like 1m, 2h, 3d.
Set a custom period:
curl -u "user_name:shared_password" -d "1h" https://lookfar.example.com/admin/node/exampleNode/var1/expire
Clear a custom period (reverts to default):
curl -u "user_name:shared_password" -X DELETE https://lookfar.example.com/admin/node/exampleNode/var1/expire
A rule is what the value should be. Breaking the rule triggers a warning.
| rule | description |
|---|---|
==0
| Treat value as a string and must equal a string. |
<45, >45, <=45, >=45
| Treat value as a number and compare to a number. |
=~[0 ]
| Treat value as a string and must match a regular expression. |
Set a threshold:
curl -u "user_name:shared_password" -d "==0" https://lookfar.example.com/admin/node/exampleNode/var1/threshold
Clear a threshold:
curl -u "user_name:shared_password" -X DELETE https://lookfar.example.com/admin/node/exampleNode/var1/threshold
U GET / + A GET /admin/user + A GET /admin/user/<userName> + A PUT /admin/user/<userName> + A DELETE /admin/user/<userName> + U POST /admin/password U GET /admin/node U GET /admin/node/<nodeName> U PUT /admin/node/<nodeName> U DELETE /admin/node/<nodeName> U GET /admin/node/<nodeName>/<keyName> U PUT /admin/node/<nodeName>/<keyName> U DELETE /admin/node/<nodeName>/<keyName> U GET /admin/node/<nodeName>/<keyName>/expire U POST /admin/node/<nodeName>/<keyName>/expire U DELETE /admin/node/<nodeName>/<keyName>/expire U GET /admin/node/<nodeName>/<keyName>/threshold U POST /admin/node/<nodeName>/<keyName>/threshold U DELETE /admin/node/<nodeName>/<keyName>/threshold U GET /admin/updates N POST /update/<nodeName>