The garbage collector

Go collects garbage concurrently, in short pauses, and the collector's work is a function of how much garbage a program produces. Two knobs shape it: GOGC says how much the heap may grow before a collection, and GOMEMLIMIT says how much memory the process may use. A service sets the second and usually leaves the first alone.

SetGCPercent

debug.SetGCPercent sets the target and returns the previous value, which is why the program prints the default of a hundred, then fifty, then fifty again. A hundred means a collection when the live heap doubles; fifty means it grows by half, so the collector runs more often and the heap stays smaller.

package main import ( "fmt" "runtime/debug" ) func main() { old := debug.SetGCPercent(50) fmt.Println("previous percent:", old) now := debug.SetGCPercent(50) fmt.Println("current percent:", now) restored := debug.SetGCPercent(old) fmt.Println("restored:", restored) }

go build -o app main.go && ./app

previous percent: 100
current percent: 50
restored: 50

The second call returned fifty because the first had already set it. A negative value turns the collector off, which is a tool for a short batch job and a way to end a long-running one with an out-of-memory kill. The environment variable GOGC=50 does the same at start-up and is the form a deployment uses.

SetMemoryLimit

The memory limit is a soft cap in bytes for the whole process. Its default is the maximum int64, which means no limit; the program sets sixty-four megabytes and reads the previous and current values back. When the live heap approaches the limit, the collector runs more often to stay under it, even if that costs CPU.

package main import ( "fmt" "runtime/debug" ) func main() { old := debug.SetMemoryLimit(64 << 20) fmt.Println("previous limit:", old) now := debug.SetMemoryLimit(64 << 20) fmt.Println("current limit:", now) debug.SetMemoryLimit(old) fmt.Println("restored a finite limit:", old > 0) }

go build -o app main.go && ./app

previous limit: 9223372036854775807
current limit: 67108864
restored a finite limit: true

The previous value is the maximum int64, and sixty-four megabytes is 67108864 bytes. A container sets GOMEMLIMIT a little below its memory limit, so the collector works harder before the kernel kills the process. The limit is soft: a program that needs more than it will still exceed it, and the collector cannot help.

ReadMemStats

runtime.ReadMemStats copies the counters, which stops the world for a moment, so a program calls it from a metrics loop and not from a request. The program below reads them, allocates four megabytes, forces a collection and reads again; the counters show a collection ran and the total allocation grew.

package main import ( "fmt" "runtime" ) func main() { var before, after runtime.MemStats runtime.ReadMemStats(&before) data := make([][]byte, 1000) for i := range data { data[i] = make([]byte, 4096) } runtime.GC() runtime.ReadMemStats(&after) fmt.Println("gc cycles ran:", after.NumGC > before.NumGC) fmt.Println("heap in use:", after.Alloc > 0) fmt.Println("allocated bytes > 2MB:", after.TotalAlloc-before.TotalAlloc > 2<<20) fmt.Println("kept one slice:", len(data) == 1000) }

go build -o app main.go && ./app

gc cycles ran: true
heap in use: true
allocated bytes > 2MB: true
kept one slice: true

The NumGC counter went up because the program called runtime.GC, which is a forced collection. Alloc is the live heap and TotalAlloc every byte ever allocated; the difference is the garbage the collector reclaimed. PauseNs holds the recent pauses, and a service exports the counters that matter to its dashboard.

gctrace

GODEBUG=gctrace=1 prints one line per collection, which is the cheapest way to see whether a program collects too often. The program below allocates two thousand slices of four kilobytes, and the run printed two collections before the final print. The sizes and timings vary between runs and machines.

package main import "fmt" func main() { data := make([][]byte, 2000) for i := range data { data[i] = make([]byte, 4096) } fmt.Println("allocated slices:", len(data)) }

go build -o app main.go && GODEBUG=gctrace=1 ./app

gc 1 @0.000s 5%: 0.025+0.31+0.033 ms clock, 0.10+0.053/0.13/0.22+0.13 ms cpu, 3->4->0 MB, 4 MB goal, 0 MB stacks, 0 MB globals, 4 P
gc 2 @0.004s 3%: 0.018+0.22+0.026 ms clock, 0.075+0.094/0.10/0.13+0.10 ms cpu, 3->3->0 MB, 4 MB goal, 0 MB stacks, 0 MB globals, 4 P
allocated slices: 2000

Each line names the cycle, the time since start, the CPU share spent collecting, the pause phases in milliseconds, and the heap before, after and live. A fifth field says the goal the next cycle aims at, and the last says how many Ps were running. A line every few milliseconds is a program that allocates too much; a line every few seconds is a program at rest.

A budget, not a tune

The modern advice is to set a memory budget and leave the collector to it: GOMEMLIMIT at the container limit, GOGC at its default, and a dashboard for the heap and the pause. A program that allocates less is the real improvement; a lower GOGC trades CPU for memory and a higher one the other way, and neither fixes a leak. The next lesson exports the runtime's own metrics and records a trace.

Exercises

  1. Set the GC percent to 10 and read the value back. What does a lower target do to the collections, and what does it cost?
  2. Replace 64 << 20 with debug.SetMemoryLimit(-1) and read the returned value. What does minus one mean to the function?
  3. Run the gctrace program with GOGC=off and with the default. How many lines does each print, and what does that say about the cost of collecting?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does GOGC=100 mean?

    Answer

    Collect when the live heap doubles

    The target is a percentage of growth.

  2. What does debug.SetGCPercent return?

    Answer

    The previous setting

    The program reads it to restore the old value.

  3. What is the default memory limit?

    Answer

    The maximum int64, meaning no limit

    It prints as 9223372036854775807.

  4. What does GOMEMLIMIT do near the limit?

    Answer

    Makes the collector run more often to stay under it

    It is a soft limit that costs CPU.

  5. Why is ReadMemStats not for a request path?

    Answer

    It stops the world for a moment

    A metrics loop is the place for it.

  6. What is the difference between Alloc and TotalAlloc?

    Answer

    Alloc is the live heap, TotalAlloc every byte ever allocated

    The difference is the reclaimed garbage.

  7. What does GODEBUG=gctrace=1 print?

    Answer

    One line per collection with sizes and pauses

    It is the cheapest collector view.

  8. What does a trace line every few milliseconds suggest?

    Answer

    The program allocates too much

    Frequent collections cost CPU.

  9. What replaces hand tuning in a container?

    Answer

    A GOMEMLIMIT budget near the container limit

    The collector balances the rest.

  10. What actually reduces GC work?

    Answer

    Allocating less

    The other knobs trade one cost for another.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev