Práticas Recomendadas de Runtime e GC

Fluxo de trabalho de ajuste de produção com métricas e testes de carga.

Estas regras destilam a seção Runtime & GC: meça primeiro, ajuste os parâmetros com margem e corrija os retentores antes de buscar micro-otimizações.

Como Usar Esta Lista

• Aplique durante o design do serviço, atualizações menores do Go e pós-mortem de incidentes de memória.
• Codifique os itens da Categoria A em runbooks e modelos de implantação.
• Emparelhe com testes de carga que exportam artefatos gctrace e pprof.
• Altere uma variável (GOGC, GOMEMLIMIT, hotspots de alocação) por experimento.
• Reavalie após o coletor padrão do Go 1.26 Green Tea GC se tornar o seu padrão.

A - Meça antes de ajustar

• Profile alloc_space e inuse_space sob carga real. Conheça os principais alocadores antes de alterar GOGC.
• Exporte /gc/cpu:fraction-of-cpu-time e go_memstats_heap_alloc_bytes. Alerte sobre desvios sustentados, não picos únicos.
• Monitore NumGoroutine e StackInuse com a taxa de requisição. Separe vazamentos de heap do crescimento da pilha de goroutines.
• Capture GODEBUG=gctrace=1 durante testes de carga. Armazene a saída com tags de implantação para comparação.
• Execute go test -bench com benchmem em pacotes intensivos. Capture regressões de alocação em CI.

B - Dimensionamento de contêiner e cgroup

• Defina GOMEMLIMIT para ~85-90% do limite de memória do pod. Deixe margem para pilhas e memória fora do heap.
• Documente limite vs requisição no README. Operadores precisam de ambos para planejamento de capacidade.
• Combine GOMAXPROCS com o limite de CPU quando não for automático. Evite throttling invisível com Ps em excesso.
• Dimensionar limites a partir de picos de RSS de testes de carga, não de laptops de desenvolvimento. Inclua fases de aquecimento e estado estável.
• Planeje FreeOSMemory pós-pico apenas após trabalhos em lote raros. Não é um substituto para correções de vazamentos.

C - Disciplina de parâmetros do GC

• Prefira GOMEMLIMIT em vez de GOGC baixo agressivo no Kubernetes. A escassez de CPU prejudica a latência mais do que os limites flexíveis ajudam.
• Altere GOGC apenas com métricas p99 e gc_cpu antes e depois. Um parâmetro por canary.
• Proíba GOGC=off fora de benchmarks isolados. Documente qualquer exceção com limites de tempo.
• Registre as alterações de debug.SetGCPercent se usadas dinamicamente. Raro, observável, reversível.
• Reavalie após atualizações do Go (especialmente 1.26 Green Tea). Mudanças no coletor padrão alteram perfis de CPU.

D - Higiene de alocação e escape

• Corrija loops make intensivos antes de ajustar o GC. A taxa de alocação impulsiona a CPU de marcação.
• Execute go build -gcflags="-m" em caminhos intensivos comprovados. Verifique se os escapes correspondem às expectativas.
• Use sync.Pool apenas para buffers temporários de curta duração. Nunca agrupe objetos com estado oculto.
• Limite caches com TTL ou LRU. Sem retentores de map de nível de pacote ilimitados.
• Substitua time.After em loops por timers reutilizáveis. Evite vazamentos de heap de timers.

E - Goroutines, pilhas e encerramento

• Limite o fan-out com pools de workers ou semáforos. A contagem de goroutines deve estabilizar sob carga sustentada.
• Propague context.Context e selecione em Done() em loops. Evite vazamentos de goroutines paradas.
• Feche canais do lado do produtor; feche assinaturas na desconexão. Documente a propriedade.
• Use Shutdown(ctx) com timeout limitado ao parar HTTP/gRPC. Esvazie workers antes de sair.
• Prefira Close() explícito em vez de runtime.SetFinalizer para handles. Finalizadores são apenas para diagnóstico.

FAQs

Relacionados

• O Runtime do Go: Scheduler, GC e Memória - fundação conceitual
• GOGC, GOMEMLIMIT & Finalizers - referência de parâmetros
• Vazamentos de Memória em Go: Causas Comuns - cheatsheet de vazamentos
• Ajuste de GC para Serviços Sensíveis à Latência - playbook de latência
• Profiling de CPU e Heap com pprof - como fazer profiling

Versões de Stack: Esta página foi escrita para Go 1.26.x (Green Tea GC padrão, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).