К содержимому
Войти

Go Road Map

📦 Go в контейнере: GOMAXPROCS и память

Почти все сервисы на Go работают в контейнерах, а рантайм по умолчанию ведёт себя так, будто ему досталась вся машина. Два параметра решают, как сервис уживётся с лимитами: GOMAXPROCS задаёт, сколько горутин выполняются одновременно, GOMEMLIMIT говорит сборщику, где потолок памяти. Ошибка в первом даёт троттлинг и скачки задержек, во втором — OOM-killer посреди дня. С Go 1.25 первую половину рантайм решает сам, вторую по-прежнему настраиваешь ты, и на собеседовании проверяют, знаешь ли ты эту разницу

🧠 Как это устроено

Что видит процесс в контейнере

Контейнер — это обычный процесс Linux, которому ядро ограничило ресурсы через cgroup. Ядер и памяти на машине столько же, сколько было, просто процессу разрешено потратить меньше. В cgroup v2 лимиты лежат в файлах:

  • /sys/fs/cgroup/cpu.max — квота и период CPU в микросекундах. 200000 100000 значит «200 мс процессорного времени за каждые 100 мс», то есть 2 CPU. max 100000 — лимита нет
  • /sys/fs/cgroup/memory.max — лимит памяти в байтах или max

runtime.NumCPU() эти файлы не читает. Он считает логические ядра из маски CPU affinity, поэтому в контейнере с лимитом 2 CPU на 4-ядерной машине вернёт 4. Только --cpuset-cpus, который ограничивает affinity, уменьшает NumCPU

Лимит CPU — квота времени, а не ядра

Когда в Kubernetes пишут limits.cpu: 2, контейнер не получает два ядра. Он получает право на 200 мс CPU в каждом 100-миллисекундном периоде, и тратить их можно на любом числе потоков. Восемь потоков съедят квоту за 25 мс, и дальше ядро заморозит весь процесс до конца периода. Это и есть троттлинг: 75 мс сервис не отвечает вообще, даже на health check

GOMAXPROCS — ограничение другого рода. Это число P в планировщике, то есть сколько горутин могут выполнять Go-код одновременно (как P связаны с потоками и горутинами, разобрано на странице про планировщик). Если GOMAXPROCS больше лимита, программа в пиках запускает больше потоков, чем оплачено, и упирается в квоту. Особенно это заметно на всплесках нагрузки и во время сборки мусора, когда фоновые воркеры GC занимают свободные P

GOMAXPROCS до и после Go 1.25

С Go 1.5 по 1.24 GOMAXPROCS по умолчанию равнялся числу логических ядер машины. Сервис с лимитом 2 CPU на узле в 64 ядра получал 64 P. Поэтому много лет в каждый сервис добавляли go.uber.org/automaxprocs, который при старте читал квоту и вызывал runtime.GOMAXPROCS

С Go 1.25, вышедшего в августе 2025, рантайм делает это сам. По документации runtime.GOMAXPROCS значение по умолчанию — минимум из трёх чисел: логических ядер, ядер в маске affinity и квоты cgroup, то есть квота / период из cpu.max. Дальше детали, о которых любят спрашивать:

automaxprocsРантайм Go 1.25+
Дробный лимит 2,5 CPUвниз, до 2вверх, до 3
Минимум12, если ядер или affinity не меньше 2
Лимит поменяли на ходуне видит, только при стартепроверяет не чаще раза в секунду и обновляет
Задан GOMAXPROCS в envне трогаетне трогает и не обновляет

CPU request не учитывается: из него рантайм ничего не берёт, только из лимита. Авторы в блоге Go объясняют это так: request — гарантированный минимум, и если ограничить им параллелизм, сервис не сможет брать простаивающие ядра узла

Новое поведение включается версией языка в go.mod, а не версией компилятора. Если в go.mod стоит go 1.24 или ниже, даже Go 1.27 соберёт бинарник со старым правилом: в таблице GODEBUG для таких модулей стоят containermaxprocs=0 и updatemaxprocs=0. Этими же настройками новое поведение можно выключить и в свежем модуле

Память: что делает OOM-killer

С памятью квоты нет. Пока процесс в пределах memory.max, всё хорошо. Если он выходит за лимит, ядро убивает его сразу, без предупреждения и без шанса записать лог. В Docker это код выхода 137 и OOMKilled=true, в Kubernetes — статус OOMKilled и рестарт пода

Сборщик мусора Go про memory.max не знает: в исходниках рантайма 1.27.3 нет кода, который читал бы этот файл. Он запускает цикл, когда куча дорастает до цели, а при GOGC=100 цель примерно вдвое больше живых данных. Сервис с 150 МБ живой кучи спокойно растёт до 300 МБ между сборками, и если лимит контейнера 256 МБ, его убьют, хотя половина этой памяти — мусор, который сборщик мог бы собрать. GOMEMLIMIT закрывает эту дыру: у потолка сборщик запускается чаще и держит кучу ниже. Как он устроен и почему не уводит программу в бесконечную сборку, разобрано на странице про сборщик мусора

🛠️ На практике

Все прогоны ниже — Go 1.27.3, бинарник собран под linux/arm64 и запущен в Docker с cgroup v2 на виртуальной машине с 4 ядрами

Какой GOMAXPROCS выберет рантайм

Программа печатает runtime.NumCPU(), runtime.GOMAXPROCS(0) и содержимое cpu.max. Один и тот же код собран дважды: с go 1.25 и с go 1.24 в go.mod

Запускcpu.maxNumCPUgo 1.25go 1.24
без лимитаmax 100000444
--cpus=0.550000 100000424
--cpus=1.5150000 100000424
--cpus=3300000 100000434
--cpuset-cpus=0max 100000111
--cpus=1.5 -e GOMAXPROCS=4150000 100000444

Видно всё правило сразу. NumCPU квоту не замечает. Лимит 1,5 CPU округлился вверх до 2, а 0,5 CPU тоже дал 2: это нижняя граница. Сервис с лимитом 0,5 CPU будет троттлиться в пиках, и это осознанный компромисс рантайма. Affinity из одного ядра даёт 1, потому что ядер меньше двух. Переменная окружения побеждает всё. А модуль с go 1.24 живёт по старым правилам

Обновление на лету: контейнер запущен с --cpus=3, потом лимит поменяли через docker update на 2,5, на 4 и на 1. Программа раз в полсекунды проверяла GOMAXPROCS:

NumCPU=4 GOMAXPROCS=3 cpu.max="300000 100000"
8.0s: GOMAXPROCS 3 -> 4
11.5s: GOMAXPROCS 4 -> 2

При 2,5 CPU значение осталось 3, округление вверх. Остальные изменения рантайм подхватил примерно за секунду после docker update

Что стоит лишний GOMAXPROCS

Сервис с лимитом 2 CPU получает пачку из 100 тяжёлых запросов по 2,5 мс CPU раз в 300 мс, в среднем это 0,8 CPU. Параллельно раз в 5 мс приходит лёгкий запрос, и программа меряет, насколько он опоздал. Первый запуск с умолчанием Go 1.25, второй с GOMAXPROCS=4, как было бы до 1.25 на этой машине:

Go · Пачки тяжёлых запросов и задержка лёгкого

package main

import (
	"fmt"
	"os"
	"runtime"
	"slices"
	"strings"
	"sync"
	"time"
)

// heavy — тяжёлый запрос, около 2,5 мс CPU
func heavy() uint64 {
	var x uint64 = 1
	for i := 0; i < 6_400_000; i++ {
		x = x*6364136223846793005 + 1442695040888963407
	}
	return x
}

func main() {
	var wg sync.WaitGroup
	var mu sync.Mutex
	var probe []time.Duration
	stop := make(chan struct{})
	// лёгкий запрос раз в 5 мс: сколько он ждёт, пока его обслужат
	go func() {
		next := time.Now()
		for {
			next = next.Add(5 * time.Millisecond)
			select {
			case <-stop:
				return
			case <-time.After(time.Until(next)):
			}
			done := make(chan struct{})
			go func() { close(done) }()
			<-done
			// задержка считается от момента, когда запрос должен был прийти
			mu.Lock()
			probe = append(probe, time.Since(next))
			mu.Unlock()
		}
	}()
	// пачка из 100 тяжёлых запросов раз в 300 мс: в среднем 0,8 CPU при лимите 2
	for b := 0; b < 20; b++ {
		for i := 0; i < 100; i++ {
			wg.Add(1)
			go func() { defer wg.Done(); _ = heavy() }()
		}
		time.Sleep(300 * time.Millisecond)
	}
	wg.Wait()
	close(stop)
	mu.Lock()
	slices.Sort(probe)
	p := probe
	mu.Unlock()
	stat, _ := os.ReadFile("/sys/fs/cgroup/cpu.stat")
	var thr string
	for _, l := range strings.Split(string(stat), "\n") {
		if strings.HasPrefix(l, "nr_throttled") || strings.HasPrefix(l, "throttled_usec") {
			thr += l + " "
		}
	}
	r := func(d time.Duration) time.Duration { return d.Round(100 * time.Microsecond) }
	fmt.Printf("GOMAXPROCS=%d лёгкий запрос: p50=%v p99=%v max=%v %s\n", runtime.GOMAXPROCS(0),
		r(p[len(p)/2]), r(p[len(p)*99/100]), r(p[len(p)-1]), thr)
}
GOMAXPROCSp50p99maxnr_throttled
2 (умолчание)1,1–1,2 мс4,0–4,7 мс7,7–8,3 мс0
41,2–1,3 мс39–46 мс52–58 мс12–21

Три прогона на каждый вариант. Медиана почти одинаковая, а хвост вырос в десять раз. Пачка — это 250 мс CPU, четыре потока сжигают квоту в 200 мс примерно за 50 мс, и ядро замораживает процесс на оставшиеся 50 мс периода. Лёгкий запрос, пришедший в это окно, ждёт его целиком. Два P выполняют Go-код максимум на двух потоках, за период это те же 200 мс, и в прогонах троттлинга не было ни разу. В метриках это видно по счётчику nr_throttled в cpu.stat, а в Prometheus — по container_cpu_cfs_throttled_periods_total из cAdvisor

GOMEMLIMIT против OOM-killer

Программа держит 150 МБ живых данных и создаёт ещё 1,25 ГБ мусора кусками по 64 КБ. Контейнер ограничен 256 МБ без свопа:

Go · 150 МБ живой кучи и поток мусора

package main

import (
	"fmt"
	"runtime"
	"runtime/debug"
	"time"
)

var live [][]byte // ~150 МБ данных, которые нужны всё время

func main() {
	for i := 0; i < 150; i++ {
		b := make([]byte, 1<<20)
		fill(b)
		live = append(live, b)
	}
	start := time.Now()
	var sink []byte
	for i := 0; i < 20_000; i++ {
		sink = make([]byte, 64<<10) // мусор: запросы, буферы, JSON
		fill(sink)
	}
	_ = sink
	var ms runtime.MemStats
	runtime.ReadMemStats(&ms)
	fmt.Printf("лимит: %d МБ, циклов GC: %d, Sys: %d МБ, время: %v\n",
		debug.SetMemoryLimit(-1)>>20, ms.NumGC, ms.Sys>>20, time.Since(start).Round(time.Millisecond))
	runtime.KeepAlive(live)
}

// fill пишет в каждую страницу, иначе ОС не выделит под буфер физическую память
func fill(b []byte) {
	for i := 0; i < len(b); i += 4096 {
		b[i] = 1
	}
}
$ docker run --memory=256m --memory-swap=256m ...
exit=137, OOMKilled=true

$ docker run --memory=256m --memory-swap=256m -e GOMEMLIMIT=230MiB ...
лимит: 230 МБ, циклов GC: 27, Sys: 232 МБ, время: 30ms

Без лимита куча росла к цели около 300 МБ, и ядро убило процесс, не дождавшись вывода. С GOMEMLIMIT=230MiB сборщик запускался чаще и удержал процесс в пределах лимита. Оба варианта повторились одинаково в двух прогонах

Как задать GOMEMLIMIT

Самый простой способ — переменная окружения в манифесте, число на 5–10% меньше лимита:

resources:
  limits:
    memory: 1Gi
env:
  - name: GOMEMLIMIT
    value: "920MiB"

Минус в том, что два числа надо менять вместе, и рано или поздно кто-то поменяет одно. Можно прочитать лимит из cgroup при старте и поставить его из кода:

// limitFromCgroup ставит GOMEMLIMIT в 90% от memory.max, если его не задали явно
func limitFromCgroup() {
	if _, ok := os.LookupEnv("GOMEMLIMIT"); ok {
		return
	}
	raw, err := os.ReadFile("/sys/fs/cgroup/memory.max") // cgroup v2
	if err != nil {
		return
	}
	limit, err := strconv.ParseInt(strings.TrimSpace(string(raw)), 10, 64)
	if err != nil {
		return // "max" — лимита нет
	}
	debug.SetMemoryLimit(limit / 10 * 9)
}

В контейнере с --memory=1g эта функция ставит 921 МиБ, с явным GOMEMLIMIT=700MiB оставляет 700, без лимита ничего не меняет. Если не хочется своего кода, то же делает библиотека github.com/KimMachineGun/automemlimit: по умолчанию 90% от лимита cgroup, долю меняет переменная AUTOMEMLIMIT

⚠️ Где ошибаются

Обновили Go, но не go.mod. Компилятор 1.25 и новее, а в go.mod осталось go 1.23. GOMAXPROCS по-прежнему равен числу ядер узла, и команда уверена, что проблема решена. Проверка простая: залогировать runtime.GOMAXPROCS(0) при старте

Оставили automaxprocs после перехода на 1.25. Библиотека вызывает runtime.GOMAXPROCS(n), а любой явный вызов отключает автоматическое обновление. Плюс она округляет вниз: при лимите 2,5 CPU будет 2, а не 3. Импорт стоит удалить. Так же действует GOMAXPROCS, который прописали в переменных окружения «на всякий случай»

Под без лимита CPU. Многие команды сознательно ставят только requests.cpu, чтобы сервис мог брать свободные ядра узла. Тогда квоты нет и GOMAXPROCS равен числу ядер узла, например 64. Троттлинга не будет, но сборщик мусора и фоновые воркеры раскинутся на все 64 P. Это выбор, а не ошибка, просто его надо делать осознанно и смотреть метрики

GOMEMLIMIT ровно по лимиту контейнера. Через downward API (resourceFieldRef: limits.memory) легко подставить лимит в переменную, но получится 100%. В GOMEMLIMIT не входят память cgo, код самого бинарника и буферы сокетов в ядре, а cgroup считает всё это памятью контейнера. Запас 5–10% нужен, иначе OOM-killer всё равно придёт

Размер пула по runtime.NumCPU(). Код вида make(chan job, runtime.NumCPU()) или пул воркеров на NumCPU в контейнере с лимитом 2 CPU на 64-ядерном узле запустит 64 воркера. Для CPU-задач правильная мера — runtime.GOMAXPROCS(0)

🎯 Вопросы с собеседований

Что такое GOMAXPROCS и какое у него значение по умолчанию?

Это число P в планировщике, то есть сколько горутин одновременно выполняют Go-код. Горутин может быть сколько угодно, потоков в системных вызовах тоже бывает больше. До Go 1.25 по умолчанию оно равнялось числу логических ядер. С 1.25 на Linux это минимум из числа ядер, маски affinity и лимита CPU в cgroup, причём дробный лимит округляется вверх, а меньше 2 значение не опускается, если ядер хотя бы два

Почему раньше в каждый сервис ставили automaxprocs?

Рантайм не знал про лимиты контейнера и в поде с лимитом 2 CPU на большом узле запускал столько P, сколько ядер у узла. Потоков становилось больше оплаченного, квота заканчивалась в начале периода, и ядро замораживало процесс до конца периода. Это давало хвостовые задержки в десятки миллисекунд. automaxprocs при старте читал квоту из cgroup и ставил GOMAXPROCS по ней. С Go 1.25 рантайм делает это сам и ещё следит за изменениями лимита

Что такое CPU throttling и как его увидеть?

Лимит CPU в Linux — это квота времени на период, обычно 200 мс CPU на 100 мс для лимита в 2 CPU. Если процесс потратил квоту раньше конца периода, ядро не даёт ему работать до начала следующего. Снаружи это выглядит как пауза сервиса до нескольких десятков миллисекунд, хотя средняя загрузка CPU низкая. Видно в cpu.stat по nr_throttled и throttled_usec, а в Kubernetes по метрике cAdvisor container_cpu_cfs_throttled_periods_total

Учитывает ли Go CPU request в Kubernetes?

Нет, только лимит, который превращается в квоту cpu.max. Request влияет на планирование подов и долю CPU при конкуренции, но не ограничивает процесс сверху. Если бы рантайм взял request, сервис не смог бы использовать свободные ядра узла. Без лимита GOMAXPROCS будет равен числу ядер узла, и при желании его задают вручную

Как GOMAXPROCS реагирует на изменение лимита во время работы?

С Go 1.25 рантайм периодически, не чаще раза в секунду, перечитывает число ядер, affinity и квоту и обновляет значение. Поэтому новое значение подхватится и после in-place resize пода в Kubernetes, без рестарта. Автообновление выключается, если GOMAXPROCS задан через переменную окружения или вызовом runtime.GOMAXPROCS. Вернуть его можно через runtime.SetDefaultGOMAXPROCS()

Почему сервис на Go убивает OOM-killer, хотя живых данных мало?

Сборщик запускается по GOGC, а не по лимиту контейнера: при GOGC=100 куча растёт примерно до двойного объёма живых данных. Сервис со 150 МБ живой кучи доходит до 300 МБ, и при лимите 256 МБ ядро его убивает. Про лимит памяти контейнера рантайм сам не узнаёт. Решение — GOMEMLIMIT на 5–10% ниже лимита, тогда сборщик у потолка начнёт работать чаще

Если поставить GOMEMLIMIT, OOM больше не будет?

Нет. Лимит мягкий: если живых данных больше лимита, рантайм его превысит, а ядро убьёт процесс как обычно. Кроме того, в GOMEMLIMIT не входят память cgo и буферы сокетов, которые cgroup тоже считает памятью контейнера. Лимит спасает от мусора, который не успели собрать, а от утечки или реального роста данных спасает только профилирование или больше памяти

Как задать GOMEMLIMIT в Kubernetes, чтобы он не разошёлся с лимитом пода?

Самое простое — переменная окружения рядом с resources.limits.memory, но два числа надо менять вместе. Надёжнее читать memory.max из cgroup при старте и вызывать debug.SetMemoryLimit с долей 0,9, своим кодом или библиотекой automemlimit. Через downward API подставляется 100% лимита, без запаса, поэтому его используют только вместе с пересчётом в коде

📚 Что почитать

  • Container-aware GOMAXPROCS — статья команды Go: почему лимит CPU означает квоту, а не ядра, и что поменялось в 1.25
  • runtime.GOMAXPROCS — документация с точным правилом: минимум 2, округление вверх, обновление раз в секунду, GODEBUG-настройки
  • A Guide to the Go Garbage Collector: Memory limit — как работает GOMEMLIMIT и когда он не спасает
  • Control Group v2 — документация ядра: что означают cpu.max, memory.max и счётчики в cpu.stat