Introduction

Website: varta.sh · Guides: comparisons & Prometheus setup

Varta is a zero-dependency, zero-allocation health protocol for distributed local agents and networked clusters. Agents emit a fixed 32-byte heartbeat over a Unix domain socket (or UDP, with AEAD); an observer (varta-watch) decodes the beats, detects stalls, fires recovery commands, and exposes Prometheus metrics — all from a single poll loop on a single thread, with no heap allocation on the steady-state path.

Should I use Varta?

Varta is not a tracing system, an APM, a load balancer, or a config-distribution tool. It carries one fact per beat: this PID is alive, and here’s how it feels about that.

The “Zero-Everything” philosophy

• Zero registry dependencies. Production crates (varta-client, varta-watch) have empty [dependencies] sections. The single exception is varta-vlp’s optional crypto feature.
• Zero heap allocation on the beat path after Varta::connect(). Every encode/decode operates on stack buffers. Enforced by a guard-allocator test in CI.
• Non-blocking I/O. The agent socket is non-blocking at connect time. WouldBlock is treated as Dropped, never as an error that stalls the caller.
• Zero unsafe in varta-vlp and varta-client; auditable, line-by- line opt-in unsafe in varta-watch for platform syscalls.

How it works

flowchart LR
    A1[agent 1]  -.beat 32B.-> S[(UDS /run/varta/varta.sock)]
    A2[agent 2]  -.beat 32B.-> S
    AN[agent N]  -.beat 32B.-> S
    S --> O{varta-watch<br/>poll loop}
    O -- per-pid state --> T[Tracker<br/>≤ 4096 pids]
    O -- stall detected --> R[Recovery<br/>exec, non-blocking spawn]
    O -- /metrics --> P[Prometheus]
    O -- TSV --> AL[Audit log]

1. Agents call Varta::connect() once, then beat(status, payload) on whatever cadence they like (typically every 100 ms – 1 s).
2. The observer polls the socket on a 100 ms read-timeout cadence, decodes frames on the stack, updates per-pid state, fires recovery commands for pids past their silence threshold, and serves /metrics. All on one thread.
3. Recovery is opt-in and gated. Only kernel-attested beats are eligible; UDP / socket-mode-only beats are refused with a labelled counter.

Where to next