README
¶
livck-agent
A lightweight Linux monitoring agent for LIVCK Cloud. It samples system metrics — CPU, memory, load, disk, network, pressure, and optional GPU/SMART/reachability probes — and reports lifecycle events like reboots, OOM kills, clean shutdowns, and disk-full or read-only mounts. The agent collects, buffers, and sends; every decision (what's an incident, who to alert, how long to keep data) is made by the backend, not here.
It is outbound-only. There is no command channel and no inbound port: the config
it pulls describes only what to measure, never what to run. It runs as a
non-root systemd service under a hardened unit, and it needs no privileges beyond
reading /proc, /sys, and mount stats.
Install
The agent is distributed as a .deb/.rpm and enrolled with a short-lived
token from your LIVCK dashboard:
curl -fsSL https://get.livck.cloud/install.sh | sudo sh -s -- --token <ENROLLMENT_TOKEN> --name web-01
The dashboard shows the exact one-liner (with the token written to a 0600
temp file so it never lands in your shell history or /proc/cmdline).
Commands
livck-agent run collect and report (the systemd service runs this)
livck-agent enroll register with the backend and persist the identity
livck-agent doctor check platform support, clock skew, and connectivity
livck-agent version print the build version
Wire contract
The agent talks to the backend over a single frozen wire protocol in
pkg/wire. It's a separate Go module
(github.com/LIVCK/agent/pkg/wire) so the contract is versioned independently of
the agent binary and the backend can import just the protocol. See
pkg/wire/CONTRACT.md for the wire format, the metric
catalog, the error codes, and the response bodies.
Layout
cmd/livck-agent CLI and run-loop wiring
cmd/livck-loadgen fake-fleet load generator (testing)
pkg/wire the frozen protobuf contract + metric catalog
internal/platform injectable Clock / filesystem / host abstractions
internal/config config pull, validation, atomic swap
internal/collector metric sources (cpu, mem, disk, net, gpu, smart, probes…)
internal/buffer bounded report ring + shutdown spool
internal/sender batch build, compression, retry, response handling
internal/event lifecycle event queue
internal/enroll identity + token persistence
internal/lifecycle reboot / shutdown / OOM detection
internal/runner the collect loop and graceful shutdown
internal/doctor the doctor command
Build and test
make build # static, stripped binary (CGO disabled)
make test-race # tests with the race detector
make lint # golangci-lint
make wire # build and test the wire module
pkg/wire is a nested module. A standalone checkout resolves it through the
replace directive in go.mod; inside the LIVCK monorepo a go.work binds it
from source.
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
livck-agent
command
Command livck-agent is the LIVCK server monitoring agent.
|
Command livck-agent is the LIVCK server monitoring agent. |
|
livck-loadgen
command
Command livck-loadgen drives a fake fleet of N simulated agents against a live pulse ingest to find its throughput knee on the dev host.
|
Command livck-loadgen drives a fake fleet of N simulated agents against a live pulse ingest to find its throughput knee on the dev host. |
|
internal
|
|
|
buffer
Package buffer holds the agent's report ring: a RAM buffer bounded by both a byte cap (15 MB) and a time horizon (60 min), with drop-oldest on overflow.
|
Package buffer holds the agent's report ring: a RAM buffer bounded by both a byte cap (15 MB) and a time horizon (60 min), with drop-oldest on overflow. |
|
collector
Package collector defines the metric-source contract and the report assembly the run loop drives.
|
Package collector defines the metric-source contract and the report assembly the run loop drives. |
|
collector/cpu
Package cpu reports aggregate CPU utilisation from /proc/stat.
|
Package cpu reports aggregate CPU utilisation from /proc/stat. |
|
collector/disk
Package disk reports per-mount space and inode usage.
|
Package disk reports per-mount space and inode usage. |
|
collector/diskio
Package diskio reports per-device throughput and IOPS from /proc/diskstats.
|
Package diskio reports per-device throughput and IOPS from /proc/diskstats. |
|
collector/gpu
Package gpu reports per-GPU utilization, memory, temperature and power for AMD and NVIDIA cards.
|
Package gpu reports per-GPU utilization, memory, temperature and power for AMD and NVIDIA cards. |
|
collector/load
Package load reports the 1/5/15-minute load averages from /proc/loadavg.
|
Package load reports the 1/5/15-minute load averages from /proc/loadavg. |
|
collector/mem
Package mem reports memory usage from /proc/meminfo plus the cumulative oom_kill counter from /proc/vmstat.
|
Package mem reports memory usage from /proc/meminfo plus the cumulative oom_kill counter from /proc/vmstat. |
|
collector/net
Package net reports per-interface throughput and error rates from /proc/net/dev.
|
Package net reports per-interface throughput and error rates from /proc/net/dev. |
|
collector/probe
Package probe implements the reachability/latency collector: from INSIDE the customer's network the agent probes a server-declared list of targets (tcp/http/https/dns) and reports per-target latency, loss and reachability.
|
Package probe implements the reachability/latency collector: from INSIDE the customer's network the agent probes a server-declared list of targets (tcp/http/https/dns) and reports per-target latency, loss and reachability. |
|
collector/psi
Package psi reports Pressure Stall Information from /proc/pressure/{cpu,io, memory}.
|
Package psi reports Pressure Stall Information from /proc/pressure/{cpu,io, memory}. |
|
collector/registry
Package registry wires the concrete system collectors into a collector Registry.
|
Package registry wires the concrete system collectors into a collector Registry. |
|
collector/self
Package self reports the agent's own resource use for overhead transparency (sys.agent.rss_bytes, sys.agent.cpu_pct).
|
Package self reports the agent's own resource use for overhead transparency (sys.agent.rss_bytes, sys.agent.cpu_pct). |
|
collector/smart
Package smart reports SMART health for the host's storage devices.
|
Package smart reports SMART health for the host's storage devices. |
|
collector/swap
Package swap reports swap usage from /proc/meminfo.
|
Package swap reports swap usage from /proc/meminfo. |
|
collector/system
Package system reports host uptime and a process/zombie count.
|
Package system reports host uptime and a process/zombie count. |
|
config
Package config owns the agent's runtime configuration: pulling it from the control plane, validating it defensively, and swapping it atomically so a hot-reload is never half-applied.
|
Package config owns the agent's runtime configuration: pulling it from the control plane, validating it defensively, and swapping it atomically so a hot-reload is never half-applied. |
|
doctor
Package doctor implements the livck-agent `doctor` verb: a read-only, side-effect-free self-diagnosis an operator runs to answer "why isn't this server reporting?".
|
Package doctor implements the livck-agent `doctor` verb: a read-only, side-effect-free self-diagnosis an operator runs to answer "why isn't this server reporting?". |
|
enroll
This file holds the client side of the enroll handshake: the single, client-initiated POST that registers a fresh server with the LIVCK brain and yields the managed token, ingest URL and initial config the agent then reports with.
|
This file holds the client side of the enroll handshake: the single, client-initiated POST that registers a fresh server with the LIVCK brain and yields the managed token, ingest URL and initial config the agent then reports with. |
|
event
Package event holds the agent's lifecycle event queue and the Emitter interface that other foundation packages (config, buffer) push into.
|
Package event holds the agent's lifecycle event queue and the Emitter interface that other foundation packages (config, buffer) push into. |
|
hostinfo
Package hostinfo builds the two host-fact maps the agent attaches to batches: the report/enroll meta profile (os, distro, kernel, arch, cpu, ram, boot time, virtualization) and the fingerprint used for clone detection (a hashed machine-id, the boot_id and the hostname).
|
Package hostinfo builds the two host-fact maps the agent attaches to batches: the report/enroll meta profile (os, distro, kernel, arch, cpu, ram, boot time, virtualization) and the fingerprint used for clone detection (a hashed machine-id, the boot_id and the hostname). |
|
lifecycle
Package lifecycle detects the discrete host lifecycle events the agent emits as the strong-delivery signal class: boot, unexpected_reboot, clean_shutdown, oom_kill and fs_readonly.
|
Package lifecycle detects the discrete host lifecycle events the agent emits as the strong-delivery signal class: boot, unexpected_reboot, clean_shutdown, oom_kill and fs_readonly. |
|
live
Package live implements the agent side of Live-Watch: a WSS signal channel to pulse that bursts an instantaneous metric snapshot every few seconds while a browser viewer is watching.
|
Package live implements the agent side of Live-Watch: a WSS signal channel to pulse that bursts an instantaneous metric snapshot every few seconds while a browser viewer is watching. |
|
loadgen
Package loadgen holds the reusable, testable pieces of the livck-loadgen fake-fleet driver: the catalog-driven synthetic report generator and the sender-side latency/status recorder.
|
Package loadgen holds the reusable, testable pieces of the livck-loadgen fake-fleet driver: the catalog-driven synthetic report generator and the sender-side latency/status recorder. |
|
platform
Package platform holds the injectable Clock, FS and Host abstractions the agent is built on.
|
Package platform holds the injectable Clock, FS and Host abstractions the agent is built on. |
|
platform/platformtest
Package platformtest provides deterministic fakes for the platform abstractions so buffer, sender, config and identity can be tested without a real clock or filesystem.
|
Package platformtest provides deterministic fakes for the platform abstractions so buffer, sender, config and identity can be tested without a real clock or filesystem. |
|
runner
This file is the agent-local aggregation layer, which spans two aggregation levels: the runner sub-samples the cheap collectors every sample_interval and folds each Sample into an aggregator; at the end of the report interval the aggregator collapses every key's sub-samples into one report value using the catalog's agg mode for that key.
|
This file is the agent-local aggregation layer, which spans two aggregation levels: the runner sub-samples the cheap collectors every sample_interval and folds each Sample into an aggregator; at the end of the report interval the aggregator collapses every key's sub-samples into one report value using the catalog's agg mode for that key. |
|
sender
Package sender turns buffered reports and pending events into ingest requests and drives the retry matrix.
|
Package sender turns buffered reports and pending events into ingest requests and drives the retry matrix. |
|
update
Package update implements the root-side upgrade path of the agent (SERVER-AGENT.md §10.8): the `livck-agent upgrade` verb and the hourly livck-agent-update.timer both land here.
|
Package update implements the root-side upgrade path of the agent (SERVER-AGENT.md §10.8): the `livck-agent upgrade` verb and the hourly livck-agent-update.timer both land here. |
|
pkg
|
|
|
wire
module
|
Click to show internal directories.
Click to hide internal directories.