Alerting

Kanshi Core evaluates persisted alert rules on a fixed schedule and records every firing and resolved transition. Rules are created and managed from the dashboard or the REST API, and nothing is enabled by default.

Rules

A rule watches one condition for one target:

Field	Values
Metric	cpu.used_percent, mem.used_percent, disk.used_percent, agent.offline
Comparator	gt (greater than) or lt (less than)
Threshold	a percentage, or seconds offline for agent.offline
Target	one agent, or all agents when left global

agent.offline fires when an agent has not reported for longer than the threshold in seconds.

Evaluation and state

Every KANSHI_ALERT_INTERVAL (default 30s) Core checks each enabled rule against the latest metric for each target. A crossed threshold records one firing transition; recovery records one resolved transition. A sustained breach does not duplicate events. State lives in the database, so active alerts and history survive a Core restart.

Webhooks

Set KANSHI_WEBHOOK_URLS to a comma-separated list of endpoints. Core delivers a versioned JSON payload for each transition:

{
  "version": 1,
  "event": "firing",
  "ruleId": 1,
  "ruleName": "High CPU",
  "metric": "cpu.used_percent",
  "agentId": "web-01",
  "value": 95,
  "threshold": 90,
  "timestamp": "2026-07-25T19:23:33Z"
}

Successful deliveries are not retried; failures retry within a bounded policy. Set KANSHI_WEBHOOK_SECRET to sign each request with an X-Kanshi-Signature: sha256=<hmac> header you can verify.

Managing rules

Use the dashboard Alerts page to create, edit, enable, disable, and delete rules, and to watch active alerts and recent history with webhook delivery status. The same operations are available on the REST API under /api/v1/alerts.