README
¶
measure
measure correlates Go runtime memory, operating-system process memory, cgroup accounting, and application phases so engineers can optimize locally and observe the same behavior through Prometheus and Grafana.
What it does
- records Go heap, runtime-system, allocation, and garbage-collection counters;
- reads process RSS and Linux cgroup usage, peaks, limits, and attribution;
- associates periodic samples with named phases and progress;
- writes versioned JSONL/CSV traces and terminal run receipts;
- compares runs and enforces memory budgets in local development or CI;
- exposes a coherent Prometheus metric set for production dashboards.
The library exposes explicit availability states instead of treating unsupported or unreadable values as zero. JSONL is the lossless canonical trace; CSV is a documented flat projection. Linux external runs also report process_tree_rss_sum_bytes, an approximate root-plus-descendant RSS sum that can double-count shared pages.
Install
Homebrew
brew tap go-go-golems/go-go-go
brew install measure
Go install
go install github.com/go-go-golems/measure/cmd/measure@latest
Quick start
# One observation of measure itself or another process.
measure snapshot --format table
measure snapshot --pid 1234 --format json
# Stream observations until cancelled, until COUNT rows, or until PID exits.
measure watch --pid 1234 --interval 250ms --format jsonl
# Preserve child exit status and write a canonical trace plus receipt.
measure run --interval 100ms \
--trace run.jsonl --receipt run.receipt.json \
-- go test ./pkg/search -run TestLargeVault
# A derived CSV timeline is available when nested trace details are unnecessary.
measure run --trace run.csv --trace-format csv --receipt run.receipt.json \
-- ./my-workload
measure summarize run.jsonl --format table
measure compare before.jsonl after.jsonl --format table
measure assert run.jsonl --peak-rss '<600MiB' --peak-cgroup '<700MiB'
measure assert run.jsonl --phase-budget 'bleve_index:peak-rss:<450MiB'
assert exits 0 when all budgets pass, 1 when a budget fails, 2 for invalid input or an unreadable trace, and 3 when a required source was unavailable. run returns the child's exit code; signal exits use the shell convention 128 + signal.
Prometheus and Grafana
pkg/prometheus is an optional event sink and collector for caller-owned registries. It provides explicit runtime/process/process-tree/cgroup/run/phase metric groups so applications can disable series that overlap Go collectors, process exporters, or cAdvisor. Labels are limited to fixed application/environment/run-kind values and finite constructor-registered phases; run IDs, PIDs, paths, revisions, errors, and arbitrary attributes are never labels.
See:
examples/prometheus/for embedding, a loopback demo, scrape configuration, duplicate controls, and metric semantics;examples/grafana/measure-overview.jsonfor the validated nine-panel dashboard;examples/grafana/provisioning/for datasource and dashboard provisioning.
Development
make lint
make test
make build
make build-bin
The repository uses one top-level Go module, pinned lint tooling, logcopter generation checks, lefthook, GitHub Actions, and GoReleaser.
Security
Memory counters are content-free, but command arguments, arbitrary annotations, traces, and heap profiles can reveal sensitive data. Review artifacts before sharing them and keep profiling endpoints private.
License
MIT. See LICENSE.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
measure
command
|
|
|
pkg
|
|
|
budget
Package budget parses and evaluates deterministic memory limits against trace summaries.
|
Package budget parses and evaluates deterministic memory limits against trace summaries. |
|
collector
Package collector reads domain-free Go runtime, operating-system process, and cgroup memory observations.
|
Package collector reads domain-free Go runtime, operating-system process, and cgroup memory observations. |
|
measure
Package measure records process-memory observations and correlates them with application phases and progress.
|
Package measure records process-memory observations and correlates them with application phases and progress. |
|
measurement
Package measurement defines domain-free resource observations produced by measure collectors and consumed by recorders, traces, and exporters.
|
Package measurement defines domain-free resource observations produced by measure collectors and consumed by recorders, traces, and exporters. |
|
process
Package process runs and measures external process trees for the measure CLI.
|
Package process runs and measures external process trees for the measure CLI. |
|
prometheus
Package prometheus projects measure events into a bounded-cardinality Prometheus collector without using the global default registry.
|
Package prometheus projects measure events into a bounded-cardinality Prometheus collector without using the global default registry. |
|
report
Package report derives stable summaries and comparisons from trace events.
|
Package report derives stable summaries and comparisons from trace events. |
|
sink
Package sink delivers versioned measure trace events to durable or in-memory consumers.
|
Package sink delivers versioned measure trace events to durable or in-memory consumers. |
|
trace
Package trace defines the versioned, content-free event and receipt schema emitted by measure recorders.
|
Package trace defines the versioned, content-free event and receipt schema emitted by measure recorders. |