Stage 3 · Build

Performance, Memory & Debugging

Delve Debugging

Breakpoints, goroutine inspection, core dumps, and remote debugging with dlv.

7 min readGo for SREBuild

Delve Overview

Delve (dlv) is the Go debugger. It supports breakpoints, stepping, variable inspection, goroutine analysis, and core dump debugging. It is the Go equivalent of gdb/lldb.

Install and launch Delve


# Install
go install github.com/go-delve/delve/cmd/dlv@latest

# Debug a program
dlv debug ./cmd/myapp

# Debug tests
dlv test ./internal/pkg

# Attach to running process
dlv attach <pid>

# Debug a compiled binary
dlv exec ./myapp

dlv debug compiles and starts debugging. dlv test debugs test functions. dlv attach attaches to a running process. dlv exec debugs a pre-compiled binary. Choose based on your debugging scenario.

Breakpoints

Breakpoint commands


# Set breakpoint at line
break main.go:42

# Break on function
break main.processRequest

# Break on method
break (*Server).Handle

# Break on package function
break net/http.(*Server).Serve

# Conditional breakpoint
break main.go:42 counter > 100

# Breakpoint with hit count
break main.go:42 -hitcount 5

# List breakpoints
breakpoints

# Clear a breakpoint
clear 1

# Clear all breakpoints
clearAll

# Disable/enable breakpoint
disable 1
enable 1

Breakpoints pause execution at specific locations. Conditional breakpoints only pause when the condition is true. Hit count breakpoints pause after N hits. These are essential for debugging specific scenarios.

Goroutine Inspection

Goroutine debugging


# List all goroutines
goroutines

# Switch to goroutine 1
goroutine 1

# Switch to goroutine by ID
goroutine 5

# Show goroutine stack
goroutines -s

# Show goroutine with labels
goroutines -l

# Show running goroutines
goroutines -t

# Goroutine locations
goroutines -loc main.process

# When at breakpoint, inspect current goroutine
info goroutines

# Print goroutine ID
print goroutine_id()

goroutines lists all goroutines with their IDs, states, and stack traces. Switch between goroutines to inspect their state. This is invaluable for debugging deadlocks, goroutine leaks, and race conditions.

Core Dumps

Core dumps capture the state of a running process. They are useful for debugging crashes in production without stopping the service.

Core dump debugging


# Generate core dump from running process
kill -ABRT <pid>

# Or use gcore
gcore <pid>

# Debug core dump
dlv core <binary> <core>

# In the debugger
(dlv) goroutines        # List all goroutines
(dlv) goroutine 1       # Switch to goroutine 1
(dlv) bt                # Backtrace
(dlv) print variable    # Print variable value
(dlv) locals            # Print all local variables

# Go core dump analysis
go tool pprof http://localhost:6060/debug/pprof/goroutine?debug=2

Core dumps capture the full process state. dlv core lets you inspect goroutines, variables, and stack traces from the dump. This is the safest way to debug production issues — the core dump is taken without stopping the process.

Remote Debugging

Remote debugging setup


# Start headless debugger
dlv debug ./cmd/myapp --headless --listen=:2345 --api-version=2

# Connect from another terminal
dlv connect localhost:2345

# Debug in container
# Dockerfile:
# RUN go install github.com/go-delve/delve/cmd/dlv@latest
# CMD ["dlv", "--headless", "--listen=:2345", "--api-version=2", "debug", "./cmd/myapp"]

# Debug in Kubernetes
kubectl port-forward pod/myapp 2345:2345
dlv connect localhost:2345

# IDE integration (VS Code)
# launch.json:
# {
#     "name": "Attach to Delve",
#     "type": "go",
#     "request": "attach",
#     "mode": "remote",
#     "remotePath": "/go/src/app",
#     "port": 2345,
#     "host": "127.0.0.1"
# }

Headless mode runs dlv without a terminal. Connect from another terminal or IDE. In Kubernetes, use port-forward to connect. IDE integration provides visual debugging with breakpoint management and variable inspection.

Essential Commands

Essential dlv commands


# Execution control
continue        # Continue execution
step            # Step into function
stepout         # Step out of function
next            # Step over function
restart         # Restart program

# Inspection
print variable  # Print variable value
locals          # Print all local variables
args            # Print function arguments
regs            # Print registers
disassemble     # Disassemble current function

# Breakpoints
break main.go:42
breakpoints     # List all breakpoints
clear 1         # Clear breakpoint

# Goroutines
goroutines      # List goroutines
goroutine 1     # Switch goroutine

# Watchpoints
watch variable  # Watch for changes
watch -w variable  # Watch for writes only

# Source
list            # Show source code
sources         # List source files
funcs           # List functions

# Exit
exit            # Exit debugger

step/next/stepout control execution flow. print/locals inspect state. watch monitors variable changes. These commands are the essential toolkit for debugging Go programs with Delve.

Use delve for production debugging

Delve's headless mode is safe for production debugging. It adds minimal overhead and does not modify the running program. Connect remotely, set breakpoints, inspect goroutines, and disconnect without restarting the service.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.