Depurando com Delve

Delve (dlv) é o depurador padrão para Go.

Ele para um programa em execução em breakpoints, percorre o código, inspeciona goroutines e lê valores de variáveis usando informações de depuração DWARF do compilador.

Resumo

Use Delve quando testes e logs não forem suficientes para explicar um estado incorreto, especialmente com concorrência, interfaces ou callbacks de terceiros.

A CLI e as integrações de IDE compartilham o mesmo backend: breakpoints, continue, next, step e listagem de goroutines.

Os modos remoto e headless se conectam a processos em contêineres ou pods Kubernetes quando você consegue reproduzir problemas fora do seu laptop.

Receita

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

# Depurar o pacote main atual
dlv debug .
 
# Depurar uma função de teste
dlv test . -- -test.run TestName
 
# Comandos REPL comuns após a interrupção
break main.main
continue
next
step
goroutines
print err

Quando usar isso:

• Um panic ocorre apenas sob carga com muitas goroutines.
• Uma interface contém um tipo concreto inesperado.
• Você precisa inspecionar variáveis de loop em uma iteração específica.
• Execuções de reprodução semelhantes à produção em Docker e você pode se conectar localmente.

Exemplo de Trabalho

// example.com/demo/internal/counter/counter.go
package counter
 
import "sync"
 
type Counter struct {
    mu sync.Mutex
    n  int
}
 
func (c *Counter) Inc() {
    c.mu.Lock()
    c.n++
    c.mu.Unlock()
}
 
func (c *Counter) Value() int {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.n
}

// example.com/demo/internal/counter/counter_test.go
package counter
 
import (
    "sync"
    "testing"
)
 
func TestConcurrentInc(t *testing.T) {
    var c Counter
    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            c.Inc()
        }()
    }
    wg.Wait()
    if c.Value() != 10 {
        t.Fatalf("got %d", c.Value())
    }
}

Depure o teste com falha:

cd internal/counter
dlv test . -- -test.run TestConcurrentInc

No shell Delve:

(dlv) break counter_test.go:22
(dlv) continue
(dlv) goroutines
(dlv) goroutine 5 bt
(dlv) print c.n

O que isso demonstra:

• dlv test compila binários de teste com símbolos de depuração e passa flags após -- para go test.
• Breakpoints podem ter como alvo linhas de código de teste.
• goroutines lista pilhas concorrentes; mude com goroutine <id>.
• print mostra memória ao vivo, incluindo campos de struct protegidos por mutexes (observe a ordem de bloqueio).

Mergulho Profundo

Como Funciona

• O compilador Go emite informações de depuração DWARF ao compilar com configurações de depuração padrão.
• Delve controla o processo inferior com APIs de depuração do SO (ptrace no Linux, equivalentes em outros lugares).
• Caminhadas de pilha cientes de goroutine usam metadados de tempo de execução, não apenas pilhas locais de thread.
• A API RPC do Delve (v2) alimenta clientes IDE.

Comandos Principais

Testes e Pacotes Não Principais

dlv test ./... -- -test.run TestLeak -count=1

Use -count=1 para desativar o cache de teste enquanto itera.

Para pacotes main em cmd/:

dlv debug ./cmd/api

Depuração Remota e Headless

dlv debug --headless --listen=:2345 --api-version=2 --accept-multiclient .

As configurações de inicialização da IDE se conectam a 127.0.0.1:2345.

No Kubernetes, faça port-forward da porta de depuração do pod; restrinja o acesso à rede, pois Delve concede inspeção de memória.

Notas do Go

# Quando as variáveis são otimizadas
go build -gcflags="all=-N -l" -o bin/app ./cmd/app
dlv exec ./bin/app

-N desabilita otimizações; -l desabilita inlining.

Use apenas para builds de depuração, não para artefatos de lançamento de produção.

Armadilhas

• Variáveis otimizadas - Funções inlined ocultam locais em print. Correção: Recompile com -gcflags="all=-N -l" para a sessão de depuração.
• Depurando binários stripped - -ldflags="-s -w" remove informações de depuração. Correção: Mantenha os símbolos em imagens de depuração/staging; remova apenas builds de lançamento nos quais você nunca se conecta.
• Breakpoint na goroutine errada - Uma interrupção é acionada em qualquer goroutine que atinge a linha. Correção: Use cond com estado específico da goroutine ou interrompa mais perto do branch suspeito.
• Corridas baseadas em tempo desaparecem - Parar threads altera o tempo. Correção: Combine Delve com builds -race para corridas de dados; use Delve para inspeção de estado após a reprodução.
• Delve em Alpine sem compat - Discrepâncias musl vs glibc quebram a conexão. Correção: Use imagens de depuração baseadas na distribuição que corresponda ao build, ou dlv compilado para a libc de destino.
• Risco de anexação em produção - Pausar um serviço ativo interrompe o tráfego. Correção: Reproduza em staging, use core dumps ou pods de depuração efêmeros com autenticação.

Alternativas

FAQs

Relacionado

• Ferramentas de Desenvolvedor Go: LSP, Depurador e Analisadores - onde Delve se encaixa na cadeia de ferramentas
• Noções Básicas de Configuração de Ferramentas Go - instale dlv e os primeiros comandos
• gopls: Navegação, Refatoração e Diagnósticos - navegação estática antes da depuração em tempo de execução
• Noções Básicas de Depuração Go - padrões de fluxo de trabalho de defeitos mais amplos

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).