nginx-c-module-debug

name	nginx-c-module-debug
description	nginx C module debugging guidelines based on the official nginx development guide. This skill should be used when debugging nginx C module crashes, memory bugs, request flow issues, or production problems. Triggers on tasks involving segfault analysis, coredump debugging, GDB inspection, memory leak detection, request phase tracing, AddressSanitizer setup, or nginx module troubleshooting.

nginx.org C Module Debugging Best Practices

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.

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

Rule Categories by Priority

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-

Quick Reference

1. Crash Diagnosis & Signals (CRITICAL)

• 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

2. Memory Bug Detection (CRITICAL)

• 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

3. GDB & Core Dump Analysis (HIGH)

• 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

4. Request Flow Tracing (HIGH)

• 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

5. Debug Logging Patterns (MEDIUM-HIGH)

• 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

6. State & Lifecycle Debugging (MEDIUM)

• 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

7. Dynamic Tracing Tools (MEDIUM)

• 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

8. Build & Sanitizer Configuration (LOW-MEDIUM)

• 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

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