grabowski
779728e38b
Phase 3 of docs/RUST_REWRITE.md: rust/collector/src/web (axum) serves what
the FastAPI app (src/web_api.py) served, so one process collects, forecasts,
notifies and serves. With WEB_LISTEN=0.0.0.0:8000 it runs inside
`ping-collector run`; `ping-collector serve` runs it alone.
Same routes, parameters, JSON fields and field order, status codes,
{"detail": ...} errors and pydantic-style 422 lists, Cache-Control, gzip
(>500 B), CORS, Umami API tracking, the dashboard and static files, and the
stale-while-revalidate response caches (now with byte budgets: a history
response can be 10 MB). /docs is the same Swagger UI (+ /redoc); its OpenAPI
document is built from the route table, whose per-route parameter
declarations also validate the requests, so docs and behaviour cannot drift.
Python output conventions are kept: isoformat(), round(), numpy's pairwise
sums (catchment means), Python's summation order (skill metrics).
scripts/api_parity.py compares the two servers route by route on one
database (53 cases incl. errors, admin and static files; query values vary
per run so FastAPI's caches answer fresh). Locally: 53 identical; the
station CRUD writes byte-identical stations.json files; the skill/trend
logic matches on 9 station/horizon pairs with synthetic model versions.
Intended differences: /health counts the ThaiWater telemetry of the same
gauges while RID lags (as the notifier); /scraping/status adds the collector
version and last forecast run; an old stored forecast is served marked
X-Data-Stale instead of recomputed; /sensors/thaiwater is cached a minute;
.geojson is served as application/geo+json. Load (local, 16 clients): the
dashboard's routes 1375 vs 552 req/s, uncached history 714 vs 53 req/s;
25 MB resident when serving only.
Matrix (MATRIX_*): the notifier sends the room the transitions ntfy gets
(per station, outlook, feed; not ntfy's per-topic summaries), each once,
with its own matrix: keys in notification_state, seeded from ntfy's on first
use so nothing already announced repeats. Checked against a fake homeserver.
It replaces the `run.py --alert-check` cron job (repeated alerts every 15
min), which install_collector.sh now comments out (crontab backup kept).
install_collector.sh: --check-api (ping-collector serve on :8001 next to
FastAPI, api_parity.py), --cutover-api (refuses on a difference; sets
WEB_LISTEN, stops and disables water-monitor.service), --rollback-api;
--rollback-forecast and --rollback bring the Python app back as server.
ping-collector.service: MemoryMax 512M. Config::from_vars for tests; route
tests against a throwaway schema.
84 lines
2.9 KiB
Markdown
84 lines
2.9 KiB
Markdown
# Quick Matrix Alerting Setup
|
|
|
|
## Step 1: Get Matrix Account
|
|
1. Go to https://app.element.io or install Element app
|
|
2. Create account or login with existing Matrix account
|
|
|
|
## Step 2: Get Access Token
|
|
|
|
### Method 1: Element Web (Recommended)
|
|
1. Open Element in browser: https://app.element.io
|
|
2. Login to your account
|
|
3. Click Settings (gear icon) → Help & About → Advanced
|
|
4. Copy your "Access Token" (starts with `syt_...` or similar)
|
|
|
|
### Method 2: Command Line
|
|
```bash
|
|
curl -X POST https://matrix.org/_matrix/client/v3/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"type": "m.login.password",
|
|
"user": "your_username",
|
|
"password": "your_password"
|
|
}'
|
|
```
|
|
|
|
## Step 3: Create Alert Room
|
|
1. In Element, click "+" to create new room
|
|
2. Name: "Water Level Alerts"
|
|
3. Set to Private
|
|
4. Copy the room ID from room settings (format: `!roomid:matrix.org`)
|
|
|
|
## Step 4: Configure .env File
|
|
Add these to your `.env` file:
|
|
```bash
|
|
# Matrix Alerting Configuration
|
|
MATRIX_HOMESERVER=https://matrix.org
|
|
MATRIX_ACCESS_TOKEN=syt_your_access_token_here
|
|
MATRIX_ROOM_ID=!your_room_id:matrix.org
|
|
|
|
# Grafana Integration (optional)
|
|
GRAFANA_URL=http://localhost:3000
|
|
```
|
|
|
|
## Step 5: Restart and check
|
|
The Matrix messages are sent by `ping-collector` (the Rust service, with
|
|
`FORECAST_IN_COLLECTOR=true`), together with the ntfy notifications:
|
|
|
|
```bash
|
|
sudo systemctl restart ping-collector
|
|
journalctl -u ping-collector | grep -i matrix # "Matrix notifications: room ... on ..."
|
|
# what would be sent right now (ntfy and Matrix), changing nothing:
|
|
sudo -u water-monitor /opt/thailand-water-monitor/bin/ping-collector notify --dry-run
|
|
```
|
|
|
|
## What the room receives
|
|
The same transitions as the ntfy topics (docs/NOTIFICATIONS.md), each once:
|
|
a station crossing its warning or danger level and back (0.10 m hysteresis),
|
|
the P.1 early-warning outlook turning on and off, and the gauge feed going
|
|
stale or recovering. ntfy's per-topic summaries ("Ping River: warning level
|
|
reached") are not repeated in the room. For example:
|
|
|
|
```
|
|
⚠️ **Warning level at P.1**
|
|
Nawarat Bridge, Chiang Mai city: 3.75 m at 18 Oct 14:00, above the warning level of 3.70 m.
|
|
|
|
📈 Dashboard: https://water.buildfor.life/
|
|
```
|
|
|
|
The room has its own delivery state (`matrix:` keys in `notification_state`),
|
|
so a Matrix outage is retried on Matrix only and does not re-send ntfy.
|
|
|
|
The old `run.py --alert-check` cron job (every 15 minutes, repeating an alert
|
|
for as long as a level stayed high) is replaced by this;
|
|
`scripts/install_collector.sh` comments it out of the crontab once
|
|
ping-collector sends Matrix, keeping a backup next to the app.
|
|
|
|
## Troubleshooting
|
|
- **HTTP 401/403** in `journalctl -u ping-collector`: the access token is invalid
|
|
or the account is not in the room.
|
|
- **Room not found**: the room ID needs the `!` prefix and the `:homeserver`
|
|
suffix.
|
|
- **Nothing sent**: there was no transition; `ping-collector notify --dry-run`
|
|
shows the readings judged and what would be sent.
|