Compilar, Testar e Analisar Desempenho (Profile) a partir do Shell

Execute compilações e testes a partir do shell, capture perfis com go tool pprof e alinhe falhas com timestamps do journalctl em hosts Linux.

Resumo

A toolchain do Go é nativa para CLI: go build, go test e go tool pprof são projetados para scripts, CI e sessões SSH.

Combine-os com redirecionamento de shell, tee e consultas de journal para que um teste falho no seu laptop use os mesmos comandos que você executará durante um incidente de produção.

Receita

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

# Compilar e testar a partir da raiz do módulo
go build -o bin/api ./cmd/api
go test ./... -count=1 -race 2>&1 | tee test.log
 
# Analisar CPU de um benchmark localmente
go test -bench=. -benchmem -cpuprofile=cpu.prof -run=^$ ./...
go tool pprof -http=:0 cpu.prof
 
# Buscar perfil de um servidor em execução (quando o endpoint pprof está habilitado)
curl -s "http://localhost:6060/debug/pprof/profile?seconds=30" -o live.prof
go tool pprof live.prof
 
# Correlacionar com logs do systemd
sudo journalctl -u api.service --since "10 min ago" --no-pager

Quando usar isso:

• Você precisa de um loop de compilação/teste repetível antes de abrir um PR.
• A latência regrediu e você quer evidências de CPU ou heap, não suposições.
• Um serviço falhou em uma VM e você precisa alinhar a saída do go test com os timestamps do journal.

Exemplo de Trabalho

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
 
# Compilar
mkdir -p bin
go build -ldflags="-s -w" -o bin/api ./cmd/api
 
# Testar com detector de race; manter artefato de log
go test ./... -count=1 -race -timeout=5m 2>&1 | tee artifacts/test-$(date +%Y%m%d%H%M).log
 
# Micro-benchmark + perfil de CPU para um pacote
PKG=./internal/handler
go test "$PKG" -bench=BenchmarkHealth -benchmem \
  -cpuprofile=artifacts/cpu.prof -run=^$ -count=1
 
go tool pprof -top artifacts/cpu.prof | head -20
 
# Se api.service estiver em execução neste host, buscar linhas recentes do journal
if systemctl is-active --quiet api.service 2>/dev/null; then
  journalctl -u api.service --since "15 min ago" -n 200 --no-pager \
    | tee artifacts/api.journal.snippet
fi

O que isso demonstra:

• Diretório de artefatos para binários, logs de teste e perfis com timestamps.
• go test ./... habilitado para race, adequado para paridade de CI.
• Perfil de CPU com escopo de benchmark em vez de analisar o módulo inteiro cegamente.
• Snippet do journalctl capturado ao lado da saída do teste para cadernos de incidentes.

Mergulho Profundo

Como Funciona

• go build compila pacotes; -o nomeia o binário de saída e -ldflags injeta metadados de versão ou remove símbolos de depuração.
• go test executa arquivos _test.go; flags como -race, -count=1 e -timeout mapeiam diretamente para o YAML da CI.
• go test -cpuprofile e -memprofile anexam amostragem do runtime/pprof durante testes ou benchmarks.
• go tool pprof lê arquivos de perfil ou URLs e pode abrir uma interface web local (-http) para flame graphs.
• Serviços ativos expõem /debug/pprof/* quando você importa net/http/pprof e escuta em uma porta de depuração (proteja em produção).
• journalctl lê o journal do systemd; filtrar por unidade e intervalo de tempo coloca traces Go ao lado de eventos OOM ou de reinício.

Flags Úteis do go test

Padrões de Busca de Perfis do pprof

Notas do Go

// cmd/api/main.go - listener de depuração opcional (apenas staging)
import _ "net/http/pprof"
 
go func() {
    log.Println(http.ListenAndServe("127.0.0.1:6060", nil))
}()

Vincule ao loopback, proteja com autenticação ou política de rede antes de expor além do localhost.

Armadilhas

• Analisar sem carga - Um perfil de CPU de 30s em um servidor ocioso mostra pilhas ociosas. Correção: reproduza o tráfego com hey, k6 ou testes de integração enquanto analisa.
• Deixar o pprof em :6060 público - Atacantes escaneiam portas pprof abertas. Correção: vincule a 127.0.0.1, use port-forward ou restrinja com autenticação.
• Cache de teste ocultando falhas - Testes instáveis passam localmente após uma execução verde. Correção: go test -count=1 na CI e ao depurar instabilidades.
• Detector de race apenas em Go puro - Pacotes com uso intensivo de CGO podem precisar de compilações com tags. Correção: divida as execuções de race por pacote ou use -tags consistentemente.
• Logs enormes do go test ./... - Falhas rolam para fora da tela no tmux. Correção: sempre use tee para um arquivo e rg FAIL depois.
• Confusão de fuso horário do journal - journalctl usa o horário local por padrão; a UTC da CI é diferente. Correção: passe --utc ou anote os deslocamentos na documentação do incidente.

Alternativas

FAQs

Relacionados

• Noções Básicas da CLI do Linux - tee e pipe de logs
• Pesquisa, ripgrep e jq para Depuração - pesquisar saída de teste e log
• systemd e Arquivos de Unidade de Serviço para Binários Go - integração com journal
• Contêineres a partir da CLI: docker e kubectl - port-forward para pprof
• Noções Básicas de Teste Go - profundidade de teste Go

Versões da 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).