Depuración con Delve

Delve (dlv) es el depurador estándar para Go.

Detiene un programa en ejecución en puntos de interrupción, avanza paso a paso por el código, inspecciona goroutines y lee valores de variables utilizando información de depuración DWARF del compilador.

Resumen

Usa Delve cuando las pruebas y los registros no sean suficientes para explicar un estado incorrecto, especialmente con concurrencia, interfaces o callbacks de terceros.

La CLI y las integraciones de IDE comparten el mismo backend: puntos de interrupción, continuar, siguiente, paso y listado de goroutines.

Los modos remoto y sin cabeza se conectan a procesos en contenedores o pods de Kubernetes cuando puedes reproducir problemas fuera de tu portátil.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

# Depurar el paquete principal actual
dlv debug .
 
# Depurar una función de prueba
dlv test . -- -test.run TestName
 
# Comandos REPL comunes después de una interrupción
break main.main
continue
next
step
goroutines
print err

Cuándo usar esto:

• Se produce un pánico solo bajo carga con muchas goroutines.
• Una interfaz contiene un tipo concreto inesperado.
• Necesitas inspeccionar variables de bucle en una iteración específica.
• Ejecuciones de reproducción similares a producción en Docker y puedes conectarte localmente.

Ejemplo de trabajo

// 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())
    }
}

Depura la prueba fallida:

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

En el shell de Delve:

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

Lo que esto demuestra:

• dlv test compila binarios de prueba con símbolos de depuración y pasa indicadores después de -- a go test.
• Los puntos de interrupción pueden apuntar a líneas de código fuente de prueba.
• goroutines lista pilas concurrentes; cambia con goroutine <id>.
• print muestra memoria en vivo, incluidos los campos de struct detrás de los mutex (ten en cuenta el orden de bloqueo).

Inmersión Profunda

Cómo funciona

• El compilador de Go emite información de depuración DWARF al compilar con la configuración de depuración predeterminada.
• Delve controla el proceso inferior con APIs de depuración del SO (ptrace en Linux, equivalentes en otros lugares).
• Los recorridos de pila conscientes de goroutine utilizan metadatos en tiempo de ejecución, no solo pilas locales del hilo.
• La API RPC de Delve (v2) potencia los clientes IDE.

Comandos principales

Pruebas y Paquetes que no son main

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

Usa -count=1 para deshabilitar la caché de pruebas mientras iteras.

Para paquetes main en cmd/:

dlv debug ./cmd/api

Depuración Remota y sin Cabeza

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

Las configuraciones de lanzamiento de IDE se conectan a 127.0.0.1:2345.

En Kubernetes, reenvía el puerto de depuración del pod; restringe el acceso a la red porque Delve otorga inspección de memoria.

Notas de Go

# Cuando las variables se optimizan
go build -gcflags="all=-N -l" -o bin/app ./cmd/app
dlv exec ./bin/app

-N deshabilita las optimizaciones; -l deshabilita la inlining.

Úsalo solo para compilaciones de depuración, no para artefactos de lanzamiento de producción.

Trampas

• Variables optimizadas - Las funciones inlined ocultan las variables locales en print. Solución: Recompila con -gcflags="all=-N -l" para la sesión de depuración.
• Depuración de binarios eliminados - -ldflags="-s -w" elimina la información de depuración. Solución: Conserva los símbolos en imágenes de depuración/staging; elimina solo las compilaciones de lanzamiento a las que nunca te conectas.
• Punto de interrupción en la goroutine incorrecta - Una interrupción se activa en cualquier goroutine que alcance la línea. Solución: Usa cond con estado específico de goroutine o interrumpe más cerca de la rama sospechosa.
• Las carreras de tiempo desaparecen - Detener hilos cambia la temporización. Solución: Combina Delve con compilaciones -race para carreras de datos; usa Delve para la inspección de estado después de la reproducción.
• Delve en Alpine sin compatibilidad - Las discrepancias entre musl y glibc rompen la conexión. Solución: Usa imágenes de depuración basadas en la distribución que coincida con la compilación, o dlv compilado para la libc de destino.
• Riesgo de conexión en producción - Pausar un servicio en vivo interrumpe el tráfico. Solución: Reproduce en staging, usa volcados de núcleo o pods de depuración efímeros con autenticación.

Alternativas

Preguntas frecuentes

Relacionado

• Herramientas para desarrolladores de Go: LSP, Depurador y Analizadores - dónde encaja Delve en la cadena de herramientas
• Conceptos básicos de configuración de herramientas de Go - instala dlv y los primeros comandos
• gopls: Navegación, Refactorización y Diagnósticos - navegación estática antes de la depuración en tiempo de ejecución
• Conceptos básicos de depuración de Go - patrones de flujo de trabajo de defectos más amplios

Versiones de pila: Esta página fue escrita para Go 1.26.x (predeterminado de GC de Green Tea, go fix modernizadores - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).