Race Detector: Executando e Interpretando Saída

O detector de race do Go instrumenta acessos à memória em tempo de compilação para encontrar leituras e escritas concorrentes não sincronizadas.

Execute-o em CI em pacotes que usam goroutines; aprenda a ler seus relatórios para corrigir bugs reais, não para silenciar ruído.

Resumo

Ative com -race em go test, go run ou go build.

Uma data race ocorre quando duas goroutines acessam a mesma localização de memória, pelo menos uma delas é uma escrita, e não há ordenação happens-before.

Relatórios mostram pilhas de goroutines para ambos os lados da race.

Corrija com mutexes, canais, atômicos ou reestruturando a propriedade - nunca diga "passou uma vez sem -race".

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

go test -race ./...
go run -race .
go build -race -o bin/app .
./bin/app   # apenas em staging - builds com race são mais lentos e usam mais memória

Quando usar isso:

• Todo pipeline de CI para pacotes concorrentes.
• Após refatorar caches compartilhados, singletons ou globais de manipuladores.
• Quando testes falham sob -count=10 paralelo.
• Antes de culpar o escalonador por valores de contador impossíveis.

Exemplo de Trabalho

Código com bug e padrão típico de saída do detector:

package counter
 
import "sync"
 
var n int // BUG: não sincronizado
 
func Inc() { n++ }
 
func BrokenParallel(wg *sync.WaitGroup) {
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            Inc()
        }()
    }
}

$ go test -race ./...
==================
WARNING: DATA RACE
Write at 0x... by goroutine 7:
  example.com/counter.Inc()
  example.com/counter.BrokenParallel.func1()
 
Previous read at 0x... by goroutine 6:
  ...
==================

Versão corrigida:

var (
    mu sync.Mutex
    n  int
)
 
func Inc() {
    mu.Lock()
    n++
    mu.Unlock()
}

O que isso demonstra:

• O relatório de race nomeia funções e IDs de goroutine em ambos os lados.
• Inc e seus chamadores aparecem nas pilhas - comece lendo a partir dos frames do seu código.
• Mutex estabelece happens-before entre os incrementos.
• Reexecute -race até que esteja limpo.

Mergulho Profundo

Como Funciona

• O compilador insere o rastreamento happens-before em torno de primitivas de sincronização e operações de canal.
• O runtime grava metadados de acesso à memória (memória sombra).
• Acessos conflitantes não sincronizados imprimem um relatório com rastros de pilha.
• Sobrecarga: aproximadamente 2-10x CPU e 5-10x memória - não para produção.
• A cobertura é por processo - races precisam de interlaçamentos que os testes exercitam.

Anatomia do Relatório

Estratégias de Correção

Notas do Go

# Caça a race intermitente
go test -race -count=50 ./pkg
 
# Snippet de CI
go test -race -short ./...

Armadilhas

• Pular -race em CI - Races chegam à produção. Correção: -race obrigatório para pacotes principais.
• Corrigir testes apenas com -parallel 1 - Esconde races. Correção: sincronize o código em teste.
• Ignorar races em código de terceiros - Pode ainda ser seu caminho de chamada. Correção: atualize a dependência ou envolva com sync.
• Assumir que atômicos sem -race limpam - Races de lógica permanecem. Correção: atômicos para contadores simples; mutex para invariantes.
• Sem race, mas deadlock - O detector não pega deadlocks. Correção: timeouts, go test -timeout, detectores de deadlock em staging.

Alternativas

FAQs

Relacionado

• Fundamentos de Concorrência - exemplo de teste de race 10
• sync.Mutex, RWMutex & WaitGroup - ferramenta de correção principal
• Canais: Regras de Buffer, Não Buffer e Fechamento - transferência de propriedade
• Concorrência em Go: Goroutines e Canais Primeiro - modelo happens-before
• Melhores Práticas de Fundamentos de Concorrência - hábitos de CI

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