v1.0.0

gcscope v1.0.0

gcscope is a terminal UI for exploring Go garbage collector behavior in real time.

It helps you see what the garbage collector is doing while a Go program is running: when GC cycles happen, how memory changes over time, where stop-the-world pauses appear, and how behavior differs between runs.

What gcscope shows

• GC cycles as they happen
• Stop-the-world pause statistics
• Heap live / heap goal dynamics
• GC frequency over a recent observation window
• Per-cycle GC details
• Selected pacing-related signals when available
• Snapshots for saving an observation window
• Snapshot diffs for comparing two runs

Main modes

• run: start a compiled Go binary and observe its GC behavior through runtime GC output
• lab: try built-in demo workloads (alloc, churn, idle, spike)
• attach: connect to a running service that exposes runtime metrics
• diff: compare two saved snapshots side by side

Why use it

gcscope is useful when you want a quick visual answer to questions like:

• What is the garbage collector doing while my program runs?
• How often does GC happen?
• How does memory usage change over time?
• Are there pauses worth paying attention to?
• Did a code change or runtime setting change GC behavior?
• Can I quickly demonstrate GC behavior without setting up dashboards?

Install

Go (recommended):

go install github.com/timur-developer/gcscope/cmd/gcscope@latest

Prebuilt binaries:

• Download the archive for your OS/arch from Assets
• Extract and run:
  • Windows: .\gcscope.exe ...
  • macOS/Linux: ./gcscope ...
• Optionally move it into a directory in your PATH

Quickstart

Run a built-in workload:

gcscope lab churn

Observe your own compiled Go binary:

gcscope run ./your-binary

Attach to a running service:

gcscope attach http://127.0.0.1:8080/gcscope/metrics

Docs

See README for usage, controls, configuration, snapshots, and examples.