feat: accept, store and expose client diagnostics
CI / chart (push) Successful in 3s
CI / test (push) Successful in 2m20s
CI / chart-push (push) Successful in 6s
CI / image (push) Successful in 3m39s

- V11 client_logs table with per-user storage and retention/pruning
- POST/GET/DELETE /logs with batch validation, rate limit and admin access
- redact bearer tokens, Authorization headers and query/JSON secrets twice
- add X-Request-Id to responses and include it in the server log pattern
- report client error entries immediately in the server log
- scripts/logs.sh for source-side retrieval and clearing
- chart knobs CLIENT_LOG_RETENTION_DAYS and CLIENT_LOG_MAX_ROWS_PER_USER
This commit is contained in:
TapTap committed 2026-11-20 13:43:05 +00:00
1 parent 91312faa1c
commit 44b75c4d4d
19 files changed
+981 -5

No files matched your search

+42 -1
View File
@@ -100,6 +100,8 @@ Everything is environment variables:
| `DEEZER_API_BASE` | `https://api.deezer.com` | Public Deezer API base |
| `LOUDNESS_ENABLED` | `true` | Measure each file and expose a per-track gain |
| `LOUDNESS_TARGET_LUFS` | `-16` | Integrated loudness target (`-30` to `-5`) |
| `CLIENT_LOG_RETENTION_DAYS` | `14` | Days uploaded client diagnostics are kept |
| `CLIENT_LOG_MAX_ROWS_PER_USER` | `20000` | Newest diagnostic rows kept per user |
### `users.yaml`
@@ -114,6 +116,37 @@ Passwords live only in this file (use a Vault-managed Secret in Kubernetes).
`admin` is only needed for the maintenance scan endpoints. Old `folders:` keys
are accepted and ignored.
## Client diagnostics
The apps keep a small local ring buffer (500 entries) of warnings, errors and
crashes. Warnings and errors are flushed immediately, so the line that explains
a crash survives it; info entries are batched. When signed in, the client uploads
up to 100 entries per minute to `POST /api/v1/logs`, tagged with a random install
id, platform, app version and per-run session id.
Privacy and safety:
- `Authorization` headers, `Bearer` tokens, `token=`/`password=`/`arl=` query
parameters and JSON secret fields are replaced with `***` on the client
**and** again on the server.
- The server stores rows per user; a user can only read their own logs. An
administrator can pass `user=<name>`.
- Retention defaults to 14 days and 20,000 rows per user; both are configurable.
- A rejected batch (HTTP 400/413/422) is dropped so it cannot block later logs.
Inspect them with the helper:
```bash
scripts/logs.sh --server https://audiomanager.example.com --user alice \
--level warn --limit 100
# administrators can read another account
scripts/logs.sh --server ... --user admin --target alice
# clear after investigating
scripts/logs.sh --server ... --user alice --clear
```
The password is read from `LOGS_PASSWORD` or prompted; it is never stored.
## Native API
All endpoints are under `/api/v1` and require a bearer token, except login.
@@ -126,10 +159,18 @@ Media URLs may use `?token=` because HTML audio and images cannot send headers.
| `POST` | `/auth/login` | `{username,password,deviceName,platform}` → token |
| `POST` | `/auth/logout` | Revoke the current token |
| `GET` | `/me` | Current user |
| `GET` | `/info` | Default source, Deezer quality and loudness settings |
| `GET` | `/info` | Default source, Deezer quality, loudness and log retention |
| `GET` | `/auth/devices` | List device tokens |
| `DELETE` | `/auth/devices/{id}` | Revoke a device |
### Diagnostics
| Method | Path | Purpose |
|---|---|---|
| `POST` | `/logs` | Upload a client diagnostics batch |
| `GET` | `/logs` | List diagnostics (`level`, `device`, `since`, `before`, `limit`; admins may add `user`) |
| `DELETE` | `/logs` | Delete the current user's (or, for admins, a named user's) diagnostics |
### Moods
| Method | Path | Purpose |