
2026/10/24 3:38
Nginx のネイティブプロモテウス連携
RSS: https://news.ycombinator.com/rss
要約▶
Japanese Translation:
Categorica が公式に open-sourcing する「nginx-stats-prometheus」は、NGINX 用のオープンソースのエクスポンダーモジュールであり、別個のサイドカーウェブサーバーの必要性をなくすため、NGINX と直接統合してリクエスト数や接続状態など Prometheus に互換のあるメトリクスを提供します。ソースから構築することをお勧めしており、これには C99 コンパイラ(例:Clang)、PCRE、OpenSSL、zlib が必要であり、NGINX は特定のフラグ(
--with-compat および --with-http_stub_status_module)でコンパイルされている必要があります。NGINX ソースと組み合わせて構成した後、make module を実行して次に sudo make install を実行することでプラグインをインストールします。構成には load_module 経由で modules/ngx_http_stats_prom_module.so を読み込み、デフォルトはポート 9100 に設定される prometheus_metrics ブロックを定義する操作が含まれます。エンドポイント http://hostname:9100/metrics は Prometheus のインジェスジョンに適したメトリクスを提供しており、nginx_up や合計のリクエスト/レスポンス数、接続状態などの基本メトリクスに加え、最初のリクエスト後には追加のサーバー別/アップストリーム別のメトリクスも含まれます(512 ディレクティブおよび 255 文字のプレフィックスに制限)。プラグインは統計データのためにデフォルトで 1 MB の共有メモリを割り当てており、prometheus_metrics_shm_size を経由して構成しない限り、超過した場合は静かに収集をスキップします。少ない統計データを提示する点、再構築を必要とするバージョン依存問題、および実戦での検証が不十分な点から、公式のエクスポンダーへのドロップイン交換としては適しません。MIT ライセンスの下で公開され、受け入れられたプルリクエストはありますが、プロジェクトは明確にサポートまたはトラブルシューティング支援の保証を提供していません。これはミニマリストなセットアップを求めているチームに適していますが、包括的なデータが必要な場合や即時の技術的支援が求められる場合は不十分になる可能性があります。本文
NGINX と Prometheus のネイティブ統合:独自モジュールのオープンソース公開
Categorica が公式に、NGINX 用の独自 Prometheus 統計エクスポートモジュールをオープンソース化しました。本ツールはコンテナ環境なしでの運用やデプロイメント設定の簡素化を可能にします。
📦 概要と背景
- 従来の課題: NGINX のメトリクス収集には、通常「NGINX Prometheus Exporter」という別の Web サーバーを実行するサイドカーコンテナが必要でした。
- 問題点: 「監視者を監視する者」となる複雑性や、不要不急な依存関係の排除を目的としています。
- 本リリース: 週末に開発された成果として、NGINX プラグインとして直接 NGINX に組み込まれる形で公開されました。
🛠️ 前提条件と環境構築
モジュールをコンパイルするには、以下の環境が必要です(Unix ライクな環境を前提)。
必要なツール
- コンパイラ: C99 準拠のもの(例:Clang)
- ライブラリ: PCRE, OpenSSL, zlib のライブラリとヘッダファイル
NGINX ソースコードの入手方法
パッケージマネージャ版では機能不足になる可能性があるため、ソースコードからビルドするのが推奨されます。
1. NGINX のビルド
既に適切なバージョンがインストールされている場合はこのステップをスキップできます。
cd path-to-nginx-source; # プラグイン構築時のパス利用 export NGINX_SRC=`pwd`; ./configure --with-compat --with-http_stub_status_module; make -j; sudo make install;
上記コマンドは、NGINX を
系パスにインストールします。/usr/local
2. プラグインのビルド
付録の
Makefile が NGINX バージョンを自動検出・ソースコードをダウンロードします。
- 環境変数省略:
でパスを設定すると、バージョンチェックとダウンロードをスキップできます。-NGINX_SRC- - コマンド実行:
make module sudo make install;
インストール先の詳細は GitHub リポジトリの
README.md を参照してください。
⚙️ 設定と使用方法
ビルド後は、統計情報を公開するルートを定義する必要があります。
NGINX 設定例 (nginx.conf
)
nginx.confload_module modules/ngx_http_stats_prom_module.so; http { # オプション:共有メモリサイズ(デフォルト 1m) # prometheus_metrics_shm_size 2m; server { # 標準的な NGINX ディレクティブ... listen 9100; location /metrics { prometheus_metrics; } } }
メトリクスの確認
設定を適用後、以下の URL でメトリクスエンドポイントをクエリできます:
curl http://localhost:9100/metrics
📊 エクスポートされる統計情報
プロセス起動直後から利用可能な基本メトリクスと、サーバー/アップストリームごとの詳細メトリクスが提供されます。
基本メトリクス一覧
| メトリック名 | タイプ | ラベル(Label) |
|---|---|---|
| gauge | なし |
| gauge | なし |
| counter | なし |
| counter | status (1xx–5xx) |
| counter | method (GET, POST 等) |
| counter | なし |
| counter | なし |
| counter | version (1.0, 2.0, 3.0 等) |
| histogram | バケット (0.005s - 10s) |
| gauge | なし |
| gauge | なし |
| gauge | なし |
| gauge | なし |
| counter | なし |
| counter | なし |
サーバー/アップストリーム固有メトリクス
定義されたプレフィックス(例:
server_name_ や upstream_name_)に基づき、以下の計測が行われます:
: リクエスト数<prefix>_requests_total
: レスポンス数(ステータス別)<prefix>_response_total
: リクエストサイズ合計<prefix>_request_bytes_total
: レスポンスサイズ合計<prefix>_response_bytes_total
メモリ制限について
- 共有メモリサイズ: デフォルト 1MB が統計情報の保存に割り当てられています。
- 枯渇時の動作: 容量を超えると、統計収集は沈黙してスキップされます。
- 設定変更:
ディレクティブでサイズを調整可能です(例:prometheus_metrics_shm_size
)。2m - サポート数: サーバーまたはアップストリームディレクティブは最大 512 個。プレフィックス長が 255 文字を超える場合は無視されます。
⚠️ 制限事項と注意点
本モジュールは
nginx-prometheus-exporter の完全な置き換えではなく、以下の点に留意してください:
- 統計量の少なさ: 収集される項目数が限定的です。
- ビルド依存性: NGINX を更新する場合、通常プラグインも再ビルドが必要です。
- 実戦検証: ベータ版段階のため、バグや動作制限の可能性が残ります。公式サポートは現時点では提供しておりません。
📜 ライセンスと貢献
- ライセンス: MIT License
- プルリクエスト歓迎: 改善提案やパッチのご提出を大歓迎です。
- レビュープロセス: パッチセット提出時は、必ず人間によるレビューを経て合流されます。
- サポート: コントリビューターには現状の公式サポートは提供されていません。