nginx-c-module-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

nginx.org C Module Debugging Best Practices

nginx.org C模块调试最佳实践

Comprehensive debugging guide for nginx C modules, derived from the official nginx development documentation and production debugging experience. Contains 45 rules across 8 categories, prioritized by impact to guide systematic diagnosis of crashes, memory bugs, and behavioral issues in nginx modules.

Companion skills: This skill complements nginx-c-modules (correctness) and nginx-c-module-perf-reliability (performance). This skill covers debugging and diagnosis.

本指南是基于官方nginx开发文档和生产环境调试经验整理的nginx C模块综合调试指南。包含8个类别共45条规则，按影响优先级排序，指导你系统性诊断nginx模块中的崩溃、内存bug和行为异常问题。

配套技能：本技能与nginx-c-modules（正确性相关）和nginx-c-module-perf-reliability（性能相关）互为补充，专注于调试与诊断。

When to Apply

适用场景

Reference these guidelines when:

Diagnosing nginx worker crashes (segfaults, SIGABRT, SIGSEGV)
Finding memory bugs (use-after-free, leaks, pool corruption, buffer overruns)
Setting up GDB and core dump analysis for nginx
Tracing request flow through phases, subrequests, and filter chains
Instrumenting nginx modules with debug logging and dynamic tracing tools

在以下场景中参考本指南：

诊断nginx worker进程崩溃（段错误、SIGABRT、SIGSEGV）
排查内存bug（释放后使用、内存泄漏、内存池损坏、缓冲区溢出）
为nginx配置GDB和核心转储分析环境
追踪请求在各阶段、子请求和过滤链中的流转过程
使用调试日志和动态追踪工具为nginx模块插桩

Rule Categories by Priority

按优先级划分的规则类别


crash-
memdbg-
gdb-
trace-
dbglog-
state-
probe-
build-

Priority	Category	Impact	Prefix
1	Crash Diagnosis & Signals	CRITICAL	`crash-`
2	Memory Bug Detection	CRITICAL	`memdbg-`
3	GDB & Core Dump Analysis	HIGH	`gdb-`
4	Request Flow Tracing	HIGH	`trace-`
5	Debug Logging Patterns	MEDIUM-HIGH	`dbglog-`
6	State & Lifecycle Debugging	MEDIUM	`state-`
7	Dynamic Tracing Tools	MEDIUM	`probe-`
8	Build & Sanitizer Configuration	LOW-MEDIUM	`build-`


crash-
memdbg-
gdb-
trace-
dbglog-
state-
probe-
build-

优先级	类别	影响级别	前缀
1	崩溃诊断与信号处理	关键	`crash-`
2	内存bug检测	关键	`memdbg-`
3	GDB与核心转储分析	高	`gdb-`
4	请求流追踪	高	`trace-`
5	调试日志模式	中高	`dbglog-`
6	状态与生命周期调试	中	`state-`
7	动态追踪工具	中	`probe-`
8	构建与Sanitizer配置	中低	`build-`

Quick Reference

快速参考

1. Crash Diagnosis & Signals (CRITICAL)

1. 崩溃诊断与信号处理（关键）

```
crash-segfault-signature
```
- Identify Segfault Crash Signature from Signal and Address
```
crash-null-deref-pattern
```
- Recognize NULL Pointer Dereference Patterns in nginx Modules
```
crash-double-free-finalize
```
- Diagnose Double Finalize Crashes from Request Reference Count
```
crash-stack-overflow
```
- Detect Stack Overflow from Recursive Subrequest or Filter Chains
```
crash-worker-exit-log
```
- Extract Crash Context from Worker Exit Log Messages
```
crash-error-page-redirect
```
- Avoid Crashes from error_page Internal Redirect Context Invalidation

```
crash-segfault-signature
```
- 从信号和地址中识别段错误崩溃特征
```
crash-null-deref-pattern
```
- 识别nginx模块中的空指针解引用模式
```
crash-double-free-finalize
```
- 从请求引用计数诊断重复释放/重复终止导致的崩溃
```
crash-stack-overflow
```
- 检测由递归子请求或过滤链导致的栈溢出
```
crash-worker-exit-log
```
- 从worker进程退出日志中提取崩溃上下文
```
crash-error-page-redirect
```
- 避免因error_page内部重定向上下文失效导致的崩溃

2. Memory Bug Detection (CRITICAL)

2. 内存bug检测（关键）

```
memdbg-use-after-free
```
- Detect Use-After-Free from Pool Destruction Timing
```
memdbg-pool-leak-pattern
```
- Identify Pool Memory Leak Patterns from Growing Worker RSS
```
memdbg-slab-corruption
```
- Diagnose Shared Memory Slab Corruption from Multi-Worker Crashes
```
memdbg-cleanup-handler-leak
```
- Detect Resource Leaks from Missing Pool Cleanup Handlers
```
memdbg-buffer-overrun
```
- Find Buffer Overrun from ngx_pnalloc Size Miscalculation
```
memdbg-temp-pool-misuse
```
- Avoid Storing Long-Lived Pointers in Temporary Pools
```
memdbg-valgrind-pool-trace
```
- Use Valgrind Pool-Level Tracing to Find Leaked Allocations

```
memdbg-use-after-free
```
- 从内存池销毁时机检测释放后使用问题
```
memdbg-pool-leak-pattern
```
- 从worker进程RSS增长识别内存池泄漏模式
```
memdbg-slab-corruption
```
- 从多worker进程崩溃诊断共享内存slab损坏问题
```
memdbg-cleanup-handler-leak
```
- 检测因缺失内存池清理处理器导致的资源泄漏
```
memdbg-buffer-overrun
```
- 从ngx_pnalloc大小计算错误排查缓冲区溢出问题
```
memdbg-temp-pool-misuse
```
- 避免在临时内存池中存储长生命周期指针
```
memdbg-valgrind-pool-trace
```
- 使用Valgrind内存池级别追踪查找泄漏的内存分配

3. GDB & Core Dump Analysis (HIGH)

3. GDB与核心转储分析（高）

```
gdb-coredump-setup
```
- Configure Core Dump Generation for nginx Worker Crashes
```
gdb-attach-worker
```
- Attach GDB to a Running nginx Worker Process
```
gdb-backtrace-read
```
- Read nginx Backtrace to Identify Crash Module and Phase
```
gdb-inspect-request
```
- Inspect ngx_http_request_t Fields in GDB for Request State
```
gdb-memory-buffer-extract
```
- Extract Debug Log from Memory Buffer Using GDB Script
```
gdb-watchpoint-corruption
```
- Use GDB Watchpoints to Catch Memory Corruption at Write Time

```
gdb-coredump-setup
```
- 为nginx worker进程崩溃配置核心转储生成
```
gdb-attach-worker
```
- 将GDB附加到运行中的nginx worker进程
```
gdb-backtrace-read
```
- 读取nginx回溯信息识别崩溃模块和阶段
```
gdb-inspect-request
```
- 在GDB中查看ngx_http_request_t字段获取请求状态
```
gdb-memory-buffer-extract
```
- 使用GDB脚本从内存缓冲区提取调试日志
```
gdb-watchpoint-corruption
```
- 使用GDB观察点在写入时捕获内存损坏

4. Request Flow Tracing (HIGH)

4. 请求流追踪（高）

```
trace-phase-handler-flow
```
- Trace Request Through HTTP Phase Handlers
```
trace-subrequest-tree
```
- Map Subrequest Parent-Child Relationships for Debugging
```
trace-filter-chain-order
```
- Trace Filter Chain Execution Order and Data Flow
```
trace-upstream-callback-seq
```
- Trace Upstream Callback Sequence for Proxy Debugging
```
trace-event-handler-chain
```
- Trace Event Handler Execution for Connection Debugging
```
trace-config-inheritance
```
- Trace Configuration Inheritance Through Server and Location Blocks

```
trace-phase-handler-flow
```
- 追踪请求在HTTP阶段处理器中的流转
```
trace-subrequest-tree
```
- 绘制子请求父子关系图用于调试
```
trace-filter-chain-order
```
- 追踪过滤链执行顺序和数据流
```
trace-upstream-callback-seq
```
- 追踪上游回调序列用于代理调试
```
trace-event-handler-chain
```
- 追踪事件处理器执行过程用于连接调试
```
trace-config-inheritance
```
- 追踪配置在Server和Location块中的继承关系

5. Debug Logging Patterns (MEDIUM-HIGH)

5. 调试日志模式（中高）

```
dbglog-debug-mask
```
- Use Correct Debug Mask for Targeted Log Filtering
```
dbglog-debug-connection
```
- Use debug_connection to Isolate Single-Client Debug Output
```
dbglog-memory-buffer
```
- Use Memory Buffer Logging to Capture Debug Output Without Disk I/O
```
dbglog-log-action-string
```
- Set Log Action String for Context in Error Messages
```
dbglog-format-ngx-str
```
- Format ngx_str_t Correctly in Debug Log Messages

```
dbglog-debug-mask
```
- 使用正确的调试掩码实现定向日志过滤
```
dbglog-debug-connection
```
- 使用debug_connection隔离单客户端调试输出
```
dbglog-memory-buffer
```
- 使用内存缓冲区日志捕获调试输出，避免磁盘I/O影响
```
dbglog-log-action-string
```
- 设置日志操作字符串为错误消息添加上下文
```
dbglog-format-ngx-str
```
- 在调试日志中正确格式化ngx_str_t类型

6. State & Lifecycle Debugging (MEDIUM)

6. 状态与生命周期调试（中）

```
state-connection-lifecycle
```
- Track Connection State Transitions for Lifecycle Debugging
```
state-upstream-state-machine
```
- Debug Upstream Module State by Logging Transition Points
```
state-timer-leak
```
- Detect Timer Leaks from Events Not Removed Before Pool Destruction
```
state-event-flag-debug
```
- Inspect Event Flags to Debug Unexpected Handler Invocation
```
state-request-count-track
```
- Track Request Reference Count to Debug Premature Destruction

```
state-connection-lifecycle
```
- 跟踪连接状态转换用于生命周期调试
```
state-upstream-state-machine
```
- 通过记录转换点调试上游模块状态
```
state-timer-leak
```
- 检测因内存池销毁前未移除事件导致的定时器泄漏
```
state-event-flag-debug
```
- 查看事件标志调试意外的处理器调用
```
state-request-count-track
```
- 跟踪请求引用计数调试提前销毁问题

7. Dynamic Tracing Tools (MEDIUM)

7. 动态追踪工具（中）

```
probe-strace-syscall
```
- Use strace to Trace System Call Patterns in nginx Workers
```
probe-dtrace-request
```
- Trace Request Processing with DTrace pid Provider
```
probe-systemtap-pool
```
- Trace Memory Pool Allocations with SystemTap
```
probe-ebpf-latency
```
- Measure Per-Function Latency with eBPF Probes
```
probe-strace-fd-leak
```
- Detect File Descriptor Leaks with strace and /proc

```
probe-strace-syscall
```
- 使用strace追踪nginx worker进程的系统调用模式
```
probe-dtrace-request
```
- 使用DTrace pid提供者追踪请求处理过程
```
probe-systemtap-pool
```
- 使用SystemTap追踪内存池分配
```
probe-ebpf-latency
```
- 使用eBPF探针测量函数级延迟
```
probe-strace-fd-leak
```
- 使用strace和/proc检测文件描述符泄漏

8. Build & Sanitizer Configuration (LOW-MEDIUM)

8. 构建与Sanitizer配置（中低）

```
build-debug-flags
```
- Compile nginx with Full Debug Symbols and No Optimization
```
build-asan-configure
```
- Build nginx with AddressSanitizer for Memory Error Detection
```
build-single-process
```
- Use Single-Process Mode for Simplified Debugging
```
build-valgrind-suppressions
```
- Use nginx Valgrind Suppressions to Reduce False Positives
```
build-debug-palloc
```
- Enable NGX_DEBUG_PALLOC for Fine-Grained Pool Allocation Tracking

```
build-debug-flags
```
- 编译nginx时启用完整调试符号并关闭优化
```
build-asan-configure
```
- 构建带AddressSanitizer的nginx用于内存错误检测
```
build-single-process
```
- 使用单进程模式简化调试
```
build-valgrind-suppressions
```
- 使用nginx Valgrind抑制规则减少误报
```
build-debug-palloc
```
- 启用NGX_DEBUG_PALLOC实现细粒度内存池分配追踪

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构与影响级别说明
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序规则
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息