smon/README.md

169 lines
5.1 KiB
Markdown
Raw Permalink Normal View History

2024-06-30 12:28:49 +02:00
---
gitea: none
include_toc: true
---
# Smon
Smon (Simple Monitoring) is a small and easy to maintain single user monitoring system. \
It is developed for the developer's personal need for monitoring a small number of datapoints and get notifications,
without having to maintain a huge system like Zabbix. \
It is also possible to troubleshoot with historial data and graphs.
There is no concept of users or passwords. \
If a requirement, authentiation and authorization can be handled by a HTTP reverse proxy.
All data is sent to the system via an HTTP request to /entry/`datapoint_name`. \
Smon can't poll data.
2024-06-30 12:54:58 +02:00
## Screenshots
| Problems | Datapoints | Graphs | Triggers |
| --- | --- | --- | --- |
| <a href="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/problems.jpg"><img src="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/problems_small.jpg"></a> | <a href="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/datapoints.jpg"><img src="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/datapoints_small.jpg"></a> | <a href="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/datapoint_values.jpg"><img src="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/datapoint_values_small.jpg"></a> | <a href="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/triggers.jpg"><img src="https://git.ahall.se/magnus/smon/raw/branch/main/screenshots/triggers_small.jpg"></a> |
2024-05-01 22:39:55 +02:00
# Quick start
2024-06-30 12:28:49 +02:00
1) Create an empty database (smon only supports PostgreSQL).
1) Create the configuration file (default ~/.config/smon.yaml).
1) Run ./smon (will create the database schema).
2024-05-01 22:39:55 +02:00
2024-06-30 12:28:49 +02:00
## Configuration
2024-05-01 22:34:34 +02:00
```yaml
network:
address: "[::]"
port: 9000
websocket:
domains:
- localhost
- smon.example.com
database:
host: localhost
port: 5432
name: smon
username: smon
password: you_wish
application:
logfile: /var/log/smon.log
2024-05-30 17:22:38 +02:00
nodata_interval: 60
2024-05-01 22:34:34 +02:00
```
2024-05-01 22:39:55 +02:00
2024-06-30 12:28:49 +02:00
## Sending data to datapoints
2024-05-01 22:39:55 +02:00
2024-06-29 12:08:40 +02:00
`curl -d 200 http://localhost:9000/entry/datapoint_name`
2024-06-30 12:28:49 +02:00
Use `date '+%FT%T%z'` to get a value from systems in correct format.
2024-06-29 12:08:40 +02:00
2024-06-30 12:28:49 +02:00
# Concepts
Core concepts in Smon are:
* datapoints.
* triggers.
* problems.
* notifications.
* areas.
## Datapoints
A datapoint has a unique name. Recommended is to use only a-z, A-Z, 0-9, dots, dashes and underscores for easier handling in URLs and trigger conditions.
There are three data types:
* INT.
* STRING.
* DATETIME.
INT accepts values like -100, 0, 137 and 29561298561 and is stored in the int8 postgresql type.
STRING is text data and stored by an unlimited varchar.
DATETIME is a date with time and timezone in the format of `2006-01-02T15:04:05+02:00` or `2006-01-02T15:04:05+0200`. Stored in a field of timestamptz.
Recommended is to provide from where (machine, system or script location...) the data is being pushed to Smon in the comment field.
## Triggers
Triggers have datapoints the expression is being able to use.
Expressions are written with the [[https://expr-lang.org/|Expr]] language. See the [[https://expr-lang.org/docs/language-definition|language reference]] for available functions and syntax.
The trigger is evaluating the expression when data is entered through the /entry/`datapoint_name` URL and a problem is issued when the expression returns `true`.
2024-06-30 12:58:27 +02:00
### Examples
The disk usage (reported in percent) for server01 has exceeded 90%:
`server01_disk_usage_root > 90`
It was more than 48 hours since Borg finished on server01:
`(now() - borg_server01_finished).Hours() > 48`
2024-06-30 12:28:49 +02:00
## Problems
One or more datapoints that trips a trigger issues a problem.
Problems are archived in the database and can be looked up historically.
A page of current problems is available to see the current problem state, either as a list or categorised.
Problems can be acknowledged if they are known problems that will not be currently fixed.
## Notifications
2024-07-04 19:21:02 +02:00
Smon has a couple of notification services (currently [[https://ntfy.sh|NTFY]], [[https://pushover.net|Pushover]] and script).
2024-06-30 12:28:49 +02:00
Services are added with a prio. The service with the lowest prio is tried first. \
If sending through the service fails, the next service is tried and so on until one succeeds.
What is sent isn't configurable (for now). What is sent is:
* PROBLEM (when a problem is created) or OK (when a trigger evaluates to false).
* Trigger name
2024-06-30 12:58:27 +02:00
2024-06-30 12:28:49 +02:00
## NTFY
An URL is provided to the topic which should receive the notifications.
2024-07-04 19:21:02 +02:00
## Pushover
The user key and API key for the Pushover application is needed. Additionally, a device key can be specified as well.
2024-06-30 12:28:49 +02:00
## Script
The script service is defined with a filename.
The script is called with three parameters:
1) Problem ID
1) Acknowledge URL
1) Message
## Areas
Go to the `Config` icon to add areas. These are available to categorize triggers and problems for easier troubleshooting.
Each area has sections to further group problems and triggers.
# Development
A couple of small notes on development.
## Theming
* Add theme to select tag in `/views/pages/configuration.gotmpl`.
* Create `/static/less/theme-<theme-name>.less`.
* Create `/static/less/<theme-name>.less`.
2024-07-04 19:21:02 +02:00
* Copy a theme directory under `/static/images/` to the new name.