Web-Service to collect system usage statistics.
- category: Application
- copyright: 2022-2024 Nicola Asuni - Tecnick.com LTD
- license: LICENSE
- cvs: https://github.com/tecnickcom/rpistat
Web-Service to collect system usage statistics.
This project was started to collect system usage statistics from a remote Raspberry PI 4 but it can be compiled and used with other systems too.
The statistics are exposed both via the /stats Web API endpoint and Prometheus metrics at /metrics.
An HomeAssistant sensor and template to collect those metrics can be found in the resources/HomeAssistant/ directory.
curl 192.168.1.2:65501/stats
{
"datetime": "2023-06-27T07:03:54Z",
"timestamp": 1687849434569669934,
"hostname": "rpi4",
"uptime": 680189000000000,
"memory_total": 1005973504,
"memory_free": 587198464,
"memory_used": 418775040,
"memory_usage": 0.41628833993623754,
"load_1m": 0,
"load_5m": 0,
"load_15m": 0,
"temperature_cpu": 44.303,
"disk_total": 31109140480,
"disk_free": 27586793472,
"disk_used": 3522347008,
"disk_usage": 0.11322546858099501,
"network": [
{
"nic": "eth0",
"rx": 163621268,
"tx": 113155073
},
{
"nic": "wlan0",
"rx": 8225055,
"tx": 1327982
},
{
"nic": "eth1",
"rx": 24906794,
"tx": 18615044
}
]
}
- Style and Conventions
- Requirements
- Quick Start
- Running all tests
- Documentation
- Usage
- Configuration
- Examples
- Logs
- Metrics
- Profiling
- OpenAPI
- Docker
For the general style and conventions, please refer to external documents: https://github.com/uber-go/guide/blob/master/style.md
- check-jsonschema to check the validity of the JSON configuration files against the JSON schema.
sudo pip install --upgrade check-jsonschemaTo quickly get started with this project, follow these steps:
- Ensure you ahev installed the latest Go version and Python3 for some extra tests.
- Clone the repository:
git clone https://github.com/tecnickcom/rpistat.git. - Change into the project directory:
cd rpistat. - Install the required dependencies and test everything:
DEVMODE=LOCAL make x.
Now you are ready to start developing with rpistat!
This project includes a Makefile that allows you to test and build the project in a Linux-compatible system with simple commands.
All the artifacts and reports produced using this Makefile are stored in the target folder.
Alternatively, everything can be built inside a Docker container using the command make dbuild that uses the environment defined at resources/docker/Dockerfile.dev.
To see all available options:
make helpBefore committing the code, please check if it passes all tests using
make xthat is an alias for:
DEVMODE=LOCAL make format clean mod deps generate qa build docker dockertestThe README.md documentation file is generated using the source templates in doc/src via make gendoc command.
To update links and common information edit the file doc/src/config.yaml in YAML format.
The schema of the configuration file is defined by the JSON schema: doc/src/config.schema.json.
The document templates are defined by the *.tmpl files in gomplate-compatible format.
To regenerate the static documentation file:
make gendocrpistat [flags]
Flags:
-c, --configDir string Configuration directory to be added on top of the search list
-f, --logFormat string Logging format: CONSOLE, JSON
-o, --loglevel string Log level: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUGOnce the application has being compiled with make build, it can be quickly tested:
target/usr/bin/rpistat -c resources/test/etc/rpistatThis program logs the log messages in JSON format:
{
"level": "info",
"timestamp": 1595942715776382171,
"msg": "Request",
"program": "rpistat",
"version": "0.0.0",
"release": "0",
"hostname":"myserver",
"request_id": "c4iah65ldoyw3hqec1rluoj93",
"request_method": "GET",
"request_path": "/uid",
"request_query": "",
"request_uri": "/uid",
"request_useragent": "curl/7.69.1",
"remote_ip": "[::1]:36790",
"response_code": 200,
"response_message": "OK",
"response_status": "success",
"response_data": "avxkjeyk43av"
}
Logs are sent to stderr by default.
The log level can be set either in the configuration or as command argument (logLevel).
This service provides Prometheus metrics at the /metrics endpoint.
This service provides PPROF profiling data at the /pprof endpoint.
The pprof data can be analyzed and displayed using the pprof tool:
go get github.com/google/pprof
Example:
pprof -seconds 10 -http=localhost:8182 http://INSTANCE_URL:PORT/pprof/profile
The rpistat API is specified via the OpenAPI 3 file: openapi.yaml.
The openapi file can be edited using the Swagger Editor:
docker pull swaggerapi/swagger-editor
docker run -p 8056:8080 swaggerapi/swagger-editor
and pointing the Web browser to http://localhost:8056
To build a Docker scratch container for the rpistat executable binary execute the following command:
make docker
To manually create the container you can execute:
docker build --tag="tecnickcom/rpistatdev" .
To log into the newly created container:
docker run -t -i tecnickcom/rpistatdev /bin/bash
To get the container ID:
CONTAINER_ID=`docker ps -a | grep tecnickcom/rpistatdev | cut -c1-12`
To delete the newly created docker container:
docker rm -f $CONTAINER_ID
To delete the docker image:
docker rmi -f tecnickcom/rpistatdev
To delete all containers
docker rm $(docker ps -a -q)
To delete all images
docker rmi $(docker images -q)
After building the executable binary with make build:
- Copy the
target/usr/bin/rpistatfile into/usr/bin/rpistatin the target system. - Set the file is executable with:
sudo chmod +x /usr/bin/rpistat. - Copy and edit the configuration file
resources/etc/rpistat/config.jsoninto/etc/rpistat/config.jsonin the target system. - Copy the service file
resources/etc/systemd/system/rpistat.serviceinto/etc/systemd/system/rpistat.servicein the target system and enable it:
sudo systemctl daemon-reload
sudo systemctl enable rpistat.service
sudo systemctl start rpistat.service