Notes

Tune Go GC with GOGC and GOMEMLIMIT

Use GOGC to trade heap growth for collection frequency and GOMEMLIMIT to constrain Go-managed memory. Set container headroom explicitly: Go 1.27.3 does not derive this limit from cgroups.

Start with the default GOGC=100, set a memory budget with headroom for the rest of the process, then measure throughput, latency and live memory under representative load. GOGC controls growth between collections; GOMEMLIMIT supplies a soft runtime memory limit. Neither repairs an application retaining too much live data.

Choose the control

Setting Meaning
GOGC=100 Roughly one additional live-heap-sized allocation budget, including roots in the goal calculation
GOGC=25 Less growth, usually more frequent collection
GOGC=200 More growth, usually fewer collections if the memory limit permits
GOGC=off Disable the growth-triggered collector; the memory limit can still cause collection
GOMEMLIMIT=64MiB Soft budget for Go-managed memory, not a 64 MiB RSS cap

The GC guide explains the growth/CPU tradeoff. For a live heap H and roots R, the growth-based goal is approximately H + (H + R) × GOGC/100. Runtime minimums and pacing affect small heaps.

The memory limit accounts approximately for MemStats.Sys - MemStats.HeapReleased. It includes runtime stacks and metadata, while excluding memory outside the Go runtime’s control, such as many C allocations and external mappings. The SetMemoryLimit contract defines the accounting and units. debug.SetMemoryLimit changes the same runtime setting programmatically.

Produce a trace you can read

Save as gc.go:

package main
import ("fmt"; "runtime"; "runtime/debug")
var sink [][]byte
func main() {
    fmt.Println("memory limit:", debug.SetMemoryLimit(-1))
    for i := 0; i < 256; i++ {
        b := make([]byte, 1<<20)
        b[0] = byte(i)
        sink = append(sink, b)
        if len(sink) > 16 {
            sink[0] = nil
            sink = sink[1:]
        }
    }
    runtime.KeepAlive(sink)
}
go build -o gc gc.go
GOGC=100 GOMEMLIMIT=64MiB GODEBUG=gctrace=1 ./gc
GOGC=25 GOMEMLIMIT=64MiB GODEBUG=gctrace=1 ./gc
GOGC=200 GOMEMLIMIT=64MiB GODEBUG=gctrace=1 ./gc

The program keeps the most recent 16 buffers and allocates 256 MiB in total. Clear the discarded slot before reslicing: reslicing alone leaves its pointer in the backing array, keeping the old buffer reachable. Build first so compiler GC traces do not get mixed into the application measurement. Example output from Go 1.27.3:

gc 1 @0.000s 10%: 0.12+0.53+0.023 ms clock, 1.5+0/1.1/0.12+0.28 ms cpu, 4->4->4 MB, 4 MB goal, 0 MB stacks, 0 MB globals, 12 P

Read the fields from left to right: collection number, seconds since process start, cumulative fraction of available CPU time used for GC, then the clock times for sweep termination, concurrent marking, and mark termination. The three CPU groups describe the corresponding CPU work; the middle group splits assist, background and idle marking. The three heap sizes mean heap at start, heap at end and live heap. The goal is the target heap size, followed by stack/global scan sizes and the number of processors. The runtime documentation specifies this version-sensitive trace format. Concurrent mark time is not a stop-the-world pause.

Leave container headroom

As of Go 1.27.3, GOMEMLIMIT is not automatically set from cgroups. With the variable unset, this program prints memory limit: 9223372036854775807. The versioned runtime’s readGOMEMLIMIT implementation returns MaxInt64 for an unset value. Container-aware CPU scheduling does not establish a memory budget.

Choose a budget below the container’s hard limit, allowing for non-Go allocations and operational headroom. There is no universal percentage. If the live set nearly fills the budget, repeated collections reclaim little and allocation assists consume useful CPU: the GC thrashing or “death spiral” scenario. Go limits GC CPU pressure and can exceed the soft limit to keep making progress; a cgroup can still kill the process. Reduce retention, increase the budget, or lower concurrency rather than pushing the limit below irreducible live memory.

Go deeper

Use the GC controls dive to relate the measurements to pacing, allocation and memory returned to the operating system.