nginx-c-module-perf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

nginx.org C Module Performance & Reliability Best Practices

Nginx官方C模块性能与可靠性最佳实践

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.

本指南是基于Nginx官方开发文档和生产工程经验整理的Nginx C模块全面性能优化与可靠性指南，包含8个类别共43条规则，按影响优先级排序，可指导自动化优化与弹性提升。

配套技能：本技能是nginx-c-modules（涵盖内存安全、请求生命周期、配置等正确性相关内容）的补充，专注于性能优化与运行可靠性。

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

在以下场景中可参考本指南：

优化Nginx C模块的吞吐量与延迟
减少缓冲区拷贝并启用零拷贝I/O路径
调优连接池与套接字选项
降低工作进程间的共享内存锁竞争
实现优雅的错误恢复与降级响应
配置上游服务超时与重试策略
在模块内基于共享内存构建响应缓存
调优高负载下的工作进程行为

Rule Categories by Priority

按优先级划分的规则类别


buf-
conn-
lock-
err-
timeout-
cache-
worker-
log-

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


buf-
conn-
lock-
err-
timeout-
cache-
worker-
log-

优先级	类别	影响程度	前缀
1	缓冲区与零拷贝I/O	关键	`buf-`
2	连接效率	关键	`conn-`
3	锁竞争与原子操作	高	`lock-`
4	错误恢复与弹性	高	`err-`
5	超时与重试策略	中高	`timeout-`
6	响应缓存	中	`cache-`
7	工作进程调优	中	`worker-`
8	日志与指标	中低	`log-`

Quick Reference

快速参考

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

1. 缓冲区与零拷贝I/O（关键）

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

```
buf-chain-reuse
```
- 复用缓冲区链节点而非分配新节点
```
buf-file-sendfile
```
- 针对静态内容使用文件缓冲区而非读取到内存
```
buf-avoid-copy
```
- 在过滤器链传递时避免拷贝缓冲区
```
buf-coalesce-small
```
- 输出前合并小缓冲区
```
buf-shadow-reference
```
- 使用影子缓冲区存储派生数据而非完整拷贝
```
buf-recycled-flag
```
- 标记缓冲区为可回收以复用上游响应

2. Connection Efficiency (CRITICAL)

2. 连接效率（关键）

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

```
conn-reusable-queue
```
- 将空闲连接标记为可复用以便连接池回收
```
conn-drain-pressure
```
- 在内存压力下处理连接释放
```
conn-tcp-nodelay
```
- 针对延迟敏感型响应控制TCP_NODELAY
```
conn-prealloc-pool
```
- 预分配连接池大小以避免运行时重新分配
```
conn-close-linger
```
- 使用 linger 关闭实现优雅的连接终止
```
conn-ssl-session-reuse
```
- 在上游连接中启用SSL会话缓存

3. Lock Contention & Atomics (HIGH)

3. 锁竞争与原子操作（高）

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

```
lock-minimize-critical
```
- 减少共享内存中的临界区时长
```
lock-atomic-counters
```
- 对简单计数器使用原子操作而非互斥锁
```
lock-trylock-fallback
```
- 使用ngx_shmtx_trylock并配置降级策略以避免工作进程停滞
```
lock-per-worker-aggregate
```
- 聚合每个工作进程的计数器以减少共享内存访问
```
lock-alloc-outside
```
- 在热点路径外执行Slab分配
```
lock-rw-pattern
```
- 针对读密集型共享数据使用读-拷贝-更新模式

4. Error Recovery & Resilience (HIGH)

4. 错误恢复与弹性（高）

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

```
err-cache-errno
```
- 立即缓存ngx_errno以防止被覆盖
```
err-fallback-response
```
- 上游服务故障时返回降级响应
```
err-resource-exhaustion
```
- 优雅处理连接池与Slab分配耗尽的情况
```
err-blocked-counter
```
- 使用阻塞计数器防止请求被过早销毁
```
err-connection-error-check
```
- I/O操作前检查连接错误标记
```
err-log-once-pattern
```
- 限制重复错误日志输出以避免日志风暴

5. Timeout & Retry Strategy (MEDIUM-HIGH)

5. 超时与重试策略（中高）

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

```
timeout-upstream-phases
```
- 为连接、发送、读取阶段分别设置超时
```
timeout-retry-next-upstream
```
- 配置next_upstream掩码以定义可重试的故障类型
```
timeout-backoff-reconnect
```
- 对重连尝试使用指数退避策略
```
timeout-client-body-limit
```
- 设置客户端请求体超时以限制慢客户端的资源占用

6. Response Caching (MEDIUM)

6. 响应缓存（中）

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

```
cache-shm-lru
```
- 在共享内存缓存区中实现LRU淘汰机制
```
cache-stampede-lock
```
- 使用单请求模式防止缓存击穿
```
cache-key-hash
```
- 对固定缓存键使用ngx_hash进行查找
```
cache-ttl-atomic
```
- 使用原子时间戳比较检查TTL过期
```
cache-conditional-store
```
- 仅缓存成功响应以避免负缓存污染

7. Worker & Process Tuning (MEDIUM)

7. 工作进程调优（中）

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

```
worker-accept-mutex
```
- 理解Accept互斥锁对连接分配的影响
```
worker-connection-prealloc
```
- 为模块数据结构使用预分配的空闲列表
```
worker-graceful-shutdown
```
- 处理工作进程关闭信号时避免数据丢失
```
worker-single-process-debug
```
- 支持单进程模式以方便调试
```
worker-cycle-conf
```
- 通过Cycle访问配置以执行进程级操作

8. Logging & Metrics (LOW-MEDIUM)

8. 日志与指标（中低）

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

```
log-level-guard
```
- 在日志级别检查后再执行开销较大的调试参数计算
```
log-connection-context
```
- 将模块上下文附加到连接日志以实现追踪
```
log-shared-metrics
```
- 通过共享内存计数器收集指标
```
log-error-dedup
```
- 对重复错误消息进行去重并设置限流
```
log-action-string
```
- 设置日志操作字符串以记录操作上下文

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

文件	描述
references/_sections.md	类别定义与排序说明
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息