Skip to content
KanshiKanshi Docs

Architecture

Kanshi keeps collection, storage, and presentation separate. Host Agents and application SDKs use different telemetry paths, while Core owns authentication, persistence, retention, and queries.

Kanshi Agents send host metrics to Core over gRPC. Applications send traces and logs through an OpenTelemetry Collector. Core stores telemetry in TimescaleDB and serves the Dashboard over REST.

Agent

Section titled “Agent”

The agent runs on every monitored host. On a configurable interval (5s by default) it samples CPU, memory, disk, and network activity using gopsutil, appends the points to an in-memory buffer, and flushes the batch to core over gRPC when the batch fills up or a flush timer fires, whichever comes first. If the connection drops, the agent reconnects automatically and keeps collecting in the meantime.

Optional process telemetry records process name, PID, CPU, and resident memory. It is disabled by default and must be enabled on each Agent that should report it.

Batching keeps network overhead low. The synchronous sender retries an in-flight batch after reconnecting; collection resumes after delivery.

Core

Section titled “Core”

Core is the only stateful service. It exposes two interfaces:

  • gRPC (:50051): agents call ReportAgent to register/heartbeat and IngestBatch to deliver metric batches.
  • REST (:8080): the dashboard (or your own tooling) reads agents and metric ranges. Every response uses the same envelope:
{ "code": 200, "message": "ok", "data": { } }

Metrics are persisted in TimescaleDB with a 30-day retention policy. Aggregate queries use time_bucket with supported intervals of 30s, 1m, 5m, and 15m. Host range queries support up to seven days of history.

Database access is code-generated with sqlc, so queries are plain SQL checked at build time.

Dashboard

Section titled “Dashboard”

The dashboard is a static React SPA built with Vite and served by Nginx. Nginx proxies /api/v1 to core. The dashboard sends its shared read key as a bearer token, polls every five seconds, and renders fleet and per-agent CPU, memory, disk, network, and process views. Service and trace resources can link to an Agent when their advisory host.id or host.name identity matches. These attributes improve navigation but do not grant access. The Admin menu stores a Light or Dark theme choice in the browser, with Dark as the default.

The health endpoint is public. Versioned REST routes require KANSHI_DASHBOARD_KEY, and gRPC ingest requires the separate KANSHI_API_KEY.