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
- 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?
- Replace 64 << 20 with debug.SetMemoryLimit(-1) and read the returned value. What does minus one mean to the function?
- 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.
-
What does GOGC=100 mean?
Answer
Collect when the live heap doubles
The target is a percentage of growth.
-
What does debug.SetGCPercent return?
Answer
The previous setting
The program reads it to restore the old value.
-
What is the default memory limit?
Answer
The maximum int64, meaning no limit
It prints as 9223372036854775807.
-
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.
-
Why is ReadMemStats not for a request path?
Answer
It stops the world for a moment
A metrics loop is the place for it.
-
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.
-
What does GODEBUG=gctrace=1 print?
Answer
One line per collection with sizes and pauses
It is the cheapest collector view.
-
What does a trace line every few milliseconds suggest?
Answer
The program allocates too much
Frequent collections cost CPU.
-
What replaces hand tuning in a container?
Answer
A GOMEMLIMIT budget near the container limit
The collector balances the rest.
-
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