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

buf-

conn-

lock-

err-

timeout-

cache-

worker-

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