Node.jsのプロファイリング:CPUプロファイルとフレームグラフの読み方
--cpu-prof、Chrome DevTools、Inspector、Linux perfでNode.jsのCPUホットスポットを調べます。フレームグラフと時系列表示の違い、継続的プロファイリングの条件も解説。
Node.jsのCPU使用率が高くても、遅いリクエストがCPUを使い続けているとは限りません。データベースの応答待ちと、処理そのものの重さは分けて調べる必要があります。実行時間の使い道を追うなら、まず node --cpu-prof app.js でCPUプロファイルを取得し、生成された .cpuprofile をChrome DevToolsで開きます。継続的プロファイリングを併用すると、取得・保存できている本番環境の期間とも比較できます。
CPU処理とI/O待ちを切り分ける
CPU使用率を押し上げるのは、業務コードだけではありません。GC、ネイティブモジュール、カーネル側の処理も候補になります。ユーザーCPU、システムCPU、プロセスの負荷を確認してから調査方法を選びます。システムの高負荷とCPU使用率の高さは同義ではなく、I/O待ち、接続の枯渇、遅い依存先もリクエスト遅延につながります。
CPUプロファイルが説明するのは、サンプリングで捉えた実行箇所です。どれだけ待ったのか、どの依存先が遅かったのかは、ホストのメトリクスや分散トレーシングと併せて確認します。
組み込みProfilerで取得する
node --cpu-prof app.js # 起動時からサンプリングし、正常終了時に保存する
# または、出力先を指定して起動する
mkdir -p /tmp/profiles
node --cpu-prof --cpu-prof-dir=/tmp/profiles app.js
二つの node コマンドは、どちらか一方を使います。どちらも起動時からサンプリングします。--cpu-prof-dir は出力先の指定であり、実行中のプロセスへのオンデマンド接続ではありません。前者は通常、作業ディレクトリに保存しますが、--diagnostic-dir でも変更できます。後者では /tmp/profiles への書き込み権限が必要です。ディレクトリの作成例はUnix系シェルを想定しているため、他のプラットフォームでは適切なパスに置き換えてください。
アプリケーションを正常終了させてから .cpuprofile を探します。SIGKILL や実行基盤による強制終了では、保存が完了するとは限りません。常駐サービスで取得時間を区切りたい場合は、Inspectorによる録画を使えます。
別の組み込みオプションである --prof はV8ログを生成し、--prof-process で処理します。これは .cpuprofile とは異なる形式なので、取得と分析の手順を混同しないでください。
Chrome DevToolsで結果を読む
.cpuprofile は Performance パネルに読み込みます。古い記事で登場する JS Profiler パネルは非推奨となっており、現在の手順ではPerformanceを使います。
- フレームチャート(flame chart) は、横軸に記録時間を取り、ホットスポットが発生した区間を示します。一方、集計型の フレームグラフ(flame graph、flamegraphとも表記) は同じスタックをまとめます。横方向の位置は発生順ではなく、幅はサンプルの重みや時間の割合を表します。
- 幅の広いフレームには子呼び出しの処理も含まれます。上端が広く露出した部分は手掛かりになりますが、親フレームの幅だけで関数自体が遅いとは判断できません。Self Time は自身の処理、Total Time は子呼び出しを含む時間です。
- Bottom-Up は、選択した区間の処理時間を集計します。Self TimeやTotal Timeで並べ替え、呼び出し関係からコードに戻ります。ファイルや行まで特定できるかは、ソースコードやsource mapの有無にも依存します。
InspectorとLinux perfを使い分ける
Inspector は、操作しながら取得区間を決めたい場合に向いています。管理されたデバッグ環境で node --inspect app.js を起動し、chrome://inspect から接続してPerformanceで記録を開始・停止します。既定の待ち受け先は 127.0.0.1:9229 です。接続したデバッガーはアプリケーションの実行環境を操作できるため、ポートをインターネットに公開せず、遠隔接続には管理されたトンネルなどを使います。
Linux perf は、JavaScript中心の表示では説明しきれないネイティブモジュール、V8、カーネルの実行コストを調べる手段です。既存プロセスに対する perf record -F 99 -p <pid> -g は、99 Hzでのサンプリングとコールチェーンの記録を指定します。取得後にperfを停止し、perf script などで処理します。
実行には、環境に合うLinux perf、対象をサンプリングする権限、展開可能なスタックが必要です。JavaScriptの関数名を読むには、Node起動時の --perf-basic-prof-only-functions や --interpreted-frames-native-stack、参照可能なJITマッピングとネイティブシンボルも必要になる場合があります。結果はNode/V8、カーネル、コンテナ権限に左右されます。既定で完全なJSスタックが得られるとは限らず、例を動かすためにシステム全体のサンプリング制限を緩めるべきでもありません。
継続的プロファイリングで本番の期間を比較する
本番で起きた問題は、後から再現できるとは限りません。継続的プロファイリングは、設定した期間にサンプリングを続け、取得済みで保存期間内にあるProfileを使って、性能劣化の前後を比較できるようにします。
Profileは、メトリクス、ログ、トレースに加わる信号です。有効化する前の期間や未取得の区間を復元するものではなく、狙いを定めた手動取得と併用します。取得範囲と負荷は、プロファイルの種類、頻度、ワークロードによって変わるため、常に一定の低負荷とは言えません。
ホットスポットをリクエストの挙動と照らし合わせる
ローカルのCPUプロファイルで見つけた箇所も、本番の負荷の中で確かめる必要があります。GuanceのNode.js Profilingドキュメントでは、Pyroscope経由の取り込みを説明しています。アプリケーションに @pyroscope/nodejs を組み込み、DataKitで別途Profileの受信を有効にします。サービス、環境、バージョンの各フィールドを設定すると、同じデプロイのサンプルを一貫した条件で絞り込めます。
SDKの serverAddress は、アプリケーションから到達できるDataKitのPyroscope受信先を指定します。DataKit、SDK、Node.jsのバージョン、OS、必要なプロファイルの種類を、実際の構成に合わせて確認してください。現在のPyroscope SDKドキュメントでは、CPUの取得に wall.collectCpuTime の明示的な有効化が必要です。既定のwallプロファイルとCPUプロファイルは同じ測定ではありません。
APMとProfilingは取り込み経路が異なります。APMだけを有効にしても関数単位のProfileは取得されず、サービスのフィールドが一致するだけでSpanごとの関連付けまで完成するわけでもありません。まずステージングで取得負荷を測り、同じバージョン・近い負荷条件でホットスポットとリクエスト遅延を比較します。
設定手順:Node.js Profiling(英語)・Node.js APM(英語)・Pyroscope Node.js SDK(英語)。
よくある質問
プロファイリングの負荷はどれくらいですか?
ワークロード、サンプリング頻度、分析オプションによって変わります。ステージングでスループット、遅延、メモリを比較してから、本番での取得区間を決めます。継続的プロファイリングも個別の設定と評価が必要です。
フレームグラフはどこから読めばよいですか?
Self Timeで自身の処理が重いフレームを探し、JS、ネイティブ、GCを区別して、平常時のProfileと比較します。GCの割合が高い場合、ガベージコレクションが実行時間を多く使っています。過剰な割り当て、オブジェクトの寿命、ヒープ設定などが関係し得ますが、それだけでメモリリークとは断定できません。業務アルゴリズムが大量の割り当てを生む可能性も残ります。
非同期コードのCPU時間はどう表れますか?
イベントループのコールバックは複数のtickに分かれて実行されます。CPUプロファイルは、そこでサンプリングした実行スタックを記録するもので、データベースへの await の待ち時間全体を関数自身のCPU時間に加算しません。エンドツーエンドの時間と依存先の待ち時間はトレーシングで確認します。wall時間やoff-CPUの分析には、その種類を取得できるコレクターが必要であり、CPUプロファイルからそのまま導けるものではありません。
参考資料
- Node.js APIドキュメント(英語)
- Node.js CPU Profilerのオプション(英語)
- Chrome:Node.jsの性能分析(英語)
- Node.js:Linux perfとJavaScriptシンボル(英語)
- Flame Graphs:横軸とサンプルの重み(英語)
この記事は公開ドキュメントに基づきます。例はプロジェクトの依存バージョンで検証してください。ドキュメント上の性能説明を、本プロジェクトでの測定結果として示すものではありません。
