Noções Básicas de Depuração em Go

10 exemplos para você começar com Cenários de Defeitos - 7 básicos e 3 intermediários.

Pré-requisitos

Instale o Go 1.26.x ou posterior em go.dev/dl.
Instale o Delve: go install github.com/go-delve/delve/cmd/dlv@latest.
Crie um módulo: mkdir debuglab && cd debuglab && go mod init example.com/debuglab.
Salve trechos como main.go ou arquivos de teste e execute com go run . ou go test -v.

Exemplos Básicos

1. Printf com verbos úteis

Registre valores com formatação que expõe tipo e estrutura.

package main
 
import "fmt"
 
func main() {
    s := []int{1, 2, 3}
    fmt.Printf("s=%#v len=%d cap=%d\n", s, len(s), cap(s))
}

%#v imprime a representação da sintaxe Go, útil para slices nil vs vazios.
Sempre registre len e cap ao depurar bugs de append e sub-slices.
Prefira log.Printf em servidores para que timestamps e linhas de arquivo apareçam.

Relacionado: Cópia de Cabeçalho de Slice e Surpresa de Append - quando len/cap mentem

2. Registre erros fatais com contexto de pilha

Envolva erros e imprima antes de sair.

package main
 
import (
    "fmt"
    "log"
    "os"
)
 
func loadConfig(path string) error {
    _, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("loadConfig(%q): %w", path, err)
    }
    return nil
}
 
func main() {
    if err := loadConfig("missing.yaml"); err != nil {
        log.Fatalf("startup failed: %v", err)
    }
}

%w preserva a cadeia de erros para errors.Is e errors.As.
log.Fatalf sai com código 1 após imprimir.
Em bibliotecas, retorne erros em vez de registrar.

Relacionado: Depurando Go: Falhas Observáveis e Pontos Críticos - famílias de sintomas

3. Leia um rastro de pilha de pânico

Dispare um ponteiro nil para estudar a saída da pilha.

package main
 
type Store struct{}
 
func (s *Store) Get() int { return 1 }
 
func main() {
    var s *Store
    _ = s.Get() // panic: nil pointer
}

Os frames superiores mostram onde ocorreu o pânico; desça para a cadeia de chamadores.
Procure por conversões de interface e ponteiros nil retornados acima da linha de pânico.
Execute com GOTRACEBACK=all para pilhas completas, incluindo frames de runtime.

Relacionado: Análise de Defeito de Interface Nil vs Ponteiro Nil - armadilhas de nil tipado

4. Delve: break e continue

Inicie uma sessão de depuração em um programa simples.

package main
 
import "fmt"
 
func sum(nums []int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}
 
func main() {
    fmt.Println(sum([]int{1, 2, 3}))
}

dlv debug .
# no prompt do (dlv):
break main.sum
continue
print total
next

dlv debug . compila e inicia sob o depurador.
break define um ponto de interrupção; continue executa até atingi-lo.
next avança sobre as linhas; step entra nas chamadas.

Relacionado: Depurando com Delve - referência completa do Delve

5. Delve: inspecione goroutines

Liste goroutines ao depurar concorrência.

package main
 
import (
    "fmt"
    "sync"
)
 
func main() {
    var wg sync.WaitGroup
    for i := 0; i < 3; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fmt.Println("work")
        }()
    }
    wg.Wait()
}

dlv debug .
break main.main
continue
goroutines

goroutines lista cada goroutine com um trecho de pilha.
Compare IDs de goroutine quando um caminho bloqueia para sempre.
Use goroutine <id> bt para um backtrace completo de uma goroutine.

Relacionado: Vazamentos de Goroutine e Cancelamento de Contexto Ausente - pilhas bloqueadas

6. Execute testes sob o detector de corrida

Capture acesso não sincronizado durante os testes.

package counter
 
import "testing"
 
var n int
 
func Inc() { n++ }
 
func TestInc(t *testing.T) {
    done := make(chan struct{})
    go func() { Inc(); close(done) }()
    Inc()
    <-done
}

go test -race ./...

-race instrumenta o acesso à memória e relata leituras/escritas concorrentes.
A saída de corrida inclui pilhas de goroutine para ambos os lados da corrida.
Execute -race em CI para pacotes que compartilham estado mutável.

Relacionado: Cenários de Corrida de Dados e Correções do Detector de Corrida - padrões de correção

7. Despeje o perfil de goroutine localmente

Exponha o pprof para caças de vazamentos.

package main
 
import (
    "log"
    "net/http"
    _ "net/http/pprof"
)
 
func main() {
    log.Println(http.ListenAndServe("localhost:6060", nil))
}

go run .
# outro terminal:
curl -s localhost:6060/debug/pprof/goroutine?debug=1 | head

Importar _ "net/http/pprof" registra manipuladores no DefaultServeMux.
O perfil de goroutine mostra onde cada goroutine está bloqueado.
Use o mesmo endpoint contra o staging ao reproduzir vazamentos.

Relacionado: Vazamentos de Goroutine e Cancelamento de Contexto Ausente - interprete perfis

Exemplos Intermediários

8. Depure um teste com Delve

Pare dentro de uma função de teste com falha.

package mathutil
 
import "testing"
 
func Add(a, b int) int { return a + b }
 
func TestAdd(t *testing.T) {
    got := Add(2, 2)
    if got != 4 {
        t.Fatalf("got %d want 4", got)
    }
}

dlv test . -- -test.run TestAdd
break mathutil.TestAdd
continue
print got

dlv test envolve go test com suporte a depurador.
Passe flags de teste após --.
Defina pontos de interrupção em funções auxiliares de teste da mesma forma que em código de produção.

Relacionado: Depurando com Delve - fluxos de trabalho dlv test

9. Registre o contexto da requisição HTTP em erros

Vincule logs a IDs de requisição durante a depuração de manipuladores.

package main
 
import (
    "context"
    "log"
    "net/http"
)
 
type ctxKey string
 
const requestIDKey ctxKey = "requestID"
 
func withID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, requestIDKey, id)
}
 
func idFrom(ctx context.Context) string {
    v, _ := ctx.Value(requestIDKey).(string)
    return v
}
 
func handler(w http.ResponseWriter, r *http.Request) {
    ctx := withID(r.Context(), "req-42")
    if err := work(ctx); err != nil {
        log.Printf("request_id=%s err=%v", idFrom(ctx), err)
        http.Error(w, "error", http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusOK)
}
 
func work(ctx context.Context) error { return nil }
 
func main() {
    http.HandleFunc("/", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Passe IDs através de context.Context em vez de variáveis globais.
Registre request_id em cada caminho de erro para correlacionar com traces.
Passe r.Context() para I/O downstream para que o cancelamento apareça em perfis.

Relacionado: Vazamentos de Goroutine e Cancelamento de Contexto Ausente - ctx em manipuladores

10. Compare relógio monotônico vs. relógio de parede em logs

Depure defeitos relacionados ao tempo com locais explícitos.

package main
 
import (
    "fmt"
    "time"
)
 
func main() {
    utc := time.Date(2026, 7, 15, 12, 0, 0, 0, time.UTC)
    local, err := time.Parse(time.RFC3339, "2026-07-15T12:00:00-07:00")
    if err != nil {
        panic(err)
    }
    fmt.Println("utc", utc.Format(time.RFC3339))
    fmt.Println("local", local.Format(time.RFC3339))
    fmt.Println("equal?", utc.Equal(local))
}

time.Parse sem zona no layout usa UTC para strings sem deslocamento.
Equal compara instantes; a saída de Format depende de Location().
Registre t.Location() e RFC3339 ao depurar bugs de timestamp.

Relacionado: Fuso Horário e Armadilhas de time.Parse - bordas de JSON e DST

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

Pré-requisitos

Instale o Go 1.26.x ou posterior em go.dev/dl.
Instale o Delve: go install github.com/go-delve/delve/cmd/dlv@latest.
Crie um módulo: mkdir debuglab && cd debuglab && go mod init example.com/debuglab.
Salve trechos como main.go ou arquivos de teste e execute com go run . ou go test -v.

Exemplos Básicos

1. Printf com verbos úteis

Registre valores com formatação que expõe tipo e estrutura.

package main
 
import "fmt"
 
func main() {
    s := []int{1, 2, 3}
    fmt.Printf("s=%#v len=%d cap=%d\n", s, len(s), cap(s))
}

%#v imprime a representação da sintaxe Go, útil para slices nil vs vazios.
Sempre registre len e cap ao depurar bugs de append e sub-slices.
Prefira log.Printf em servidores para que timestamps e linhas de arquivo apareçam.

Relacionado: Cópia de Cabeçalho de Slice e Surpresa de Append - quando len/cap mentem

2. Registre erros fatais com contexto de pilha

Envolva erros e imprima antes de sair.

package main
 
import (
    "fmt"
    "log"
    "os"
)
 
func loadConfig(path string) error {
    _, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("loadConfig(%q): %w", path, err)
    }
    return nil
}
 
func main() {
    if err := loadConfig("missing.yaml"); err != nil {
        log.Fatalf("startup failed: %v", err)
    }
}

%w preserva a cadeia de erros para errors.Is e errors.As.
log.Fatalf sai com código 1 após imprimir.
Em bibliotecas, retorne erros em vez de registrar.

Relacionado: Depurando Go: Falhas Observáveis e Pontos Críticos - famílias de sintomas

3. Leia um rastro de pilha de pânico

Dispare um ponteiro nil para estudar a saída da pilha.

package main
 
type Store struct{}
 
func (s *Store) Get() int { return 1 }
 
func main() {
    var s *Store
    _ = s.Get() // panic: nil pointer
}

Os frames superiores mostram onde ocorreu o pânico; desça para a cadeia de chamadores.
Procure por conversões de interface e ponteiros nil retornados acima da linha de pânico.
Execute com GOTRACEBACK=all para pilhas completas, incluindo frames de runtime.

Relacionado: Análise de Defeito de Interface Nil vs Ponteiro Nil - armadilhas de nil tipado

4. Delve: break e continue

Inicie uma sessão de depuração em um programa simples.

package main
 
import "fmt"
 
func sum(nums []int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}
 
func main() {
    fmt.Println(sum([]int{1, 2, 3}))
}

dlv debug .
# no prompt do (dlv):
break main.sum
continue
print total
next

dlv debug . compila e inicia sob o depurador.
break define um ponto de interrupção; continue executa até atingi-lo.
next avança sobre as linhas; step entra nas chamadas.

Relacionado: Depurando com Delve - referência completa do Delve

5. Delve: inspecione goroutines

Liste goroutines ao depurar concorrência.

package main
 
import (
    "fmt"
    "sync"
)
 
func main() {
    var wg sync.WaitGroup
    for i := 0; i < 3; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fmt.Println("work")
        }()
    }
    wg.Wait()
}

dlv debug .
break main.main
continue
goroutines

goroutines lista cada goroutine com um trecho de pilha.
Compare IDs de goroutine quando um caminho bloqueia para sempre.
Use goroutine <id> bt para um backtrace completo de uma goroutine.

Relacionado: Vazamentos de Goroutine e Cancelamento de Contexto Ausente - pilhas bloqueadas

6. Execute testes sob o detector de corrida

Capture acesso não sincronizado durante os testes.

package counter
 
import "testing"
 
var n int
 
func Inc() { n++ }
 
func TestInc(t *testing.T) {
    done := make(chan struct{})
    go func() { Inc(); close(done) }()
    Inc()
    <-done
}

go test -race ./...

-race instrumenta o acesso à memória e relata leituras/escritas concorrentes.
A saída de corrida inclui pilhas de goroutine para ambos os lados da corrida.
Execute -race em CI para pacotes que compartilham estado mutável.

Relacionado: Cenários de Corrida de Dados e Correções do Detector de Corrida - padrões de correção

7. Despeje o perfil de goroutine localmente

Exponha o pprof para caças de vazamentos.

package main
 
import (
    "log"
    "net/http"
    _ "net/http/pprof"
)
 
func main() {
    log.Println(http.ListenAndServe("localhost:6060", nil))
}

go run .
# outro terminal:
curl -s localhost:6060/debug/pprof/goroutine?debug=1 | head

Importar _ "net/http/pprof" registra manipuladores no DefaultServeMux.
O perfil de goroutine mostra onde cada goroutine está bloqueado.
Use o mesmo endpoint contra o staging ao reproduzir vazamentos.

Relacionado: Vazamentos de Goroutine e Cancelamento de Contexto Ausente - interprete perfis

Exemplos Intermediários

8. Depure um teste com Delve

Pare dentro de uma função de teste com falha.

package mathutil
 
import "testing"
 
func Add(a, b int) int { return a + b }
 
func TestAdd(t *testing.T) {
    got := Add(2, 2)
    if got != 4 {
        t.Fatalf("got %d want 4", got)
    }
}

dlv test . -- -test.run TestAdd
break mathutil.TestAdd
continue
print got

dlv test envolve go test com suporte a depurador.
Passe flags de teste após --.
Defina pontos de interrupção em funções auxiliares de teste da mesma forma que em código de produção.

Relacionado: Depurando com Delve - fluxos de trabalho dlv test

9. Registre o contexto da requisição HTTP em erros

Vincule logs a IDs de requisição durante a depuração de manipuladores.

package main
 
import (
    "context"
    "log"
    "net/http"
)
 
type ctxKey string
 
const requestIDKey ctxKey = "requestID"
 
func withID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, requestIDKey, id)
}
 
func idFrom(ctx context.Context) string {
    v, _ := ctx.Value(requestIDKey).(string)
    return v
}
 
func handler(w http.ResponseWriter, r *http.Request) {
    ctx := withID(r.Context(), "req-42")
    if err := work(ctx); err != nil {
        log.Printf("request_id=%s err=%v", idFrom(ctx), err)
        http.Error(w, "error", http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusOK)
}
 
func work(ctx context.Context) error { return nil }
 
func main() {
    http.HandleFunc("/", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Passe IDs através de context.Context em vez de variáveis globais.
Registre request_id em cada caminho de erro para correlacionar com traces.
Passe r.Context() para I/O downstream para que o cancelamento apareça em perfis.

Relacionado: Vazamentos de Goroutine e Cancelamento de Contexto Ausente - ctx em manipuladores

10. Compare relógio monotônico vs. relógio de parede em logs

Depure defeitos relacionados ao tempo com locais explícitos.

package main
 
import (
    "fmt"
    "time"
)
 
func main() {
    utc := time.Date(2026, 7, 15, 12, 0, 0, 0, time.UTC)
    local, err := time.Parse(time.RFC3339, "2026-07-15T12:00:00-07:00")
    if err != nil {
        panic(err)
    }
    fmt.Println("utc", utc.Format(time.RFC3339))
    fmt.Println("local", local.Format(time.RFC3339))
    fmt.Println("equal?", utc.Equal(local))
}

time.Parse sem zona no layout usa UTC para strings sem deslocamento.
Equal compara instantes; a saída de Format depende de Location().
Registre t.Location() e RFC3339 ao depurar bugs de timestamp.

Relacionado: Fuso Horário e Armadilhas de time.Parse - bordas de JSON e DST

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

Noções Básicas de Depuração em Go

Buscar na documentação

Noções Básicas de Depuração em Go