Regras de Performance: Quando Otimizar

Q: Como evitar trapaças em benchmarks?

Eleve a configuração, use dados realistas, execute -count=5, compare na mesma classe de máquina.

Regras baseadas em medição e orientação contra otimização prematura.

Use quando um PR alega acelerações, quando os SLOs de latência caem, ou quando revisores suspeitam de micro-otimização prematura.

Como Usar Este Cheatsheet

Exija evidências (profile, benchmark, trace) antes de mesclar PRs apenas de otimização.
Use o código claro como padrão, a menos que um caminho quente seja comprovado.
Emparelhe perfis de CPU com perfis de alocação - corrigir alocações muitas vezes supera ajustes de algoritmo.
Re-benchmark após atualizações do Go; o comportamento do compilador e do GC mudam.

Fluxo de Decisão

Passo	Ação	Pare se
1	Reproduza com carga realista	Não é possível reproduzir - corrija a observabilidade primeiro
2	`go test -bench` + `-benchmem`	Ruído domina - estabilize o ambiente
3	Perfil de CPU (`pprof`)	Função quente não está no seu código - corrija dependências/configuração
4	Perfil de Heap/alocações	Alocações são de inicialização única - adie o trabalho
5	Trace (`go tool trace`)	Problema é espera de IO - ajuste timeouts/paralelismo
6	Mudança de código + delta registrado	Regressão na clareza sem ganho de SLO

Quando Otimizar (luz verde)

Sinal	Alavanca provável	Verifique
Perfil de CPU >10% em uma função	Algoritmo, cache, pré-cálculo	Perfil de CPU depois
`alloc_space` alto em loop	Pré-aloque slice/map, `strings.Builder`	`-benchmem`
SLO de pausa do GC perdido	Reduza ponteiros, reutilize buffers, heaps menores	`GODEBUG=gctrace=1`
Latência de cauda de RPC	Pooling de conexão, batching, menos chamadas de sistema	Trace + histograma
Codificação JSON quente	Reutilização de `json.Encoder`, structs menores, codegen	Benchmark de carga realista

Quando Não Otimizar (luz vermelha)

Anti-padrão	Por que esperar	Em vez disso
Sem perfil anexado	Adivinhar desperdiça tempo de revisão	Perfilar primeiro
Micro-otimizando caminhos frios	Sem impacto no SLO	Entregue clareza
`unsafe` sem ADR	Custo de segurança e portabilidade	Prova em Go puro
Pools de objetos globais em todos os lugares	Complexidade e estado obsoleto	Pool apenas em alocações comprovadas
Desabilitando verificações em produção	Risco de segurança/confiabilidade	Corrija a causa raiz
`sync.Pool` prematuro	Difícil de raciocinar	Meça alocações

Regras em Nível de Código (após medição)

Regra	Aplique quando	Pule quando
Pré-aloque slices	Tamanho conhecido a partir da entrada	Caminhos de append raros
`strings.Builder`	Muitas concatenações em loop	Poucas junções - use `+` ou `Join`
Passe ponteiros em structs grandes	Profiler mostra custo de cópia	Structs pequenas - prefira valores
Reutilização de buffer `json.Encoder`	Codificação de QPS alta	Saída de CLI única
PGO (otimização guiada por perfil)	Binário de carga de trabalho estável	Caminhos de código em rápida mudança
Ajuste de GOGC	Latência após correções de alocação	Antes de reduzir alocações

Higiene de Benchmark

go test -bench=BenchmarkFoo -benchmem -count=5 ./...
go test -cpuprofile=cpu.prof -bench=BenchmarkFoo ./...
go tool pprof -top cpu.prof

Regra	Requisito
Entrada realista	Cargas úteis em tamanho de produção
Reinicie o timer	Configuração cara fora do loop
Compare a linha de base	Ramificação A vs B em um PR
Documente o ambiente	Contagem de CPU, versão do Go, `GOMAXPROCS`
Rastreie em CI levemente	`benchstat` opcional em tags de release

Regras em Nível de Serviço

Área	Regra
HTTP	Defina timeouts; reutilize `Transport` com limites de conexão ociosa
DB	Tamanho do pool correspondido à concorrência; evite consultas N+1
gRPC	Reutilize conexões; stream quando as cargas úteis são grandes
Concorrência	Trabalhadores limitados; profile com `-race` separadamente
Logging	Logs estruturados em `info`; `debug` fora de caminhos quentes
Métricas	Rótulos de baixa cardinalidade

GC e Runtime (último recurso)

Botão	Use quando	Cuidado
`GOGC`	Pausas comprovadamente limitadas por alocação	Esconde vazamentos
`GOMEMLIMIT`	Risco de OOM com limite claro	Pode aumentar a CPU
GC Green Tea (padrão 1.26)	Novas implantações	Valide na carga de trabalho
`debug.SetMemoryLimit`	Serviços cientes de contêineres	Teste o rollback

Documentando Exceções

Ao ignorar uma regra de clareza por velocidade, a descrição do PR inclui:

Link do perfil ou benchmark
Métrica de SLO ou custo antes/depois
Plano de rollback se a produção regredir

FAQs

A otimização prematura é realmente prejudicial?

Queima tempo de revisão e adiciona bugs em caminhos frios.

Otimize quando a medição mostrar impacto visível ao usuário.

Quando a legibilidade pode ser sacrificada?

Quando um caminho quente é comprovado e a equipe documenta a troca com testes que protegem o comportamento.

Todo PR deve incluir benchmarks?

Apenas PRs de performance ou APIs em caminhos críticos.

Caso contrário, o profiling periódico é suficiente.

CPU alta, mas latência baixa?

Pode ser trabalho em lote/fora de pico.

Verifique histogramas de latência de cauda, não apenas médias.

Como evitar trapaças em benchmarks?

Eleve a configuração, use dados realistas, execute -count=5, compare na mesma classe de máquina.

A análise de escape é suficiente?

Relatórios do compilador ajudam.

Perfis confirmam locais de alocação no mundo real.

Quando adotar PGO?

Binários estáveis com perfil de CPU de produção representativo alimentado na compilação.

Revisite a cada release.

TinyGo/WASM mudam as regras?

A memória é mais limitada; a clareza ainda é o primeiro passo.

Meça em alvos de dispositivo, não apenas em perfis de desktop.

E sobre sync.Pool?

Use quando o perfil de alocação mostrar temporários grandes repetidos.

Reinicie objetos no Get; nunca armazene estado autoritativo apenas em Pool.

Devo ajustar GOGC no Kubernetes?

Somente após a redução de alocação e com o limite de memória alinhado ao limite do contêiner.

Monitore o overhead de CPU do GC.

Como isso se relaciona com Effective Go?

Effective Go favorece a clareza.

Estas regras adicionam quando desviar com evidências.

Qual é o primeiro passo mais rápido?

Use pprof em um benchmark representativo ou carga de staging, seguindo a seção de higiene de benchmark acima.

Relacionado

Testes Orientados a Tabela e Subtestes - estrutura de benchmark
Melhores Práticas de Teste - hábitos de bench e race
Lista de Verificação de Regras do Effective Go - padrões de clareza
Lista de Verificação de Regras de Concorrência - trabalhadores limitados
Resumo de Regras e Melhores Práticas do Go - índice da seção

Links Relacionados Externos

Go Blog (Oficial) - Anúncios oficiais, aprofundamentos e notas de release.
Documentação da Biblioteca Padrão do Go - Referência completa para a biblioteca padrão.
Effective Go - Guia oficial para escrever Go claro e idiomático.
Learning Go (2ª Edição, O'Reilly) - Jon Bodner na O'Reilly.
Concurrency in Go - Katherine Cox-Buday.

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC Green Tea 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).

Use quando um PR alega acelerações, quando os SLOs de latência caem, ou quando revisores suspeitam de micro-otimização prematura.

Como Usar Este Cheatsheet

Exija evidências (profile, benchmark, trace) antes de mesclar PRs apenas de otimização.
Use o código claro como padrão, a menos que um caminho quente seja comprovado.
Emparelhe perfis de CPU com perfis de alocação - corrigir alocações muitas vezes supera ajustes de algoritmo.
Re-benchmark após atualizações do Go; o comportamento do compilador e do GC mudam.

Fluxo de Decisão

Passo	Ação	Pare se
1	Reproduza com carga realista	Não é possível reproduzir - corrija a observabilidade primeiro
2	`go test -bench` + `-benchmem`	Ruído domina - estabilize o ambiente
3	Perfil de CPU (`pprof`)	Função quente não está no seu código - corrija dependências/configuração
4	Perfil de Heap/alocações	Alocações são de inicialização única - adie o trabalho
5	Trace (`go tool trace`)	Problema é espera de IO - ajuste timeouts/paralelismo
6	Mudança de código + delta registrado	Regressão na clareza sem ganho de SLO

Quando Otimizar (luz verde)

Sinal	Alavanca provável	Verifique
Perfil de CPU >10% em uma função	Algoritmo, cache, pré-cálculo	Perfil de CPU depois
`alloc_space` alto em loop	Pré-aloque slice/map, `strings.Builder`	`-benchmem`
SLO de pausa do GC perdido	Reduza ponteiros, reutilize buffers, heaps menores	`GODEBUG=gctrace=1`
Latência de cauda de RPC	Pooling de conexão, batching, menos chamadas de sistema	Trace + histograma
Codificação JSON quente	Reutilização de `json.Encoder`, structs menores, codegen	Benchmark de carga realista

Quando Não Otimizar (luz vermelha)

Anti-padrão	Por que esperar	Em vez disso
Sem perfil anexado	Adivinhar desperdiça tempo de revisão	Perfilar primeiro
Micro-otimizando caminhos frios	Sem impacto no SLO	Entregue clareza
`unsafe` sem ADR	Custo de segurança e portabilidade	Prova em Go puro
Pools de objetos globais em todos os lugares	Complexidade e estado obsoleto	Pool apenas em alocações comprovadas
Desabilitando verificações em produção	Risco de segurança/confiabilidade	Corrija a causa raiz
`sync.Pool` prematuro	Difícil de raciocinar	Meça alocações

Regras em Nível de Código (após medição)

Regra	Aplique quando	Pule quando
Pré-aloque slices	Tamanho conhecido a partir da entrada	Caminhos de append raros
`strings.Builder`	Muitas concatenações em loop	Poucas junções - use `+` ou `Join`
Passe ponteiros em structs grandes	Profiler mostra custo de cópia	Structs pequenas - prefira valores
Reutilização de buffer `json.Encoder`	Codificação de QPS alta	Saída de CLI única
PGO (otimização guiada por perfil)	Binário de carga de trabalho estável	Caminhos de código em rápida mudança
Ajuste de GOGC	Latência após correções de alocação	Antes de reduzir alocações

Higiene de Benchmark

go test -bench=BenchmarkFoo -benchmem -count=5 ./...
go test -cpuprofile=cpu.prof -bench=BenchmarkFoo ./...
go tool pprof -top cpu.prof

Regra	Requisito
Entrada realista	Cargas úteis em tamanho de produção
Reinicie o timer	Configuração cara fora do loop
Compare a linha de base	Ramificação A vs B em um PR
Documente o ambiente	Contagem de CPU, versão do Go, `GOMAXPROCS`
Rastreie em CI levemente	`benchstat` opcional em tags de release

Regras em Nível de Serviço

Área	Regra
HTTP	Defina timeouts; reutilize `Transport` com limites de conexão ociosa
DB	Tamanho do pool correspondido à concorrência; evite consultas N+1
gRPC	Reutilize conexões; stream quando as cargas úteis são grandes
Concorrência	Trabalhadores limitados; profile com `-race` separadamente
Logging	Logs estruturados em `info`; `debug` fora de caminhos quentes
Métricas	Rótulos de baixa cardinalidade

GC e Runtime (último recurso)

Botão	Use quando	Cuidado
`GOGC`	Pausas comprovadamente limitadas por alocação	Esconde vazamentos
`GOMEMLIMIT`	Risco de OOM com limite claro	Pode aumentar a CPU
GC Green Tea (padrão 1.26)	Novas implantações	Valide na carga de trabalho
`debug.SetMemoryLimit`	Serviços cientes de contêineres	Teste o rollback

Documentando Exceções

Ao ignorar uma regra de clareza por velocidade, a descrição do PR inclui:

Link do perfil ou benchmark
Métrica de SLO ou custo antes/depois
Plano de rollback se a produção regredir

FAQs

A otimização prematura é realmente prejudicial?

Queima tempo de revisão e adiciona bugs em caminhos frios.

Otimize quando a medição mostrar impacto visível ao usuário.

Quando a legibilidade pode ser sacrificada?

Quando um caminho quente é comprovado e a equipe documenta a troca com testes que protegem o comportamento.

Todo PR deve incluir benchmarks?

Apenas PRs de performance ou APIs em caminhos críticos.

Caso contrário, o profiling periódico é suficiente.

CPU alta, mas latência baixa?

Pode ser trabalho em lote/fora de pico.

Verifique histogramas de latência de cauda, não apenas médias.

Como evitar trapaças em benchmarks?

Eleve a configuração, use dados realistas, execute -count=5, compare na mesma classe de máquina.

A análise de escape é suficiente?

Relatórios do compilador ajudam.

Perfis confirmam locais de alocação no mundo real.

Quando adotar PGO?

Binários estáveis com perfil de CPU de produção representativo alimentado na compilação.

Revisite a cada release.

TinyGo/WASM mudam as regras?

A memória é mais limitada; a clareza ainda é o primeiro passo.

Meça em alvos de dispositivo, não apenas em perfis de desktop.

E sobre sync.Pool?

Use quando o perfil de alocação mostrar temporários grandes repetidos.

Reinicie objetos no Get; nunca armazene estado autoritativo apenas em Pool.

Devo ajustar GOGC no Kubernetes?

Somente após a redução de alocação e com o limite de memória alinhado ao limite do contêiner.

Monitore o overhead de CPU do GC.

Como isso se relaciona com Effective Go?

Effective Go favorece a clareza.

Estas regras adicionam quando desviar com evidências.

Qual é o primeiro passo mais rápido?

Use pprof em um benchmark representativo ou carga de staging, seguindo a seção de higiene de benchmark acima.

Relacionado

Testes Orientados a Tabela e Subtestes - estrutura de benchmark
Melhores Práticas de Teste - hábitos de bench e race
Lista de Verificação de Regras do Effective Go - padrões de clareza
Lista de Verificação de Regras de Concorrência - trabalhadores limitados
Resumo de Regras e Melhores Práticas do Go - índice da seção

Links Relacionados Externos

Go Blog (Oficial) - Anúncios oficiais, aprofundamentos e notas de release.
Documentação da Biblioteca Padrão do Go - Referência completa para a biblioteca padrão.
Effective Go - Guia oficial para escrever Go claro e idiomático.
Learning Go (2ª Edição, O'Reilly) - Jon Bodner na O'Reilly.
Concurrency in Go - Katherine Cox-Buday.

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC Green Tea 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).

Regras de Performance: Quando Otimizar

Buscar na documentação

Regras de Performance: Quando Otimizar