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

# 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.

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

# 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:

{"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.