Runtime Introspection

Three levels of looking inside

Go ships rich, built-in introspection — no agent, no external profiler required to start:

• runtime quick reads — MemStats, NumGoroutine, Version, GOMAXPROCS. Cheap to sprinkle in for a glance.
• runtime/metrics — the modern, stable, self-describing metrics interface (Go 1.16+). What you wire into Prometheus/dashboards.
• GODEBUG + tracing — zero-code production telemetry (gctrace, schedtrace) and the deep pprof / execution-tracer tooling for offline analysis.

MemStats: the quick gauge

runtime.ReadMemStats fills a struct with heap and GC counters. It’s the fastest way to answer “how much am I allocating and how often does the GC run?” — but it’s a stop-the-world snapshot, so don’t poll it in a hot loop.

package main

import (
"fmt"
"runtime"
)

func dump(label string) {
var m runtime.MemStats
runtime.ReadMemStats(&m)
fmt.Printf("%-6s HeapAlloc=%4dKB  TotalAlloc=%5dKB  Mallocs=%d  NumGC=%d\n",
	label, m.HeapAlloc/1024, m.TotalAlloc/1024, m.Mallocs, m.NumGC)
}

func main() {
fmt.Println("Go version:", runtime.Version())
fmt.Println("GOMAXPROCS:", runtime.GOMAXPROCS(0))
dump("start")

// Allocate ~8 MB of short-lived garbage.
var sink [][]byte
for i := 0; i < 128; i++ {
	sink = append(sink, make([]byte, 64*1024))
}
dump("alloc")

sink = nil
runtime.GC()
dump("gc")
_ = sink
}

HeapAlloc is live memory right now; TotalAlloc and Mallocs only ever climb (cumulative); NumGC counts completed cycles. After dropping the slice and forcing a GC, HeapAlloc falls back while the cumulative counters stay high.

runtime/metrics: the modern instrument cluster

runtime/metrics replaces ad-hoc MemStats reads for anything you’ll monitor over time. Metrics are named (e.g. /gc/heap/allocs:bytes), carry documented units, and the set can grow across Go versions without breaking your code. You read only what you ask for:

package main

import (
"fmt"
"runtime/metrics"
)

func main() {
// Ask for a few specific, stable metrics by name.
samples := []metrics.Sample{
	{Name: "/gc/heap/allocs:bytes"},        // cumulative bytes allocated
	{Name: "/gc/cycles/total:gc-cycles"},   // completed GC cycles
	{Name: "/sched/goroutines:goroutines"}, // live goroutines
	{Name: "/memory/classes/heap/objects:bytes"},
}

// Allocate a little so the numbers are non-zero.
var keep [][]byte
for i := 0; i < 1000; i++ {
	keep = append(keep, make([]byte, 1024))
}

metrics.Read(samples)
for _, s := range samples {
	switch s.Value.Kind() {
	case metrics.KindUint64:
		fmt.Printf("%-44s = %d\n", s.Name, s.Value.Uint64())
	case metrics.KindFloat64:
		fmt.Printf("%-44s = %f\n", s.Name, s.Value.Float64())
	default:
		fmt.Printf("%-44s = (other)\n", s.Name)
	}
}
_ = keep
}

Call metrics.All() to discover every available metric with its description and unit — a self-documenting catalog that grows with the runtime.

GODEBUG: telemetry with zero code

GODEBUG is an environment variable the runtime reads at startup. It turns on built-in tracing without recompiling — invaluable in production:

# One line per GC: pause times, heap before->after->goal, GC CPU%.
GODEBUG=gctrace=1 ./app

# Scheduler state every 1000ms: run queues, idle Ps/Ms, spinning threads.
GODEBUG=schedtrace=1000 ./app

# Combine; comma-separated. Allocation/free tracing (very verbose):
GODEBUG=gctrace=1,schedtrace=2000 ./app

For deep, offline analysis there are two tools, both fed by the runtime package:

graph LR
A["runtime/pprof<br/>net/http/pprof"] --> P["go tool pprof<br/>(where: CPU, heap, blocking)"]
B["runtime/trace"] --> T["go tool trace<br/>(when: scheduler/GC timeline)"]

• pprof answers where — aggregated CPU, heap, goroutine, mutex, and block profiles. See profiling with pprof.
• the execution tracer (runtime/trace → go tool trace) answers when — a timeline of goroutine scheduling, GC phases, syscalls, and blocking events, the right tool for latency and concurrency mysteries.

Reference

See also

• the garbage collector — what gctrace and the GC metrics describe.
• scheduler internals — what schedtrace and the execution tracer reveal.
• profiling with pprof (stdlib) — the where tool, in depth.
• the memory allocator — the allocation counters’ source.

Next: from source to a running binary — compile & link.

Related topics