debugging-techniques

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debugging Techniques

调试技术

Purpose

用途

Provides systematic debugging workflows for local, remote, container, and production environments across Python, Go, Rust, and Node.js. Covers interactive debuggers, container debugging with ephemeral containers, and production-safe techniques using correlation IDs and distributed tracing.

为Python、Go、Rust和Node.js提供本地、远程、容器及生产环境下的系统化调试工作流。涵盖交互式调试器、基于ephemeral containers的容器调试，以及使用correlation IDs和分布式追踪的生产环境安全调试技术。

When to Use This Skill

何时使用该技能

Trigger this skill for:

Setting breakpoints in Python, Go, Rust, or Node.js code
Debugging running containers or Kubernetes pods
Setting up remote debugging connections
Safely debugging production issues
Inspecting goroutines, threads, or async tasks
Analyzing core dumps or stack traces
Choosing the right debugging tool for a scenario

在以下场景中使用该技能：

在Python、Go、Rust或Node.js代码中设置断点
调试运行中的容器或Kubernetes Pod
搭建远程调试连接
安全调试生产环境问题
检查goroutines、线程或异步任务
分析核心转储或堆栈跟踪
为特定场景选择合适的调试工具

Quick Reference by Language

按语言分类快速参考

Python Debugging

Python调试

Built-in: pdb

python

undefined

内置工具：pdb

python

undefined

Python 3.7+

def buggy_function(x, y): breakpoint() # Stops execution here return x / y

Older Python

import pdb pdb.set_trace()


**Essential pdb commands:**
- `list` (l) - Show code around current line
- `next` (n) - Execute current line, step over functions
- `step` (s) - Execute current line, step into functions
- `continue` (c) - Continue until next breakpoint
- `print var` (p) - Print variable value
- `where` (w) - Show stack trace
- `quit` (q) - Exit debugger

**Enhanced tools:**
- `ipdb` - Enhanced pdb with tab completion, syntax highlighting (`pip install ipdb`)
- `pudb` - Terminal GUI debugger (`pip install pudb`)
- `debugpy` - VS Code integration (included in Python extension)

**Debugging tests:**
```bash
pytest --pdb  # Drop into debugger on test failure

For detailed Python debugging patterns, see

references/python-debugging.md

import pdb pdb.set_trace()


**pdb核心命令：**
- `list` (l) - 显示当前行附近的代码
- `next` (n) - 执行当前行，步过函数
- `step` (s) - 执行当前行，步入函数
- `continue` (c) - 继续执行至下一个断点
- `print var` (p) - 打印变量值
- `where` (w) - 显示堆栈跟踪
- `quit` (q) - 退出调试器

**增强工具：**
- `ipdb` - 带自动补全和语法高亮的增强版pdb（`pip install ipdb`）
- `pudb` - 终端GUI调试器（`pip install pudb`）
- `debugpy` - 与VS Code集成（包含在Python扩展中）

**调试测试：**
```bash
pytest --pdb  # Drop into debugger on test failure

如需了解详细的Python调试模式，请参阅

references/python-debugging.md

。

Go Debugging

Go调试

Delve - Official Go debugger

Installation:

bash

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

Basic usage:

bash

dlv debug main.go              # Debug main package
dlv test github.com/me/pkg     # Debug test suite
dlv attach <pid>               # Attach to running process
dlv debug -- --config prod.yaml  # Pass arguments

Essential commands:

```
break main.main
```
(b) - Set breakpoint at function
```
break file.go:10
```
(b) - Set breakpoint at line
```
continue
```
(c) - Continue execution
```
next
```
(n) - Step over
```
step
```
(s) - Step into
```
print x
```
(p) - Print variable
```
goroutine
```
(gr) - Show current goroutine
```
goroutines
```
(grs) - List all goroutines
```
goroutines -t
```
- Show goroutine stacktraces
```
stack
```
(bt) - Show stack trace

Goroutine debugging:

bash

(dlv) goroutines                 # List all goroutines
(dlv) goroutines -t              # Show stacktraces
(dlv) goroutines -with user      # Filter user goroutines
(dlv) goroutine 5                # Switch to goroutine 5

For detailed Go debugging patterns, see

references/go-debugging.md

Delve - 官方Go调试器

安装方式：

bash

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

基本用法：

bash

dlv debug main.go              # Debug main package
dlv test github.com/me/pkg     # Debug test suite
dlv attach <pid>               # Attach to running process
dlv debug -- --config prod.yaml  # Pass arguments

核心命令：

```
break main.main
```
(b) - 在函数处设置断点
```
break file.go:10
```
(b) - 在指定行设置断点
```
continue
```
(c) - 继续执行
```
next
```
(n) - 步过
```
step
```
(s) - 步入
```
print x
```
(p) - 打印变量
```
goroutine
```
(gr) - 显示当前goroutine
```
goroutines
```
(grs) - 列出所有goroutines
```
goroutines -t
```
- 显示goroutine堆栈跟踪
```
stack
```
(bt) - 显示堆栈跟踪

Goroutine调试：

bash

(dlv) goroutines                 # List all goroutines
(dlv) goroutines -t              # Show stacktraces
(dlv) goroutines -with user      # Filter user goroutines
(dlv) goroutine 5                # Switch to goroutine 5

如需了解详细的Go调试模式，请参阅

references/go-debugging.md

。

Rust Debugging

Rust调试

LLDB - Default Rust debugger

Compilation:

bash

cargo build  # Debug build includes symbols by default

Usage:

bash

rust-lldb target/debug/myapp   # LLDB wrapper for Rust
rust-gdb target/debug/myapp    # GDB wrapper (alternative)

Essential LLDB commands:

```
breakpoint set -f main.rs -l 10
```
- Set breakpoint at line
```
breakpoint set -n main
```
- Set breakpoint at function
```
run
```
(r) - Start program
```
continue
```
(c) - Continue execution
```
next
```
(n) - Step over
```
step
```
(s) - Step into
```
print variable
```
(p) - Print variable
```
frame variable
```
(fr v) - Show local variables
```
backtrace
```
(bt) - Show stack trace
```
thread list
```
- List all threads

VS Code integration:

Install CodeLLDB extension (
```
vadimcn.vscode-lldb
```
)
Configure
```
launch.json
```
for Rust projects

For detailed Rust debugging patterns, see

references/rust-debugging.md

LLDB - 默认Rust调试器

编译：

bash

cargo build  # Debug build includes symbols by default

用法：

bash

rust-lldb target/debug/myapp   # LLDB wrapper for Rust
rust-gdb target/debug/myapp    # GDB wrapper (alternative)

LLDB核心命令：

```
breakpoint set -f main.rs -l 10
```
- 在指定行设置断点
```
breakpoint set -n main
```
- 在函数处设置断点
```
run
```
(r) - 启动程序
```
continue
```
(c) - 继续执行
```
next
```
(n) - 步过
```
step
```
(s) - 步入
```
print variable
```
(p) - 打印变量
```
frame variable
```
(fr v) - 显示局部变量
```
backtrace
```
(bt) - 显示堆栈跟踪
```
thread list
```
- 列出所有线程

VS Code集成：

安装CodeLLDB扩展（
```
vadimcn.vscode-lldb
```
）
为Rust项目配置
```
launch.json
```

如需了解详细的Rust调试模式，请参阅

references/rust-debugging.md

。

Node.js Debugging

Node.js调试

Built-in: node --inspect

Basic usage:

bash

node --inspect-brk app.js       # Start and pause immediately
node --inspect app.js           # Start and run
node --inspect=0.0.0.0:9229 app.js  # Specify host/port

Chrome DevTools:

Open
```
chrome://inspect
```
Click "Open dedicated DevTools for Node"
Set breakpoints, inspect variables

VS Code integration: Configure

launch.json

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js"
}

Docker debugging:

dockerfile

EXPOSE 9229
CMD ["node", "--inspect=0.0.0.0:9229", "app.js"]

For detailed Node.js debugging patterns, see

references/nodejs-debugging.md

内置工具：node --inspect

基本用法：

bash

node --inspect-brk app.js       # Start and pause immediately
node --inspect app.js           # Start and run
node --inspect=0.0.0.0:9229 app.js  # Specify host/port

Chrome DevTools：

打开
```
chrome://inspect
```
点击"Open dedicated DevTools for Node"
设置断点、检查变量

VS Code集成： 配置

launch.json

json

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js"
}

Docker调试：

dockerfile

EXPOSE 9229
CMD ["node", "--inspect=0.0.0.0:9229", "app.js"]

如需了解详细的Node.js调试模式，请参阅

references/nodejs-debugging.md

。

Container & Kubernetes Debugging

容器与Kubernetes调试

kubectl debug with Ephemeral Containers

使用Ephemeral Containers进行kubectl debug

When to use:

Container has crashed (kubectl exec won't work)
Using distroless/minimal image (no shell, no tools)
Need debugging tools without rebuilding image
Debugging network issues

Basic usage:

bash

undefined

适用场景：

容器已崩溃（kubectl exec无法使用）
使用无发行版/极简镜像（无Shell、无工具）
无需重新构建镜像即可使用调试工具
调试网络问题

基本用法：

bash

undefined

Add ephemeral debugging container

kubectl debug -it <pod-name> --image=nicolaka/netshoot

Share process namespace (see other container processes)

kubectl debug -it <pod-name> --image=busybox --share-processes

Target specific container

kubectl debug -it <pod-name> --image=busybox --target=app


**Recommended debugging images:**
- `nicolaka/netshoot` (~380MB) - Network debugging (curl, dig, tcpdump, netstat)
- `busybox` (~1MB) - Minimal shell and utilities
- `alpine` (~5MB) - Lightweight with package manager
- `ubuntu` (~70MB) - Full environment

**Node debugging:**
```bash
kubectl debug node/<node-name> -it --image=ubuntu

Docker container debugging:

bash

docker exec -it <container-id> sh

kubectl debug -it <pod-name> --image=busybox --target=app


**推荐调试镜像：**
- `nicolaka/netshoot` (~380MB) - 网络调试工具（包含curl、dig、tcpdump、netstat）
- `busybox` (~1MB) - 极简Shell及工具集
- `alpine` (~5MB) - 轻量级镜像，带包管理器
- `ubuntu` (~70MB) - 完整运行环境

**节点调试：**
```bash
kubectl debug node/<node-name> -it --image=ubuntu

Docker容器调试：

bash

docker exec -it <container-id> sh

If no shell available

docker run -it --pid=container:<container-id>
--net=container:<container-id>
busybox sh


For detailed container debugging patterns, see `references/container-debugging.md`.

docker run -it --pid=container:<container-id>
--net=container:<container-id>
busybox sh


如需了解详细的容器调试模式，请参阅`references/container-debugging.md`。

Production Debugging

生产环境调试

Production Debugging Principles

生产环境调试原则

Golden rules:

Minimal performance impact - Profile overhead, limit scope
No blocking operations - Use non-breaking techniques
Security-aware - Avoid logging secrets, PII
Reversible - Can roll back quickly (feature flags, Git)
Observable - Structured logging, correlation IDs, tracing

黄金准则：

最小性能影响 - 分析开销，限制范围
无阻塞操作 - 使用非中断技术
安全优先 - 避免记录敏感信息、个人可识别信息（PII）
可回滚 - 可快速回退（功能开关、Git）
可观测 - 结构化日志、correlation IDs、追踪

Safe Production Techniques

生产环境安全调试技术

1. Structured Logging

python

import logging
import json

logger = logging.getLogger(__name__)
logger.info(json.dumps({
    "event": "user_login_failed",
    "user_id": user_id,
    "error": str(e),
    "correlation_id": request_id
}))

2. Correlation IDs (Request Tracing)

func handleRequest(w http.ResponseWriter, r *http.Request) {
    correlationID := r.Header.Get("X-Correlation-ID")
    if correlationID == "" {
        correlationID = generateUUID()
    }
    ctx := context.WithValue(r.Context(), "correlationID", correlationID)
    log.Printf("[%s] Processing request", correlationID)
}

3. Distributed Tracing (OpenTelemetry)

python

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def process_order(order_id):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.id", order_id)
        span.add_event("Order validated")

4. Error Tracking Platforms

Sentry - Exception tracking with context
New Relic - APM with error tracking
Datadog - Logs, metrics, traces
Rollbar - Error monitoring

Production debugging workflow:

Detect - Error tracking alert, log spike, metric anomaly
Locate - Find correlation ID, search logs, view distributed trace
Reproduce - Try to reproduce in staging with production data (sanitized)
Fix - Create feature flag, deploy to canary first
Verify - Check error rates, review logs, monitor traces

For detailed production debugging patterns, see

references/production-debugging.md

1. 结构化日志

python

import logging
import json

logger = logging.getLogger(__name__)
logger.info(json.dumps({
    "event": "user_login_failed",
    "user_id": user_id,
    "error": str(e),
    "correlation_id": request_id
}))

2. Correlation IDs（请求追踪）

func handleRequest(w http.ResponseWriter, r *http.Request) {
    correlationID := r.Header.Get("X-Correlation-ID")
    if correlationID == "" {
        correlationID = generateUUID()
    }
    ctx := context.WithValue(r.Context(), "correlationID", correlationID)
    log.Printf("[%s] Processing request", correlationID)
}

3. 分布式追踪（OpenTelemetry）

python

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

def process_order(order_id):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.id", order_id)
        span.add_event("Order validated")

4. 错误追踪平台

Sentry - 带上下文的异常追踪
New Relic - 包含错误追踪的APM工具
Datadog - 日志、指标、追踪一体化平台
Rollbar - 错误监控工具

生产环境调试工作流：

检测 - 错误追踪告警、日志激增、指标异常
定位 - 查找correlation ID、搜索日志、查看分布式追踪链路
复现 - 使用脱敏后的生产数据在预发布环境复现问题
修复 - 创建功能开关，先部署到金丝雀环境
验证 - 检查错误率、查看日志、监控追踪链路

如需了解详细的生产环境调试模式，请参阅

references/production-debugging.md

。

Decision Framework

决策框架

Which Debugger for Which Language?

各语言对应的调试器？

Language	Primary Tool	Installation	Best For
Python	pdb	Built-in	Simple scripts, server environments
	ipdb	`pip install ipdb`	Enhanced UX, IPython users
	debugpy	VS Code extension	IDE integration, remote debugging
Go	delve	`go install github.com/go-delve/delve/cmd/dlv@latest`	All Go debugging, goroutines
Rust	rust-lldb	System package	Mac, Linux, MSVC Windows
	rust-gdb	System package	Linux, prefer GDB
Node.js	node --inspect	Built-in	All Node.js debugging, Chrome DevTools

编程语言	主要工具	安装方式	最佳适用场景
Python	pdb	内置	简单脚本、服务器环境
	ipdb	`pip install ipdb`	增强交互体验、IPython用户
	debugpy	VS Code扩展	IDE集成、远程调试
Go	delve	`go install github.com/go-delve/delve/cmd/dlv@latest`	所有Go调试场景、goroutine调试
Rust	rust-lldb	系统包管理器安装	Mac、Linux、MSVC Windows环境
	rust-gdb	系统包管理器安装	Linux环境、偏好GDB的用户
Node.js	node --inspect	内置	所有Node.js调试场景、Chrome DevTools集成

Which Technique for Which Scenario?

各场景对应的调试技术？

Scenario	Recommended Technique	Tools
Local development	Interactive debugger	pdb, delve, lldb, node --inspect
Bug in test	Test-specific debugging	pytest --pdb, dlv test, cargo test
Remote server	SSH tunnel + remote attach	VS Code Remote, debugpy
Container (local)	docker exec -it	sh/bash + debugger
Kubernetes pod	Ephemeral container	kubectl debug --image=nicolaka/netshoot
Distroless image	Ephemeral container (required)	kubectl debug with busybox/alpine
Production issue	Log analysis + error tracking	Structured logs, Sentry, correlation IDs
Goroutine deadlock	Goroutine inspection	delve goroutines -t
Crashed process	Core dump analysis	gdb core, lldb -c core
Distributed failure	Distributed tracing	OpenTelemetry, Jaeger, correlation IDs
Race condition	Race detector + debugger	go run -race, cargo test

场景	推荐技术	工具
本地开发	交互式调试器	pdb, delve, lldb, node --inspect
测试用例失败	测试专属调试	pytest --pdb, dlv test, cargo test
远程服务器	SSH隧道+远程附加	VS Code Remote, debugpy
本地容器	docker exec -it	sh/bash + 调试器
Kubernetes Pod	Ephemeral容器	kubectl debug --image=nicolaka/netshoot
无发行版镜像	Ephemeral容器（必需）	kubectl debug结合busybox/alpine
生产环境问题	日志分析+错误追踪	结构化日志、Sentry、correlation IDs
Goroutine死锁	Goroutine检查	delve goroutines -t
进程崩溃	核心转储分析	gdb core, lldb -c core
分布式故障	分布式追踪	OpenTelemetry, Jaeger, correlation IDs
竞态条件	竞态检测器+调试器	go run -race, cargo test

Production Debugging Safety Checklist

生产环境调试安全检查表

Common Debugging Workflows

常见调试工作流

Workflow 1: Local Development Bug

工作流1：本地开发Bug调试

Insert breakpoint in code (language-specific)
Start debugger (dlv debug, rust-lldb, node --inspect-brk)
Execute to breakpoint (run, continue)
Inspect variables (print, frame variable)
Step through code (next, step, finish)
Identify issue and fix

插入断点到代码中（对应编程语言的方式）
启动调试器（dlv debug、rust-lldb、node --inspect-brk）
执行至断点（run、continue）
检查变量（print、frame variable）
逐步执行代码（next、step、finish）
定位问题并修复

Workflow 2: Test Failure Debugging

工作流2：测试失败调试

Python:

bash

pytest --pdb  # Drops into pdb on failure

Go:

bash

dlv test github.com/user/project/pkg
(dlv) break TestMyFunction
(dlv) continue

Rust:

bash

cargo test --no-run
rust-lldb target/debug/deps/myapp-<hash>
(lldb) breakpoint set -n test_name
(lldb) run test_name

Python：

bash

pytest --pdb  # Drops into pdb on failure

Go：

bash

dlv test github.com/user/project/pkg
(dlv) break TestMyFunction
(dlv) continue

Rust：

bash

cargo test --no-run
rust-lldb target/debug/deps/myapp-<hash>
(lldb) breakpoint set -n test_name
(lldb) run test_name

Workflow 3: Kubernetes Pod Debugging

工作流3：Kubernetes Pod调试

Scenario: Pod with distroless image, network issue

bash

undefined

场景：使用无发行版镜像的Pod出现网络问题

bash

undefined

Step 1: Check pod status

步骤1：检查Pod状态

kubectl get pod my-app-pod -o wide

Step 2: Check logs first

步骤2：先查看日志

kubectl logs my-app-pod

Step 3: Add ephemeral container if logs insufficient

步骤3：若日志不足，添加临时调试容器

kubectl debug -it my-app-pod --image=nicolaka/netshoot

Step 4: Inside debug container, investigate

步骤4：在调试容器内排查问题

curl localhost:8080 netstat -tuln nslookup api.example.com

undefined

curl localhost:8080 netstat -tuln nslookup api.example.com

undefined

Workflow 4: Production Error Investigation

工作流4：生产环境错误排查

Scenario: API returning 500 errors

bash

undefined

场景：API返回500错误

bash

undefined

Step 1: Check error tracking (Sentry)

步骤1：查看错误追踪平台（Sentry）

- Find error details, stack trace

- 查找错误详情、堆栈跟踪

- Copy correlation ID from error report

- 从错误报告中复制correlation ID

Step 2: Search logs for correlation ID

步骤2：根据correlation ID搜索日志

In log aggregation tool (ELK, Splunk):

在日志聚合工具（ELK、Splunk）中搜索：

correlation_id:"abc-123-def"

Step 3: View distributed trace

步骤3：查看分布式追踪链路

In tracing tool (Jaeger, Datadog):

在追踪工具（Jaeger、Datadog）中：

Search by correlation ID, review span timeline

根据correlation ID搜索，查看Span时间线

Step 4: Reproduce in staging

步骤4：在预发布环境复现

Use production data (sanitized) if needed

如需，使用脱敏后的生产数据

Add additional logging if needed

如需，添加额外日志

Step 5: Fix and deploy

步骤5：修复并部署

Create feature flag for gradual rollout

创建功能开关用于灰度发布

Deploy to canary environment first

先部署到金丝雀环境

Monitor error rates closely

密切监控错误率

undefined

undefined

Additional Resources

额外资源

For language-specific deep dives:

```
references/python-debugging.md
```
- pdb, ipdb, pudb, debugpy detailed guide
```
references/go-debugging.md
```
- Delve CLI, goroutine debugging, conditional breakpoints
```
references/rust-debugging.md
```
- LLDB vs GDB, ownership debugging, macro debugging
```
references/nodejs-debugging.md
```
- node --inspect, Chrome DevTools, Docker debugging

For environment-specific patterns:

```
references/container-debugging.md
```
- kubectl debug, ephemeral containers, node debugging
```
references/production-debugging.md
```
- Structured logging, correlation IDs, OpenTelemetry, error tracking

For decision support:

```
references/decision-trees.md
```
- Expanded debugging decision frameworks

For hands-on examples:

```
examples/
```
- Step-by-step debugging sessions for each language

针对各语言的深度指南：

```
references/python-debugging.md
```
- pdb、ipdb、pudb、debugpy详细指南
```
references/go-debugging.md
```
- Delve命令行、goroutine调试、条件断点
```
references/rust-debugging.md
```
- LLDB vs GDB、所有权调试、宏调试
```
references/nodejs-debugging.md
```
- node --inspect、Chrome DevTools、Docker调试

针对各环境的调试模式：

```
references/container-debugging.md
```
- kubectl debug、ephemeral containers、节点调试
```
references/production-debugging.md
```
- 结构化日志、correlation IDs、OpenTelemetry、错误追踪

针对决策支持：

```
references/decision-trees.md
```
- 扩展版调试决策框架

针对实操示例：

```
examples/
```
- 各语言的分步调试会话示例