The runtime Package

runtime is the machinery underneath every Go program: the scheduler, the garbage collector, the stack. Most of it you never call, and a few functions are worth knowing.

Examples

Four facts about the binary and the host, available without importing anything else.

fmt.Println(runtime.GOOS, runtime.GOARCH)
fmt.Println("cpus:", runtime.NumCPU())
fmt.Println(runtime.Version())

Output

linux amd64
cpus: 8
go1.26.1

The count includes the goroutine doing the asking. Watching it over time is the cheapest leak detector there is.

fmt.Println("before:", runtime.NumGoroutine())

var wg sync.WaitGroup
for i := 0; i < 3; i++ {
    wg.Add(1)
    go func() { defer wg.Done() }()
}
wg.Wait()

fmt.Println("after:", runtime.NumGoroutine())

Output

before: 1
after: 1

ReadMemStats fills a struct you own. Alloc is what is live now; TotalAlloc only ever climbs.

var m runtime.MemStats
runtime.ReadMemStats(&m)

fmt.Printf("live %d KB, total %d KB, %d collections\n",
    m.Alloc/1024, m.TotalAlloc/1024, m.NumGC)

Output

live 168 KB, total 168 KB, 0 collections

One frame up is your caller, which is what a logger wants to report.

func logLine(msg string) {
    _, file, line, ok := runtime.Caller(1)
    if !ok {
        file, line = "?", 0
    }
    fmt.Printf("%s:%d %s\n", filepath.Base(file), line, msg)
}

logLine("started")

Output

main.go:18 started

Function	Description
GOOS `runtime.GOOS == "linux"`	The operating system the binary was built for: linux, darwin, windows.
Behavior A constant fixed at build time, not a look at the running machine. Cross-compiling changes it.
GOARCH `runtime.GOARCH // "amd64"`	The architecture the binary was built for: amd64, arm64.
NumCPU() int `runtime.NumCPU() // 8`	How many hardware threads the machine reports.
Behavior Read once at start-up. It does not notice a container's CPU limit, which is why a pod with a one-core quota can still report the host's count.
Version() string `runtime.Version() // "go1.26.1"`	The Go version the binary was built with.
NumGoroutine() int	How many goroutines exist right now.
Output An `int`, including the one asking. Use when Watching for a leak. A count that climbs and never falls is the signature of goroutines that never return. A goroutine that blocks forever is never collected, so a count that only climbs is a leak. Sampling it on a ticker costs nothing and catches the class of bug that otherwise shows up as a server growing quietly for a week. `go func() { for range time.Tick(30 * time.Second) { log.Println("goroutines:", runtime.NumGoroutine()) } }()`
Gosched() `runtime.Gosched()`	Hands the processor to another goroutine and comes back.
Behavior Almost never needed. The scheduler preempts on its own, and reaching for this usually means a channel or a lock belongs there instead.
GOMAXPROCS(n int) int `runtime.GOMAXPROCS(0) // read without setting`	Sets how many goroutines may run at once, and returns the previous value.
Input The new limit. Zero reads the current value without changing it. Output The value it had before the call. Behavior Defaults to `NumCPU`. Setting it below that is how a containerised service stops the scheduler assuming it owns the host. Equivalent to the GOMAXPROCS environment variable
ReadMemStats(m *MemStats) `runtime.ReadMemStats(&m)`	Fills a MemStats with the current heap and GC numbers.
Input A pointer to a `MemStats` you own. It is filled in place. Behavior Stops the world for the duration. Fine on a metrics interval, wrong in a request handler.
MemStats	The heap numbers: Alloc is live bytes, TotalAlloc is everything ever allocated, Sys is what was taken from the OS, NumGC counts collections.
GC() `runtime.GC()`	Runs a garbage collection and waits for it.
Use when Taking a memory measurement in a test, so the numbers are not noise. Not in production; the collector's own timing is better than yours.
SetFinalizer(obj any, finalizer any) `runtime.SetFinalizer(f, cleanup)`	Runs a function when the object becomes unreachable.
Behavior No guarantee it ever runs, including at exit. Use `defer` and an explicit Close for anything that matters.
Caller(skip int) (pc uintptr, file string, line int, ok bool) `_, file, line, _ := runtime.Caller(1)`	The file and line of the caller, skip frames up.
Input How many frames to climb. Zero is the line calling `Caller`, one is its caller. Output A program counter, file, line, and whether the lookup worked. Use when Writing a logger that reports where it was called from.
FuncForPC(pc uintptr) *Func `runtime.FuncForPC(pc).Name()`	The function containing a program counter, for its name.
Stack(buf []byte, all bool) int `runtime.Stack(buf, true)`	Writes a stack trace into buf, optionally for every goroutine.
Use when Dumping state from a panic handler, or working out what a hung program is waiting on.

Goroutines What NumGoroutine is counting.sync The tools to reach for before Gosched.Concurrency The scheduler this package exposes the edges of.

Most of this is not for you

The scheduler and the collector are tuned for the general case and are usually better at their jobs than a guess made from outside. Gosched, GC and SetFinalizer in particular tend to appear in code that wanted a channel, a benchmark, or a defer.

The parts that earn their place every day are the read-only ones: which platform this is, how many goroutines exist, how much memory is live, and where a call came from.

Previous regexp Next Topic slices

The runtime Package

Examples

Related