Kula collects system metrics every second by reading directly from /proc and /sys, stores them in a built-in tiered ring-buffer storage engine, and serves them through a real-time Web UI dashboard and a terminal TUI.
| Metric | What's Collected |
|---|---|
| CPU | Total usage (user, system, iowait, irq, softirq, steal) + core count |
| Load | 1 / 5 / 15 min averages, running & total tasks |
| Memory | Total, free, available, used, buffers, cached, shmem |
| Swap | Total, free, used |
| Network | Per-interface throughput (Mbps), packets/s, errors, drops; TCP errors/s, resets/s, established connections; socket counts |
| Disks | Per-device I/O (read/write bytes/s, reads/s, writes/s IOPS); filesystem usage |
| System | Uptime, entropy, clock sync, hostname, logged-in user count |
| Processes | Running, sleeping, blocked, zombie counts |
| Self | Kula's own CPU%, RSS memory, open file descriptors |
┌──────────────────────────────────────────────┐
│ Linux Kernel │
│ /proc/stat /proc/meminfo /sys/... │
└──────────────────┬───────────────────────────┘
│ read every 1s
▼
┌──────────────────┐
│ Collectors │
│ (cpu, mem, net, │
│ disk, system) │
└────────┬─────────┘
│ Sample struct
┌────────────┼────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────┐ ┌──────────┐
│ Storage │ │ Web │ │ TUI │
│ Engine │ │ Server │ │ Terminal │
└─────┬──────┘ └───┬────┘ └──────────┘
│ │
┌──────────┼─────────┐ └───────────┐ HTTP + WebSocket
▼ ▼ ▼ ▼
┌─────────┬─────────┬─────────┐ ┌───────────────┐
│ Tier 1 │ Tier 2 │ Tier 3 │ │ Dashboard │
│ 1s │ 1m │ 5m │ │ (Browser) │
│ 250 MB │ 150 MB │ 50 MB │ └───────────────┘
└─────────┴─────────┴─────────┘
Ring-buffer binary files
with circular overwrites
Data is persisted in pre-allocated ring-buffer files per tier. Each tier file has a fixed maximum size — when it fills up, new data overwrites the oldest entries. This gives predictable, bounded disk usage with no cleanup needed.
- Tier 1 — Raw 1-second samples (default 250 MB)
- Tier 2 — 1-minute aggregates: averaged CPU & network, last-value gauges (default 150 MB)
- Tier 3 — 5-minute aggregates, same logic (default 50 MB)
The HTTP server exposes a REST API (/api/current, /api/history, /api/config) and a WebSocket endpoint (/ws) for live streaming. Authentication is optional — when enabled, it uses Argon2id hashing with salt and session cookies or Bearer tokens.
The frontend is a single-page application embedded in the binary. Built on Chart.js with custom SVG gauges, it connects via WebSocket for live updates and falls back to history API for longer time ranges. Features include:
- Interactive zoom with drag-select (auto-pauses live stream)
- Focus mode to show only selected graphs
- Grid / stacked list layout toggle
- Alert system for clock sync & entropy issues
- Gap detection for missing data points
Example installation methods for amd64 (x86_64) GNU/Linux.
Check Releases for ARM and RISC-V packages.
wget https://github.com/c0m4r/kula/releases/download/0.7.1/kula-0.7.1-amd64.tar.gz
echo "6baff6bee9f9bbf56adc6e264e7ff9e1dfa763e7bab76a21dbc1e7d4be0397f4 kula-0.7.1-amd64.tar.gz" | sha256sum -c || rm kula-0.7.1-amd64.tar.gz
tar -xvf kula-0.7.1-amd64.tar.gz
cd kula
./kulawget https://github.com/c0m4r/kula/releases/download/0.7.1/kula_0.7.1_amd64.deb
echo "bbcd6ee65441c85f5bc835c40a1afaabc78b78d976c25e535c051b29ad514185 kula_0.7.1_amd64.deb" | sha256sum -c || rm kula_0.7.1_amd64.deb
sudo dpkg -i kula_0.7.1_amd64.deb
systemctl status kulagit clone https://github.com/c0m4r/kula.git
cd kula
bash addons/build.shKula uses Argon2id for password hashing. If you enable authentication, it is highly recommended to tune the Argon2 parameters (time, memory, threads) in config.yaml based on your hardware capabilities to increase resistance against cracking.
Important: Your config.yaml file contains the plaintext password_salt and the generated password_hash. Ensure the configuration file is protected from unauthorized access on the server:
chmod 0600 /path/to/kula/config.yaml# 1. Copy and edit config
cp config.example.yaml config.yaml
# 2. Start the server
./kula serve
# Dashboard at http://localhost:8080
# 3. Or use the terminal UI
./kula tui# Generate password hash
./kula hash-password
# Add the output to config.yaml under web.authInit system files are provided in addons/init/:
# systemd
sudo cp addons/init/systemd/kula.service /etc/systemd/system/
sudo systemctl enable --now kula
# OpenRC
sudo cp addons/init/openrc/kula /etc/init.d/
sudo rc-update add kula default
# runit
sudo cp -r addons/init/runit/kula /etc/sv/
sudo ln -s /etc/sv/kula /var/service/server {
listen 80 ;
listen [::]:80 ;
server_name kula.localhost;
location / {
proxy_pass http://localhost:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}All settings live in config.yaml. See config.example.yaml for defaults.
# Lint + test suite
bash ./addons/check.sh
# Build dev (Binary size: ~11MB)
CGO_ENABLED=0 go build -o kula ./cmd/kula/
# Build prod (Binary size: ~8MB)
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -buildvcs=false -o kula ./cmd/kula/To safely update only the Go modules used by Kula to their latest minor/patch versions, and prune any unused dependencies:
go get -u ./...
go mod tidy# Run unit tests with race detector
go test -race ./...
# Run the full storage benchmark suite (default: 3s per bench)
bash addons/benchmark.sh
# Shorter run for quick iteration
bash addons/benchmark.sh 500ms
# Python scripts formatter and linters
black addons/*.py
pylint addons/*.py
mypy --strict addons/*.pyBenchmarks cover the full storage engine: codec encode/decode, ring-buffer write throughput, concurrent writes, QueryRange at various sizes (small/large/wrapped), the QueryLatest cache vs cold-disk paths, multi-tier aggregation, and the inline downsampler.
bash addons/build.sh cross # builds amd64, arm64, riscv64bash addons/build_deb.sh
sudo dpkg -i dist/kula_*.debbash addons/build_aur.sh
cd dist/aur && makepkg -sibash addons/docker/build.sh
docker compose -f addons/docker/docker-compose.yml up -dkula/
├── cmd/
│ ├── kula/
│ │ └── main.go # CLI entry point, flag parsing, commands
│ └── gen-mock-data/
│ └── main.go # Mock data generator utility
├── internal/
│ ├── collector/ # Metric collectors (/proc, /sys readers)
│ │ ├── collector.go # Orchestrator — gathers all metrics
│ │ ├── types.go # Sample struct (CPU, mem, net, disk...)
│ │ ├── cpu.go # /proc/stat parser
│ │ ├── memory.go # /proc/meminfo parser
│ │ ├── network.go # /proc/net/* parser
│ │ ├── disk.go # /proc/diskstats + /proc/mounts
│ │ └── system.go # Uptime, entropy, hostname
│ ├── config/ # YAML config loader with defaults
│ ├── sandbox/ # Linux Landlock sandboxing
│ ├── storage/ # Tiered ring-buffer engine
│ │ ├── store.go # Multi-tier coordinator + aggregation
│ │ ├── tier.go # Single ring-buffer file
│ │ └── codec.go # JSON encode/decode for samples
│ ├── tui/ # Terminal UI (bubbletea + lipgloss)
│ └── web/ # HTTP/WebSocket server
│ ├── server.go # Routes, API handlers, startup
│ ├── websocket.go # Live streaming hub + client mgmt
│ ├── auth.go # Argon2id auth, sessions, middleware
│ └── static/ # Embedded SPA (served from binary)
│ ├── index.html # Dashboard markup
│ ├── app.js # Charts, WebSocket, UI logic
│ └── style.css # Dark theme, glassmorphism
├── addons/
│ ├── inspect_tier.py # Standalone Python script for reading tiers
│ ├── benchmark.sh # Storage engine benchmark suite (formatted output)
│ ├── build.sh # Cross-compile (amd64/arm64/riscv64)
│ ├── build_deb.sh # Debian package builder
│ ├── build_aur.sh # Arch AUR PKGBUILD generator
│ ├── check.sh # Linting + testing
│ ├── kula.1 # Man page
│ ├── release.sh # CI packaging wrapper
│ ├── bash-completion/ # Bash completion script
│ ├── docker/ # Dockerfile + compose
│ └── init/ # Service files (systemd/openrc/runit)
├── config.example.yaml
├── VERSION # Single source of truth for version
├── CHANGELOG
└── LICENSE # AGPL-3.0
GNU Affero General Public License v3.0
- Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
- Chart.js library licensed under MIT