Node.js を Prometheus で監視する
Express のランタイムと HTTP メトリクスを収集し、PromQL でリクエストレート、5xx 率、P95 を調べ、少量トラフィックを考慮したアラートを設定します。
決済 API が 503 を返し始めても、CPU 使用率やヒープ使用量は平常どおりかもしれません。まず知りたいのは、どれだけのリクエストが失敗し、応答にかかる時間が全体として延びているかです。Node.js 用 Prometheus クライアントを使うと、ランタイムのメトリクスに加え、こうした問いに答えるためのカウンターとヒストグラムも、同じ /metrics エンドポイントで公開できます。
ここでは Express の決済ルートを例に、計測の実装から Prometheus によるスクレイプ、2 本のアラートルールの設定まで進めます。決済の応答は説明用のデータです。
アプリケーションをスクレイプできるようにする
Prometheus は定期的にアプリケーションからメトリクスを取得します。メトリクス名とラベルの組み合わせで時系列が決まり、スクレイプが成功するたびにサンプルが追加されます。Prometheus が PromQL のクエリとアラートルールを評価し、Alertmanager が通知先を振り分けます。可視化には Grafana を利用できます。
このクライアントは、以前は prom-client という名前で配布されていました。ここでは後継の @prometheus-io/client 0.16.1 と Node.js 22 を使います。このバージョンが対応するのは Node.js 22、24、および 26 以降です。試す場合は、検証用プロジェクトに依存パッケージを入れてください。
npm install express@5.3.0 @prometheus-io/client@0.16.1
次のコードを checkout.cjs として保存し、node checkout.cjs で起動します。ループバックでの待ち受けはローカル検証用です。本番では、収集側が管理されたネットワーク経路で /metrics に到達できるようにしたうえで、ほかのアクセスを制限します。
const express = require('express');
const client = require('@prometheus-io/client');
const app = express();
client.collectDefaultMetrics();
const requests = new client.Counter({
name: 'http_requests_total',
help: 'Completed checkout HTTP responses',
labelNames: ['method', 'route', 'status'],
});
const inFlight = new client.Gauge({
name: 'http_requests_in_flight',
help: 'Checkout HTTP responses still in progress',
});
const duration = new client.Histogram({
name: 'request_duration_seconds',
help: 'Completed checkout response duration in seconds',
labelNames: ['route'],
buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
});
app.get('/metrics', async (req, res) => {
res.set('Content-Type', client.register.contentType);
res.end(await client.register.metrics());
});
const checkoutRoute = '/checkout';
for (const status of ['204', '503']) {
requests.inc({ method: 'POST', route: checkoutRoute, status }, 0);
}
app.post(checkoutRoute, (req, res) => {
const route = checkoutRoute;
const stopTimer = duration.startTimer({ route });
inFlight.inc();
res.once('finish', () => {
requests.inc({ method: req.method, route, status: String(res.statusCode) });
stopTimer();
});
res.once('close', () => inFlight.dec());
res.status(req.query.fail === '1' ? 503 : 204).end();
});
app.listen(3000, '127.0.0.1');
curl -i -X POST 'http://127.0.0.1:3000/checkout'
curl -i -X POST 'http://127.0.0.1:3000/checkout?fail=1'
curl -fsS http://127.0.0.1:3000/metrics
上の 2 リクエストは 204 と 503 を返します。クエリパラメーターはエラーを再現するためのものです。スクレイプ結果では http_requests_total に 2 種類のステータスが現れ、request_duration_seconds_count は完了した応答 2 件を示します。デフォルトのメトリクスにはイベントループ遅延、ガベージコレクション、ヒープ使用量、CPU などがあります。一部は実行環境により異なります。
知りたいことに合わせてメトリクスを選ぶ
**Counter(カウンター)**は、完了した応答をメソッド、ルート、ステータス別に数えます。プロセスが再起動するとカウントはリセットされます。最終ステータスは応答の finish で取得します。このイベントはデータを送信のために OS へ渡した時点を示します。そのため、ここで計測するのはルート処理を開始してからのサーバー側の時間で、クライアントまでの通信時間は含みません。
**Gauge(ゲージ)**は、処理中の応答数を表します。処理を始めたら増やし、close で減らします。途中で接続が切れたときも同じように減ります。finish に達しなかった応答は完了件数やレイテンシーの分布に含めません。切断自体を監視したいなら、別に数えます。
**クラシックヒストグラム(Histogram)**は、処理時間を累積バケットに記録します。各レプリカのバケット境界がそろっていれば、Prometheus が集計してから分位点を推定できます。注目するレイテンシーのしきい値の前後に境界を置くと、判定しやすくなります。**Summary(サマリー)**はプロセス内で分位点を求められます。各プロセスの P95 を平均しても、全リクエストの P95 は求まりません。
ラベルに使う値は、種類が増え続けないものにします。たとえば /orders/:id ならルートテンプレートを使い、注文 ID やクエリ文字列はラベルに含めません。ラベルの組み合わせごとに時系列が増え、ヒストグラムではバケットと合計値、件数の分だけ増えます。
リクエストレート、エラー率、P95 をクエリする
次の設定を prometheus.yml として保存します。次節のアラートファイルを同じディレクトリに置き、例のアプリケーションと同じホストで prometheus --config.file=prometheus.yml を実行します。
global:
scrape_interval: 15s
evaluation_interval: 15s
rule_files:
- checkout-alerts.yml
scrape_configs:
- job_name: checkout-node
static_configs:
- targets: ["127.0.0.1:3000"]
1 本目はルート別の 1 秒あたりの完了応答数、2 本目は決済ジョブ全体の 5xx 応答率をパーセントで、3 本目はルート別の推定 P95 を秒単位で返します。
sum by (route) (rate(http_requests_total{job="checkout-node"}[5m]))
100 * (
sum(rate(http_requests_total{job="checkout-node",status=~"5.."}[5m]))
or 0 * sum(rate(http_requests_total{job="checkout-node"}[5m]))
) / (sum(rate(http_requests_total{job="checkout-node"}[5m])) > 0)
histogram_quantile(0.95, sum by (le, route) (
rate(request_duration_seconds_bucket{job="checkout-node"}[5m])
))
先に各カウンターの時系列に rate() を適用してから集計すると、Prometheus は各プロセスの再起動に伴うリセットを扱えます。総レートを計算できても 5xx のレートが得られない場合、or 0 * ... が分子をゼロで補います。新しい時系列は、サンプルが足りるまでレートを求められません。例では 2 種類のステータスのカウンターを先に初期化し、最初のエラーより前にゼロ値をスクレイプできるようにしています。トラフィックがゼロか、総レートが得られない場合は結果が空になります。スクレイプが失敗していないかは up で別に確認します。
異常が続いたら通知する
checkout-alerts.yml は直近 5 分間を対象にエラー率と P95 を計算します。ルールの条件を満たした状態が 5 分間続くとアラートが発火します。例ではごく少ないリクエストで通知が出ないように、最小リクエストレートも条件に入れています。しきい値はサービスのトラフィックと SLO に合わせて調整し、通知を配信するには Prometheus の Alertmanager 接続先を設定します。
groups:
- name: checkout
rules:
- record: checkout:http_requests_per_second:rate5m
expr: sum(rate(http_requests_total{job="checkout-node"}[5m]))
- alert: CheckoutHighErrorRatio
expr: |
(
sum(rate(http_requests_total{job="checkout-node",status=~"5.."}[5m]))
or 0 * checkout:http_requests_per_second:rate5m
) / checkout:http_requests_per_second:rate5m > 0.01
and checkout:http_requests_per_second:rate5m > 0.2
for: 5m
- alert: CheckoutHighP95
expr: |
histogram_quantile(0.95, sum by (le) (
rate(request_duration_seconds_bucket{job="checkout-node"}[5m])
)) > 2
and checkout:http_requests_per_second:rate5m > 0.2
for: 5m
Guance でも同じエンドポイントを使う
DataKit の Prom コレクターは、既存の /metrics をスクレイプして、選択したメトリクスを Guance に送信できます。接続先、必要な認証設定、収集間隔を指定します。エラー率やレイテンシーのモニターを作る前に、メトリクスの型、単位、ラベルの対応を確認してください。レイテンシーのアラートからリクエストのトレースを調べるには、Node.js の APM 計装が必要です。スパンにログを関連付けるには、ログにトレース ID とスパン ID を注入し、サービス、環境、バージョンの項目をトレース側とそろえます。
デプロイ時によくある疑問
複数のレプリカや Node.js のワーカーはどうスクレイプしますか?
各レプリカを個別のターゲットにします。ロードバランサー配下の単一エンドポイントだと、取得するプロセスがスクレイプごとに変わる可能性があります。Node.js の cluster を使う場合は、ワーカーごとに公開するか、クライアントの AggregatorRegistry で集計します。Kubernetes で Prometheus Operator を導入済みなら、セレクターとポートをそろえ、ServiceMonitor でエンドポイントを検出できます。
スクレイプの間に終了する CronJob はどうしますか?
特定のマシンに依存しないサービス単位のバッチジョブなら、実行結果や最終成功時刻を Pushgateway に送れます。Prometheus や DataKit がそのエンドポイントをスクレイプします。グループは明示的に削除するまで残るので、不要になったジョブの削除手順も決めておきます。特定のマシンで動くジョブなら Node Exporter の textfile コレクターが候補です。実行ごとの記録が必要なら、ログやトレースも使えます。
計装の負荷はどれくらいですか?
実際に近いトラフィックで測定します。メトリクス数、ラベルの組み合わせ、バケット数、スクレイプ頻度によって、計測負荷や転送量は変わります。ユーザー ID など取りうる値の種類が多いラベルは、バックエンドが保存、検索する時系列も増やします。
参照資料
- Node.js 用 Prometheus クライアントと変更履歴
- Prometheus のヒストグラムとサマリーと計装の実践ガイド
- Prometheus のアラートルールと Pushgateway の用途
- Node.js の HTTP 応答イベントと Prometheus Operator の設定
