Agent Skills: nginx.org C Module Performance & Reliability Best Practices

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-modules 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

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Buffer & Zero-Copy I/O | CRITICAL | buf- | | 2 | Connection Efficiency | CRITICAL | conn- | | 3 | Lock Contention & Atomics | HIGH | lock- | | 4 | Error Recovery & Resilience | HIGH | err- | | 5 | Timeout & Retry Strategy | MEDIUM-HIGH | timeout- | | 6 | Response Caching | MEDIUM | cache- | | 7 | Worker & Process Tuning | MEDIUM | worker- | | 8 | Logging & Metrics | LOW-MEDIUM | log- |

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

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