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