nginx-c-module-perf

nginx.org C モジュールのパフォーマンスと信頼性に関するベストプラクティス

nginx の C モジュール向けの包括的なパフォーマンス最適化と信頼性のガイドです。nginx の公式開発ドキュメントと本番環境でのエンジニアリング経験に基づいています。8 つのカテゴリーにわたる 43 のルールを含み、影響度の高い順に、自動最適化とレジリエンス向上の指針を示します。

関連スキル：このスキルは、正確性（メモリ安全性、リクエストのライフサイクル、設定）を扱う nginx-c-modules を補完します。このスキルでは、パフォーマンスの最適化と運用上の信頼性を扱います。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• nginx C モジュールのスループットとレイテンシを最適化する
• バッファのコピーを減らし、ゼロコピー I/O パスを有効にする
• コネクションプーリングとソケットオプションを調整する
• ワーカー間の共有メモリロックの競合を最小限に抑える
• 適切なエラー復旧とフォールバックレスポンスを実装する
• アップストリームのタイムアウトと再試行戦略を設定する
• 共有メモリを使ったモジュール内レスポンスキャッシュを構築する
• 負荷がかかった状態でのワーカープロセスの動作を調整する

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	接頭辞
1	バッファとゼロコピー I/O	重大	buf-
2	コネクション効率	重大	conn-
3	ロック競合とアトミック操作	高	lock-
4	エラー復旧とレジリエンス	高	err-
5	タイムアウトと再試行戦略	中〜高	timeout-
6	レスポンスキャッシュ	中	cache-
7	ワーカーとプロセスの調整	中	worker-
8	ロギングとメトリクス	低〜中	log-

クイックリファレンス

1. バッファとゼロコピー I/O（重大）

• buf-chain-reuse - 新規割り当ての代わりにバッファチェーンのリンクを再利用する
• buf-file-sendfile - 静的コンテンツをメモリに読み込む代わりに、ファイルバッファを使用する
• buf-avoid-copy - フィルターチェーンを通す際にバッファをコピーしない
• buf-coalesce-small - 出力前に小さなバッファをまとめる
• buf-shadow-reference - 完全なコピーの代わりに、派生データにはシャドウバッファを使用する
• buf-recycled-flag - アップストリームレスポンスの再利用に備えて、バッファに再利用可能フラグを設定する

2. コネクション効率（重大）

• conn-reusable-queue - アイドル状態のコネクションを再利用可能としてマークし、プールで再利用できるようにする
• conn-drain-pressure - メモリ圧迫時のコネクションのドレインを処理する
• conn-tcp-nodelay - レイテンシに敏感なレスポンスに対して TCP_NODELAY を制御する
• conn-prealloc-pool - 実行時の再割り当てを避けるためにコネクションプールのサイズを設定する
• conn-close-linger - コネクションを適切にシャットダウンするためにリンガークローズを使用する
• conn-ssl-session-reuse - アップストリームコネクションで SSL セッションキャッシュを有効にする

3. ロック競合とアトミック操作（高）

• lock-minimize-critical - 共有メモリ内のクリティカルセクションの時間を最小限に抑える
• lock-atomic-counters - 単純なカウンターにはミューテックスの代わりにアトミック操作を使用する
• lock-trylock-fallback - ワーカーの停止を避けるため、フォールバックを設けて ngx_shmtx_trylock を使用する
• lock-per-worker-aggregate - 共有メモリへのアクセスを減らすため、ワーカーごとのカウンターを集計する
• lock-alloc-outside - ホットパスの外でスラブ割り当てを行う
• lock-rw-pattern - 読み取りの多い共有データに Read-Copy-Update パターンを使用する

4. エラー復旧とレジリエンス（高）

• err-cache-errno - 上書きを防ぐため、ngx_errno を直ちにキャッシュする
• err-fallback-response - アップストリームが失敗したときにフォールバックレスポンスを返す
• err-resource-exhaustion - プールとスラブの割り当て枯渇を適切に処理する
• err-blocked-counter - リクエストの早期破棄を防ぐため、ブロックカウンターを使用する
• err-connection-error-check - I/O 操作の前に接続エラーフラグを確認する
• err-log-once-pattern - ログの大量発生を防ぐため、エラーログの繰り返しを制限する

5. タイムアウトと再試行戦略（中〜高）

• timeout-upstream-phases - 接続、送信、読み取りの各フェーズに個別のタイムアウトを設定する
• timeout-retry-next-upstream - 再試行可能な失敗に対して next_upstream マスクを設定する
• timeout-backoff-reconnect - アップストリームへの再接続試行に指数バックオフを使用する
• timeout-client-body-limit - クライアントのボディタイムアウトを設定し、低速クライアントによるリソース使用量を制限する

6. レスポンスキャッシュ（中）

• cache-shm-lru - 共有メモリキャッシュゾーンに LRU 退去方式を実装する
• cache-stampede-lock - シングルフライトパターンでキャッシュスタンピードを防ぐ
• cache-key-hash - 固定キャッシュキーの検索に ngx_hash を使用する
• cache-ttl-atomic - TTL の期限切れ判定にアトミックなタイムスタンプ比較を使用する
• cache-conditional-store - ネガティブキャッシュの汚染を避けるため、成功したレスポンスのみをキャッシュする

7. ワーカーとプロセスのチューニング（中）

• worker-accept-mutex - 接続分散に対する Accept Mutex の影響を理解する
• worker-connection-prealloc - モジュールのデータ構造に事前割り当て済みのフリーリストを使用する
• worker-graceful-shutdown - データを失わずにワーカーのシャットダウンシグナルを処理する
• worker-single-process-debug - デバッグ用のシングルプロセスモードをサポートする
• worker-cycle-conf - プロセスレベルの操作で Cycle を通じて設定にアクセスする

8. ロギングとメトリクス（低〜中）

• log-level-guard - レベルチェックでガードし、コストの高いデバッグ引数の計算を抑える
• log-connection-context - トレース用に接続ログへモジュールのコンテキストを付加する
• log-shared-metrics - 共有メモリカウンターを使ってメトリクスを収集する
• log-error-dedup - スロットリングにより、繰り返されるエラーメッセージを重複排除する
• log-action-string - 操作のコンテキストを示すログアクション文字列を設定する

使用方法

詳細な説明とコード例については、個別のリファレンスファイルを参照してください。

• セクションの定義 - カテゴリーの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報