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