Skip to content
ROOT

pulse Plan

A CLI infrastructure scanner in Go. Concurrently probes N hosts (ICMP/TCP/HTTP), exposes Prometheus metrics, outputs JSON/YAML. Year 1 Phase 5 Go-fluency proof. Used to monitor real basecamp services from Year 2 onward.

pulse is the Group C fluency artifact for Year 1 Phase 5 — the Go counterpart to Phase 4’s rxp. Where rxp is about Python text-processing fluency, pulse is about Go’s concurrency primitives — channels, errgroup, context — which directly implement the backpressure and fault-isolation patterns at the language level.

pulse earns its production role from Year 2 onward: it monitors real basecamp services, and its /metrics endpoint is scraped by basecamp’s Prometheus. Commercial tools (Pingdom, UptimeRobot) are overkill at homelab scale; pulse fills the gap with a small fast Go binary that matches the platform’s operational discipline.

Like the other Year 1 CLIs, pulse is a quiet ship — push, GoReleaser binaries, README, move on. The discipline is the deliverable; production utility is the bonus that prevents it from being an orphaned demo.

What it is

A cobra-based Go CLI:

Terminal window
pulse scan --targets ./hosts.txt --workers 50
# → concurrent ICMP + TCP + HTTP probes; output JSON


pulse serve --port 9100 --targets ./hosts.txt
# → long-running mode; exposes /metrics for Prometheus


pulse check https://api.example.com --timeout 5s
# → one-shot check

Why it exists

  1. Phase deliverable: Year 1 Phase 5 Go-fluency proof
  2. Real tool: ROOT operations want a small fast probe scanner; commercial tools are overkill at homelab scale; pulse fills the gap.
  3. Y2+ integration: Used to monitor real basecamp services (Y2+); its /metrics endpoint is scraped by basecamp’s Prometheus. Earned a production role in observability.

Pattern it teaches

backpressure: bounded worker pool as concrete example.

fault-isolation: per-probe timeout, context cancellation.

The Go-specific concurrency primitives (channels, errgroup, context) implement these patterns directly.

Scope

v1 (Year 1 Phase 5: quiet ship)

[ ] cobra CLI: scan, serve, check
[ ] Probe types: ICMP, TCP, HTTP (status + content match)
[ ] Concurrency: bounded worker pool (--workers flag)
[ ] Outputs: JSON, YAML, Prometheus exposition format
[ ] Timeout per probe (context-driven)
[ ] Retries with exponential backoff
[ ] >80% test coverage; race-detector-clean
[ ] Released as binary via GoReleaser (linux + macos + windows; amd64 + arm64)
[ ] README + examples
[ ] Quiet ship

v2 (deferred)

  • DNS health checks
  • TLS cert expiry warnings
  • TCP connect-time histograms
  • Self-monitoring (alert when pulse itself is unhealthy)

Stack

  • Go 1.23+
  • cobra (CLI), viper (config)
  • prometheus/client_golang (metrics)
  • net/http + custom ICMP / TCP probes
  • testify (assertions)

When built

Year 1 Phase 5, Month 6-7. Ships to github.com/abukix/pulse + binary release.

Dependencies

pulse is standalone in Year 1. The Y2+ integration creates a downstream dependency: basecamp’s Prometheus scrapes pulse’s /metrics, so pulse’s exposition format must remain stable through the program.

Deliverables checklist

[ ] github.com/abukix/pulse public (quiet ship)
[ ] All commands working
[ ] Binary releases on tag (GoReleaser)
[ ] README + usage examples
[ ] CI: tests + race detector on PR
[ ] Used to monitor real basecamp services (Y2+)

Public vs private

Public quiet ship from Year 1 Phase 5. No launch energy.

Cross-references