Monitoring

A monitoring system that fails silently is worse than none. Here is exactly what Watcher tells you, and what it does not.

Health alerts

Watcher pushes ⚠️ operational messages to your admin chat, formatted differently from event alerts so you can filter them.

Sent when	From
A watch errored during a run	Both runtimes
A watch’s model could not produce a valid verdict (transient)	Both runtimes
A watch’s sources all failed to collect	Both runtimes
The scheduled run itself crashed	The CLI
A scheduler tick crashed	The service

Configure with TELEGRAM_ADMIN_CHAT_ID (falls back to your normal chat). Health alerts are best-effort: if sending one fails, it is logged and never masks the original problem.

What produces no alert

• An alert given up on after five delivery attempts. Repeated notify-failed outcomes are the only signal.
• A watch that quietly stops finding anything because a page changed shape. It reports nothing-new forever, which looks exactly like a quiet week.
• The scheduled job being disabled by your CI provider for inactivity.

These are the three ways Watcher can go quiet without telling you. The habits below cover them.

Run history

Every run of every watch is recorded, whatever the outcome:

pnpm watches history framework-releases
curl -s https://<your-host>/watches/framework-releases/runs -H "authorization: Bearer $TOKEN"

Each record carries the outcome, the summary and evidence, the model’s reasoning, per-source errors, collection counts, the models consulted and the corroborating trust tier. This is your primary diagnostic surface — see Run outcomes.

Liveness and configuration

curl -s https://<your-host>/health          # {"status":"ok"}
curl -s https://<your-host>/config/status   # booleans per integration

/health is the endpoint to point an uptime monitor at, if you run the API. /config/status is the fastest way to tell “broken” from “never configured”.

Collection health

GET /collection/stats aggregates recent runs into attempted, collected, extracted and an extraction rate. A falling rate means pages are being fetched but not read — the early warning that a site changed shape, well before you notice missing alerts.

Key health

GET /admin/keys shows each key’s live status (active, cooldown, dead) and today’s metered usage against its configured limit. Check it when runs start failing with quota errors. See Model and quota errors.

A practical routine

Frequency	Check
Whenever a health alert arrives	Read it; it names the watch
Weekly	Skim run history for a watch you care about. Are outcomes what you expect?
Weekly	Confirm the scheduled job actually ran
Monthly	Extraction rate and accuracy stats; key usage against limits
After any config change	Force a run and read the outcome

The single best habit

Keep one watch pointed at something that changes predictably and often — a busy official feed, for example. If that watch stops producing notified runs, your pipeline is broken, and you will find out from a watch you do not care about instead of from one you do.

Logs

The CLI prints one line per watch. The API logs structured records, including a line per scheduler tick when any watch ran. Neither logs a secret; provider errors are reported with status codes rather than key material.