Skip to main content

Integrating a project with KamuStatus

KamuStatus is the platform's monitoring service. One integration gives you four signals in the kamuhub dashboard (app.kamuhub.com → Monitor):

  1. Uptime — HTTP/TCP/DNS/ping monitors probed from multiple regions.
  2. Heartbeats — for services with no public ingress (workers, 6PN-only apps).
  3. Backend errors — server-side exceptions, grouped and deduplicated.
  4. Client errors — browser errors, pageviews and sessions via a 1.7 KB SDK.

Everything hangs off a property: one site/service origin, which carries a public write-only ingest key (ksts_..., DSN model — it can only submit events, never read anything, so it is not a secret and belongs in fly.toml [env], not in a secret store).

Concepts​

project (org-scoped, keyed on kamuid_org_id)
 ├─ properties   one per site/service origin; owns the ksts_ ingest key
 │   ├─ error groups / events / stats   (telemetry lands here)
 │   └─ error alert rules               (error_rate, new_group, group_regression)
 ├─ monitors     uptime checks; can be linked to a property
 └─ channels     notification targets shared by all alert rules

The ingest endpoint is https://kamustatus-ingest.fly.dev (canonical name ingest.kamustatus.com once DNS is live). The wire contract is versioned in the kamustatus repo at packages/telemetry/PROTOCOL.md: POST {ingest}/i/{key}, Content-Type: text/plain (a CORS simple request), JSON envelope {"v":1,"sdk","release","sid","dropped","events":[...]}. Browsers must send an Origin matching the property's origin; server-side reporters send no Origin header, which ingest accepts by design.

Guides​

  • Error telemetry — create a property, add the browser SDK, vendor the backend reporter, configure the ingest env vars.
  • Uptime monitoring — monitor types (HTTP with body assertions and certificate/domain expiry, TCP, DNS, ping) and health endpoints.
  • Heartbeats — ping URLs for jobs and workers without public ingress, metrics in the ping body.
  • Alerts — uptime alert rules and error alert rules.
  • Notification channels — the 14 channel types, their fields and the webhook payload.
  • Status pages — public status pages, custom domains and the uptime badge.
  • Incidents and maintenance — incident timelines and maintenance windows on status pages.
  • Import from UptimeRobot — move monitors, channels and history over.

The platform-wide kamu CLI covers projects, properties, monitors, uptime alert rules and status pages with a kamuhub access key. Channels, incidents, maintenance, imports, error alert rules and metric rules are in the dashboard, or in the API: the same routes the dashboard uses, at https://app.kamuhub.com/api/status/... with Authorization: Bearer <access key> (capability status.read for reads, status.manage for writes).

Integration checklist​

  1. Property created; ksts_ key in hand.
  2. Browser: script tag with data-key (+ data-release) on every page.
  3. Backend: reporter file copied; installGlobalErrorReporting() + framework onError hook (+ job:failed in workers).
  4. KAMUSTATUS_INGEST_URL + KAMUSTATUS_INGEST_KEY (+ VERSION) in fly.toml [env].
  5. Monitor on /health, or heartbeat for ingress-less services.
  6. Alert rules once the project has a notification channel.
  7. Verify: trigger a test error, see it under Monitor → project → Errors within seconds.