The Problem
Teams often need a quick way to watch a shell‑generated metric (queue depth, DB row count, log tail) without provisioning a full monitoring stack. Setting up Prometheus, Grafana, or custom scripts can be overkill for ad‑hoc checks, especially when the metric is only needed during development or a short‑lived operation.
What This Does
sampler runs user‑defined shell commands at a configurable interval, parses the numeric output, and renders it in a terminal UI. The UI is built from reusable components found under component/ – e.g. component/gauge/gauge.go for dial‑style displays, component/sparkline/sparkline.go for rolling line graphs, and component/runchart/runchart.go for stacked bar charts.
Configuration lives in a single YAML file (example.yml) and is parsed by config/config.go, which validates the schema (config/validator.go). The main execution loop resides in main.go, which creates a data.Sampler (see data/sampler.go), wires the configured components, and starts the console driver (console/console.go). Docker support is provided via the Dockerfile that builds the binary and copies the config at runtime.
How To Use It
Setup
Build locally (requires Go 1.22+) go build -o sampler .
Or use the published binary (v1.1.0)
curl -Lo /usr/local/bin/sampler \ https://github.com/sqshq/sampler/releases/download/v1.1.0/sampler-1.1.0-linux-amd64 chmod +x /usr/local/bin/sampler
A Docker image can be produced with the included Dockerfile: docker build -t sampler .
Configuration
Create a YAML file that follows the schema in config/component.go and config/options.go. The repository ships example.yml as a minimal reference. Typical sections include: components: type: gauge command: "cat /proc/loadavg | awk '{print $1}'" options: min: 0 max: 5 title: "CPU Load"
Place the file anywhere; the CLI flag -c (or --config) points to it, as defined in main.go.
Running
Local execution sampler -c path/to/config.yml
Inside Docker (mount config)
docker run --rm -it -v $(pwd)/config.yml:/root/config.yml sampler -c /root/config.yml
The binary starts a full‑screen terminal UI. Interaction keys are described in README.md (e.g., q to quit, h for help).
Real‑World Use
A DevOps engineer can monitor a remote RabbitMQ queue during a deployment: components: type: barchart command: "ssh user@host rabbitmqctl listqueues name messages | grep myqueue | awk '{print $2}'" options: title: "Queue depth" period: 5s
Running sampler -c rabbitmq.yml shows a live bar chart; a trigger can fire a sound (via data/trigger.go) when the count drops below a threshold, allowing the engineer to proceed without constant manual checks.
Code Health & Issues
Low – Limited test coverage – Only a handful of component utilities (gaugetest.go, sparklinetest.go, parsetest.go) are exercised; core UI rendering and command execution lack unit tests. Low – Platform‑specific code – Files data/intptywindows.go and data/int_pty.go handle PTY differences; on Windows the PTY implementation is experimental and may fail for complex commands. Low – Hard‑coded external dependencies – The README mentions libasound2-dev for sound alerts, but the build does not enforce its presence; missing libraries will cause runtime errors on Linux. Low – No Go vet/lint step – .travis.yml runs go test ./... but does not invoke go vet or static analysis, leaving potential race conditions or misuse of the sync package unchecked. Low – License present – LICENSE.md includes an MIT license, satisfying open‑source compliance. Low – CI status – Travis CI is configured and badge present; however, the repository is a fork with zero stars, suggesting limited community validation.
Overall, the repo compiles cleanly, has a functional CI pipeline, and ships a Dockerfile, indicating a baseline of engineering hygiene.
The Bottom Line
sampler delivers a lightweight, terminal‑based visual monitor for any shell‑exposable metric, with a simple YAML config and out‑of‑the‑box Docker image. It is well‑suited for developers or small teams needing rapid, ad‑hoc visibility without the overhead of a full monitoring stack. The main caveats are modest test coverage and platform‑specific quirks; teams should validate PTY behavior on their target OS before production use.