nginx.org C Module Performance & Reliability Best Practices

Comprehensive performance optimization and reliability guide for nginx C modules, derived from the official nginx development documentation and production engineering experience. Contains 43 rules across 8 categories, prioritized by impact to guide automated optimization and resilience improvements.

Companion skill: This skill complements nginx-c-module-best-practices which covers correctness (memory safety, request lifecycle, configuration). This skill covers performance optimization and operational reliability.

When to Apply

Reference these guidelines when:

• Optimizing nginx C module throughput and latency
• Reducing buffer copies and enabling zero-copy I/O paths
• Tuning connection pooling and socket options
• Minimizing shared memory lock contention across workers
• Implementing graceful error recovery and fallback responses
• Configuring upstream timeouts and retry strategies
• Building in-module response caches with shared memory
• Tuning worker process behavior under load

Rule Categories by Priority

Quick Reference

1. Buffer & Zero-Copy I/O (CRITICAL)

• buf-chain-reuse – Reuse Buffer Chain Links Instead of Allocating New Ones
• buf-file-sendfile – Use File Buffers for Static Content Instead of Reading into Memory
• buf-avoid-copy – Avoid Copying Buffers When Passing Through Filter Chain
• buf-coalesce-small – Coalesce Small Buffers Before Output
• buf-shadow-reference – Use Shadow Buffers for Derived Data Instead of Full Copies
• buf-recycled-flag – Mark Buffers as Recycled for Upstream Response Reuse

2. Connection Efficiency (CRITICAL)

• conn-reusable-queue – Mark Idle Connections as Reusable for Pool Recovery
• conn-drain-pressure – Handle Connection Drain Under Memory Pressure
• conn-tcp-nodelay – Control TCP_NODELAY for Latency-Sensitive Responses
• conn-prealloc-pool – Size Connection Pool to Avoid Runtime Reallocation
• conn-close-linger – Use Lingering Close for Graceful Connection Shutdown
• conn-ssl-session-reuse – Enable SSL Session Caching in Upstream Connections

3. Lock Contention & Atomics (HIGH)

• lock-minimize-critical – Minimize Critical Section Duration in Shared Memory
• lock-atomic-counters – Use Atomic Operations for Simple Counters Instead of Mutex
• lock-trylock-fallback – Use ngx_shmtx_trylock with Fallback to Avoid Worker Stalls
• lock-per-worker-aggregate – Aggregate Per-Worker Counters to Reduce Shared Memory Access
• lock-alloc-outside – Perform Slab Allocation Outside Hot Path
• lock-rw-pattern – Use Read-Copy-Update Pattern for Read-Heavy Shared Data

4. Error Recovery & Resilience (HIGH)

• err-cache-errno – Cache ngx_errno Immediately to Prevent Overwrite
• err-fallback-response – Return Fallback Response When Upstream Fails
• err-resource-exhaustion – Handle Pool and Slab Allocation Exhaustion Gracefully
• err-blocked-counter – Use Blocked Counter to Prevent Premature Request Destruction
• err-connection-error-check – Check Connection Error Flag Before I/O Operations
• err-log-once-pattern – Limit Repeated Error Logging to Prevent Log Storms

5. Timeout & Retry Strategy (MEDIUM-HIGH)

• timeout-upstream-phases – Set Separate Timeouts for Connect, Send, and Read Phases
• timeout-retry-next-upstream – Configure next_upstream Mask for Retriable Failures
• timeout-backoff-reconnect – Use Exponential Backoff for Upstream Reconnection Attempts
• timeout-client-body-limit – Set Client Body Timeout to Bound Slow-Client Resource Usage

6. Response Caching (MEDIUM)

• cache-shm-lru – Implement LRU Eviction in Shared Memory Cache Zones
• cache-stampede-lock – Prevent Cache Stampede with Single-Flight Pattern
• cache-key-hash – Use ngx_hash for Fixed Cache Key Lookups
• cache-ttl-atomic – Use Atomic Timestamp Comparison for TTL Expiry Checks
• cache-conditional-store – Cache Only Successful Responses to Avoid Negative Cache Pollution

7. Worker & Process Tuning (MEDIUM)

• worker-accept-mutex – Understand Accept Mutex Impact on Connection Distribution
• worker-connection-prealloc – Use Pre-Allocated Free List for Module Data Structures
• worker-graceful-shutdown – Handle Worker Shutdown Signal Without Data Loss
• worker-single-process-debug – Support Single-Process Mode for Debugging
• worker-cycle-conf – Access Configuration Through Cycle for Process-Level Operations

8. Logging & Metrics (LOW-MEDIUM)

• log-level-guard – Guard Expensive Debug Argument Computation Behind Level Check
• log-connection-context – Attach Module Context to Connection Log for Tracing
• log-shared-metrics – Collect Metrics via Shared Memory Counters
• log-error-dedup – Deduplicate Repeated Error Messages with Throttling
• log-action-string – Set Log Action String for Operation Context

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