# Connector health monitoring

# 1. Statuses (SPEC §12)

internal (`connector_health.status`)	operator label	meaning
`healthy`	UP	≥ 85 % page success in 24 h, no anomalies
`degraded`	DEGRADED	50–85 % success, or anomalies (schema drift, result-count collapse, duplicate explosion, price shift, challenges)
`failing`	BROKEN	< 50 % success or the last 3 runs failed
`paused` / `disabled`	DISABLED	paused by an operator, disabled in the registry, or gated (missing `requires` env vars)
`maintenance`	MAINTENANCE	operator flag; scheduler skips it, health keeps computing
`unknown`	UNKNOWN	never ran

Health is computed every 30 min (health.compute job) by healthFromRuns() over the last 7 days of connector_runs, plus a data-freshness query. pnpm ri health [--probe] forces a recompute (with a live probe).

# 2. Metrics per connector (`ConnectorHealth`)

success_rate_24h · pages_attempted/success · requests_24h · items (records_24h, duplicates_24h) · latest successful ingest (last_success) · last_error · HTTP error distribution (http_errors {code: n}) · parse_failure_rate · schema_drift[] · latency_ms_avg · rate_limited_24h (429s) · captcha/challenge events (challenges_24h) · circuit_refusals_24h · data_freshness (newest source-side date ingested) · records_7d_daily_avg (volume baseline) · Firecrawl success rate / Scrapfly fallback rate · missing_requirements. Queue backlog comes from pg-boss (/admin overview). Costs per connector from costs.

# 3. Schema-drift detection (SPEC §13)

Detectors, all producing anomaly strings that mark the run and degrade health:

signal	where	anomaly
expected selectors/fields missing	connector `parse()` → router quality < 0.6 → escalation; connector `ctx.anomaly('selector_missing'	'parse_failure_page')`
field-null increase	normalizer: `connector_field_stats` daily presence of price/currency/date/images/title/identifiers/grade/number/set/year/description vs trailing 7 days; +30 pts null rate on ≥ 50 records	`schema_drift:<field>`
price parsing failure / currency problem	normalizer `priceDistributionAnomaly` (median shift ×3 vs last 500 sales), Zod schema failures	`price_distribution_shift`, `parse_failure: schema …`
pagination failure	connector `ctx.anomaly('pagination_failure')`, `all_pages_failed`	`pagination_failure`, `all_pages_failed`
result-count collapse	health: `records_24h < 20 %` of the 7-day daily average (≥ 50/day)	`result_count_collapse`
layout change / JSON schema change	Zod payload schemas throw in `normalize()` → recorded on the raw row (`process_error`) and counted as parse failures	`parse_failure`
duplicate explosion	crawler: ≥ 90 % duplicates on ≥ 50 records	`duplicate_explosion`
anti-bot	router `isChallengePage()`	`challenge_events: n`

The connector page shows the field-presence monitor (today vs 7 days) so a drift is visible before the connector silently produces garbage.

# 4. Alerts

connector_run_finished events carry status and anomalies; the account/alert worker and the MacLustr monitoring apps read /api/admin/connectors (health labels) — a BROKEN or DEGRADED-with-drift connector is an alert condition. Circuit-breaker openings are logged at warn with the retry time.

# 5. Admin explorer (SPEC §29) — `/admin/connectors`

Columns: logo · domain · category · country · health label · status · acquisition method (+ engines, refresh class) · last sync / last ok / data freshness · items 24 h (normalised, duplicates, pages/min) · errors (HTTP errors, anomalies, challenges) · Firecrawl/Scrapfly credits 24 h and rates · latency / 429 · priority · trust · backfill progress. Filters: text, health, category, country.

Buttons: Test (25-record probe) · Run now · Backfill (start/continue a resumable campaign) · Pause / Resume; on the connector page also Retry from cursor, Pause backfill, Reset backfill, Maintenance, View logs (runs, anomalies, costs), View payload (/admin/connectors/<id>/raw/<rawId>), View parsed record (/admin/connectors/<id>/record/<recId>), config/schedule editor, access notes and the full registry entry.

JSON: GET /api/admin/connectors (health per connector) · GET /api/admin/coverage (SPEC §30 coverage stats) · GET /api/admin/status (pipeline counts + queues). All require the admin cookie.

# 6. Coverage dashboard (SPEC §30) — `/admin/coverage`

Connectors by health / category / country / source type / engine / capability; live listings indexed; historical sales indexed (and how many older than a year, oldest sale); auction houses covered; grading providers (certificates, population reports); canonical assets and variants; guide observations; daily ingested observations (14-day bars); sales by family with 30-day counts and oldest dates; sales by year (historical depth).