Node.js の性能監視を perf_hooks と Prometheus で始める

Node.js の処理時間を計測し、イベントループ遅延と利用率を切り分け、Prometheus でルート別の P95 レイテンシを調べます。

ベストプラクティス
Node.js のイベントループと非同期処理のイメージ

注文 API の応答が遅くなっても、平均応答時間にはほとんど変化が出ないことがあります。特定のルートで遅いリクエストが増えたら、まず、どの処理に時間がかかったか、その間にイベントループが動けていたかを切り分けます。Node.js の性能監視では、処理区間の計測、ランタイムのメトリクス、リクエストのレイテンシを組み合わせると、この二つを別々に確認できます。

リクエストが待っている区間を計測する

データベースや外部 API の呼び出しを囲んで計測すると、待ち時間を含む経過時間が分かります。データ変換、テンプレートの描画、JSON のシリアライズなど、CPU を使う処理は個別に測ると切り分けやすくなります。たとえば、接続プールの空きを待つ時間を含むアプリ側の計測値と、データベース側のクエリ実行時間では、示している範囲が違います。

次の CommonJS の例では、PerformanceObserver を先に登録します。開始マークは呼び出しごとに分けるので、並行するクエリの計測が干渉しません。計測名は固定し、使い終わったエントリはタイムラインから削除します。

const { performance, PerformanceObserver } = require('node:perf_hooks');

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntriesByName('db-query')) {
    console.log('db-query', entry.duration);
  }
});
observer.observe({ entryTypes: ['measure'] });

let sequence = 0;
async function timeQuery(query) {
  const start = 'db-query:start:' + (++sequence);
  performance.mark(start);
  try {
    return await query();
  } finally {
    performance.measure('db-query', { start, end: performance.now() });
    performance.clearMarks(start);
    performance.clearMeasures('db-query');
  }
}

非同期関数内から、使用しているデータベースクライアントを渡して await timeQuery(() => db.query(sql)) のように呼び出します。クエリが失敗した場合も時間を記録し、エラーは呼び出し元へ伝わります。entry.duration の単位はミリ秒です。単位が秒のヒストグラムに記録するときは 1,000 で割ります。メトリクス名は固定し、ラベル値も操作の種類などに絞ります。個々の計測値の出力はデバッグ時に限り、計測を終了するときはオブザーバーを解除します。

イベントループの遅延と利用率を併せて見る

イベントループ遅延は、計測用タイマーの実行がどれだけ遅れたかを示します。イベントループ利用率(ELU)は、観測区間のうちループがアイドル待機以外に費やした時間の割合です。同期処理がメインスレッドを塞ぐと、CPU 使用率が低くても ELU は上がり得ます。次の例では、二つのスナップショットから区間内の ELU を計算します。遅延のパーセンタイルはナノ秒からミリ秒に変換し、区間ごとにヒストグラムをリセットします。unref() により、ほかに処理がなければこのタイマーだけでプロセスは終了を待ち続けません。

const { performance, monitorEventLoopDelay } = require('node:perf_hooks');

const delay = monitorEventLoopDelay({ resolution: 20 });
delay.enable();
let previous = performance.eventLoopUtilization();

const timer = setInterval(() => {
  const current = performance.eventLoopUtilization();
  const delta = performance.eventLoopUtilization(current, previous);
  previous = current;
  const p99Ms = delay.count ? delay.percentile(99) / 1e6 : null;
  delay.reset();
  console.log({ utilization: delta.utilization, p99Ms });
}, 10_000);
timer.unref();

function stopSampling() {
  clearInterval(timer);
  delay.disable();
}

サービス内で計測を開始し、終了時に stopSampling() を呼び出します。遅延は、同じサンプリング間隔で測った平常時の値と比べます。リクエストの遅延と一緒に悪化したら、CPU 負荷の高い処理、同期呼び出し、ガベージコレクション(GC)の停止時間を調べます。GC が長くなっただけでメモリの保持量が増えたとは判断できないので、ヒープ使用量の推移も確認します。リクエストだけが遅いときは、データベースの接続待ちや外部サービスも候補です。ワーカースレッドはそれぞれ独自のイベントループを持つため、メインスレッドの計測だけではワーカー内の遅延は見えません。CPU を多く使う JavaScript をワーカーに移す場合は、処理の割り振りやデータ転送にかかるコストも考慮します。

HTTP とランタイムのメトリクスを同じエンドポイントに公開する

Express の例では、旧パッケージ名の prom-client@15.1.3 を使います。後継バージョンは @prometheus-io/client として公開されているので、移行前に変更履歴を確認してください。計測は注文ルートのハンドラーで開始し、レスポンスが送信のため OS に渡った時点で finish が発生します。途中で切断されたリクエストと、クライアント側から見たレイテンシは、必要に応じて別に記録します。

const express = require('express');
const client = require('prom-client');
const app = express();
const registry = new client.Registry();

client.collectDefaultMetrics({ register: registry });
const httpDuration = new client.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of completed HTTP responses in seconds',
  labelNames: ['method', 'route', 'status'],
  buckets: [0.01, 0.05, 0.1, 0.3, 0.5, 1, 2, 5],
  registers: [registry],
});

const orderRoute = '/api/orders/:id';
app.get(orderRoute, (req, res) => {
  const end = httpDuration.startTimer();
  res.once('finish', () => end({
    method: req.method,
    route: orderRoute,
    status: String(res.statusCode),
  }));
  res.json({ ok: true });
});

app.get('/metrics', async (_req, res, next) => {
  try {
    const body = await registry.metrics();
    res.set('Content-Type', registry.contentType).end(body);
  } catch (error) {
    next(error);
  }
});

app.listen(3000, '127.0.0.1');

Express と指定のクライアントを用意して起動し、http://127.0.0.1:3000/api/orders/42 を呼び出した後に http://127.0.0.1:3000/metrics を確認します。注文 ID が変わってもラベル値は /api/orders/:id のままです。プロセスと Node.js の標準メトリクスも、HTTP ヒストグラムと同じレジストリに登録します。この例はループバックだけで待ち受けます。本番では、許可した監視基盤からだけ収集できるようにします。各レプリカを個別に収集し、Node.js の cluster モジュールを使う場合はワーカープロセスの集約を別途設定します。

インスタンスをまたいで遅いリクエストの傾向を把握する

ヒストグラムにはバケットごとの累積件数が記録されます。次のクエリは、node-api という Prometheus ジョブを例に、直近 5 分間の P95 をインスタンス横断でルートごとに推定します。集約の前に rate を適用すると系列ごとのカウンターリセットを扱えます。le はバケットの上限を保持するために必要です。

histogram_quantile(
  0.95,
  sum by (route, le) (
    rate(http_request_duration_seconds_bucket{job="node-api"}[5m])
  )
)

P95 は http_request_duration_seconds_count から求めたリクエストレートと並べます。件数が少ないと、全体の傾向が変わらなくても推定値が大きく動きます。従来型ヒストグラムのパーセンタイルはバケット内の補間で求めるため、意味のある応答時間を境界に選び、レプリカ間でそろえます。300 ms 以内の応答割合を見るなら、le="0.3" のバケットと _count のレートを、同じ集計範囲と時間窓で比較します。5xx の割合も同様に全件のレートで割り、エラー系列がまだない場合と、リクエスト自体がない区間を区別します。

遅くなったルートから依存先をたどる

注文ルートの P95 だけが悪化し、イベントループ遅延や GC が平常時と変わらないなら、遅いリクエストのトレースで時間の内訳を見ます。データベース接続を待つ時間が増えているなら、クエリを変更する前に接続プールの使用状況を確認します。一つのインスタンスで複数ルートの遅延とイベントループ遅延が重なって上がるなら、そのプロセス内の処理から調べます。

Guance では DataKit の Prom コレクター(英語) でメトリクスを収集し、別途 Node.js の APM 計装(英語) からトレースを送れます。サービス、環境、インスタンスの識別子をそろえ、同じデプロイのメトリクスとトレースを同じ時間帯で比較できるようにします。

参考資料・関連記事

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ