Monitoring & health

A collector you can't see is a collector you can't trust. This page covers how to know your fleet is healthy and get told when it isn't — the difference between running a deployment and hoping.

Where you do this: Two surfaces.

• In the dashboard (kilasec.com/app/) — Collectors (fleet state), Health (on-demand self-checks), Logs → Collector (diagnostics timeline), Dashboard tab (first-run checklist, pending approvals), Settings → Notifications (alert channels). Requires the tenant_admin role.
• From your external uptime monitor — probe https://kilasec.com/api/healthz. Configured wherever your uptime tool lives (Better Uptime, Pingdom, cron+curl), not in the Kilasec dashboard.

Where to look

Dashboard → Collectors shows each collector's live state — online/offline, time since last heartbeat, version, and IP — refreshing every 10 seconds. Until traffic is flowing, Dashboard → Dashboard shows a first-run checklist so you can tell "not set up yet" from "broken".

Health checks

In the dashboard → Health (under Operate in the sidebar). One card per active collector: online/offline, the build it runs, any recent warning badges (policy sync failing, passed uninspected, degraded, dropped events, …), and a Run checks button.

Run checks asks the collector to run its on-box self-checks and report back. It picks the request up on its next status poll, so results land within about 30 seconds — no SSH needed:

Check	Fails when	Code
Proxy port	the :8080 proxy (PAC / explicit-proxy clients) isn't accepting connections	AFW-111
Device port (Kilasec Connect)	the device TLS hop isn't accepting connections. When it passes, it lists every port devices are told to use (:443 and :8443)	AFW-111
Device port :443	devices can only reach this collector on :8443, with the reason (see Firewall & ports)	AFW-113
PAC-TLS port	the :9443 PAC server isn't accepting connections	AFW-111
Port conflict	another process on the host already held one of the collector's ports at boot, so that listener wasn't started	AFW-112
TLS-inspection CA	the CA is missing, unreadable, expired, or expires within 30 days	AFW-120
Cloud reachable	the collector can't reach the cloud (latency is shown when it can)	AFW-510
Cloud auth (collector token)	the cloud rejects the collector's token, or the plan has lapsed	AFW-511 / AFW-410
Clock skew vs cloud	the host clock is more than two minutes off	AFW-512
Enforcing (not degraded)	the collector has fallen back to pass-through	AFW-220
File-descriptor limit	the open-files hard limit is below 8192 (the data plane raises its own soft limit to the hard one)	AFW-140
Disk space	under 1 GB free on the data volume	AFW-141

Every failed row carries an AFW-### chip — hover it for the cause and the fix, or look it up in Error codes. An offline collector runs a requested check when it reconnects; until then you see its last results. The same panel is in each collector's detail view on Collectors (Health check section).

Logs → Collector is the passive side: the collector's diagnostics timeline (sync failures, fail-open/fail-closed episodes, shedding, dropped events, update reverts), each row tagged with its code.

On the collector host, docker exec kilasec-collector kilasec test connectivity runs the same checks.

Liveness: how "online" is decided

Every collector heartbeats to the cloud roughly every 10 seconds (its uplink cycle). A collector counts as online if its last heartbeat was within 60 seconds. Two timestamps are tracked:

• last seen — updated on every heartbeat; "is it alive?"
• last event — updated only when real traffic flows through it; "is it actually inspecting anything?"

A collector can be online but idle (alive, no AI traffic yet) or online and busy. The board surfaces both so you can tell a quiet network from a broken one.

Offline alerting

Dashboard → Settings → Notifications. When a collector that was heartbeating goes dark for more than 5 minutes, Kilasec fires an alert (once per offline episode; it re-arms after the collector comes back). Configure the channel here — a Slack-compatible webhook and/or email — and use Send test to confirm it reaches you.

The health endpoint

From your external uptime monitor. GET https://kilasec.com/api/healthz is a real probe suitable for external uptime tools:

{ "ok": true, "service": "agentfw-cloud", "db": "ok", "collectors": 3, "collectors_online": 2 }

It probes the database and returns HTTP 503 when degraded (e.g. the DB is unreachable), so a monitor actually trips instead of getting a hardcoded ok. Point your uptime checker (Better Uptime, Pingdom, a simple cron + curl) at that URL and alert on non-200.

A monitoring baseline for a beta

1. Dashboard → Settings → Notifications: configure an alert channel (webhook or email) so offline events reach you.
2. External uptime tool: add a check on https://kilasec.com/api/healthz.
3. Dashboard → Health: glance on your normal cadence — any warning badge or red check names its fix.
4. Dashboard → Dashboard: watch the approval backlog — a growing pending approval count means requests are being held and nobody's resolving them.

When a collector shows offline

See Collector is offline for the triage steps — reachability, the container, the uplink, and the host. For a collector that is online but misbehaving, start with Run checks on the Health page.