90 lines
2.6 KiB
Markdown
90 lines
2.6 KiB
Markdown
# metrica
|
||
|
||
AI README PLACEHOLDER
|
||
|
||
```
|
||
POST /api/{script}/ push JSON (requires a token)
|
||
GET /api/{script}/ read JSON (requires a token)
|
||
GET / dashboard (open)
|
||
GET /health liveness
|
||
```
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
# 1. configure a token (or let the app print a temporary one on first start)
|
||
cp .env.example .env
|
||
$EDITOR .env
|
||
|
||
# 2. run it (uv installs deps into an ephemeral env automatically)
|
||
uv run app.py
|
||
# → http://127.0.0.1:8000
|
||
```
|
||
|
||
If you don't set `METRICA_TOKENS`, the app generates a temporary token and
|
||
prints it to the console on startup.
|
||
|
||
## Pushing data
|
||
|
||
Any valid token authorizes any script. A script is auto-created the first time
|
||
it pushes — no registration step.
|
||
|
||
```bash
|
||
TOKEN=change-me-token-1
|
||
|
||
# a single number
|
||
curl -X POST http://127.0.0.1:8000/api/nightly-backup/ \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d "$(ls /var/backups | wc -l)"
|
||
|
||
# a structured payload
|
||
curl -X POST http://127.0.0.1:8000/api/disk-check/ \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"files": 1423, "used_gb": 38.2, "status": "ok"}'
|
||
```
|
||
|
||
`X-API-Key: $TOKEN` works as an alternative to the `Authorization` header.
|
||
|
||
The dashboard draws a sparkline from the first numeric value it finds in each
|
||
payload (so both examples above chart automatically).
|
||
|
||
### From cron
|
||
|
||
```cron
|
||
# count files in a directory every hour
|
||
0 * * * * curl -sf -X POST https://metrica.example.com/api/inbox-count/ \
|
||
-H "Authorization: Bearer $METRICA_TOKEN" \
|
||
-d "$(ls /srv/inbox | wc -l)"
|
||
```
|
||
|
||
## Storage
|
||
|
||
Each script is one file: `data/{script}.jsonl`. Every push appends one line:
|
||
|
||
```json
|
||
{"ts": "2026-07-08T16:42:00Z", "data": {"files": 1423, "used_gb": 38.2}}
|
||
```
|
||
|
||
Delete a script by deleting its file. Trim history with `tail`. Back it up by
|
||
copying the `data/` directory.
|
||
|
||
## Configuration
|
||
|
||
| Variable | Default | Purpose |
|
||
|---|---|---|
|
||
| `METRICA_TOKENS` | *(generated)* | Comma/space-separated valid push tokens |
|
||
| `METRICA_TOKENS_FILE` | – | File of tokens, one per line |
|
||
| `METRICA_DATA_DIR` | `data` | Where JSONL files are written |
|
||
| `METRICA_MAX_HISTORY` | `100` | Recent points shown per script |
|
||
| `METRICA_HOST` / `METRICA_PORT` | `127.0.0.1` / `8000` | Bind address |
|
||
|
||
## Notes on security
|
||
|
||
- The **push and read APIs require a token**; script names are restricted to
|
||
`[A-Za-z0-9_-]` so they can't escape the data directory.
|
||
- The **dashboard is open** (read-only). If the metrics are sensitive, keep the
|
||
service on a private network or put a reverse proxy / VPN / basic-auth in
|
||
front of `/`.
|
||
- Always run behind HTTPS in production so tokens aren't sent in clear text.
|