Node.js v25.0.0 ドキュメンテーション
- Node.js v25.0.0
- 目次
-
索引
- アサーションテスト
- 非同期コンテキストの追跡
- Async hooks
- Buffer
- C++アドオン
- Node-API を使用した C/C++ アドオン
- C++ embedder API
- 子プロセス
- Cluster
- コマンドラインオプション
- Console
- Crypto
- Debugger
- 非推奨のAPI
- Diagnostics Channel
- DNS
- Domain
- 環境変数
- エラー
- Events
- ファイルシステム
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- 国際化
- モジュール: CommonJS モジュール
- モジュール: ECMAScript モジュール
- モジュール:
node:moduleAPI - モジュール: パッケージ
- モジュール: TypeScript
- Net
- OS
- Path
- Performance hooks
- パーミッション
- Process
- Punycode
- クエリストリング
- Readline
- REPL
- レポート
- 単一実行可能ファイルアプリケーション
- SQLite
- Stream
- String decoder
- テストランナー
- タイマー
- TLS/SSL
- トレースイベント
- TTY
- UDP/datagram
- URL
- ユーティリティ
- V8
- VM
- WASI
- Web Crypto API
- Web Streams API
- ワーカースレッド
- Zlib
- 他のバージョン
- オプション
診断レポート#
ファイルに書き出される、JSON形式の診断サマリーを提供します。
このレポートは、開発、テスト、および本番環境での使用を目的としており、問題判別のための情報をキャプチャして保持します。これには、JavaScriptとネイティブのスタックトレース、ヒープ統計、プラットフォーム情報、リソース使用状況などが含まれます。レポートオプションを有効にすると、未処理の例外、致命的なエラー、およびユーザーシグナルで診断レポートをトリガーできるほか、API呼び出しを通じてプログラム的にトリガーすることも可能です。
参考として、キャッチされなかった例外で生成された完全なレポート例を以下に示します。
{
"header": {
"reportVersion": 5,
"event": "exception",
"trigger": "Exception",
"filename": "report.20181221.005011.8974.0.001.json",
"dumpEventTime": "2018-12-21T00:50:11Z",
"dumpEventTimeStamp": "1545371411331",
"processId": 8974,
"cwd": "/home/nodeuser/project/node",
"commandLine": [
"/home/nodeuser/project/node/out/Release/node",
"--report-uncaught-exception",
"/home/nodeuser/project/node/test/report/test-exception.js",
"child"
],
"nodejsVersion": "v12.0.0-pre",
"glibcVersionRuntime": "2.17",
"glibcVersionCompiler": "2.17",
"wordSize": "64 bit",
"arch": "x64",
"platform": "linux",
"componentVersions": {
"node": "12.0.0-pre",
"v8": "7.1.302.28-node.5",
"uv": "1.24.1",
"zlib": "1.2.11",
"ares": "1.15.0",
"modules": "68",
"nghttp2": "1.34.0",
"napi": "3",
"llhttp": "1.0.1",
"openssl": "1.1.0j"
},
"release": {
"name": "node"
},
"osName": "Linux",
"osRelease": "3.10.0-862.el7.x86_64",
"osVersion": "#1 SMP Wed Mar 21 18:14:51 EDT 2018",
"osMachine": "x86_64",
"cpus": [
{
"model": "Intel(R) Core(TM) i7-6820HQ CPU @ 2.70GHz",
"speed": 2700,
"user": 88902660,
"nice": 0,
"sys": 50902570,
"idle": 241732220,
"irq": 0
},
{
"model": "Intel(R) Core(TM) i7-6820HQ CPU @ 2.70GHz",
"speed": 2700,
"user": 88902660,
"nice": 0,
"sys": 50902570,
"idle": 241732220,
"irq": 0
}
],
"networkInterfaces": [
{
"name": "en0",
"internal": false,
"mac": "13:10:de:ad:be:ef",
"address": "10.0.0.37",
"netmask": "255.255.255.0",
"family": "IPv4"
}
],
"host": "test_machine"
},
"javascriptStack": {
"message": "Error: *** test-exception.js: throwing uncaught Error",
"stack": [
"at myException (/home/nodeuser/project/node/test/report/test-exception.js:9:11)",
"at Object.<anonymous> (/home/nodeuser/project/node/test/report/test-exception.js:12:3)",
"at Module._compile (internal/modules/cjs/loader.js:718:30)",
"at Object.Module._extensions..js (internal/modules/cjs/loader.js:729:10)",
"at Module.load (internal/modules/cjs/loader.js:617:32)",
"at tryModuleLoad (internal/modules/cjs/loader.js:560:12)",
"at Function.Module._load (internal/modules/cjs/loader.js:552:3)",
"at Function.Module.runMain (internal/modules/cjs/loader.js:771:12)",
"at executeUserCode (internal/bootstrap/node.js:332:15)"
]
},
"nativeStack": [
{
"pc": "0x000055b57f07a9ef",
"symbol": "report::GetNodeReport(v8::Isolate*, node::Environment*, char const*, char const*, v8::Local<v8::String>, std::ostream&) [./node]"
},
{
"pc": "0x000055b57f07cf03",
"symbol": "report::GetReport(v8::FunctionCallbackInfo<v8::Value> const&) [./node]"
},
{
"pc": "0x000055b57f1bccfd",
"symbol": " [./node]"
},
{
"pc": "0x000055b57f1be048",
"symbol": "v8::internal::Builtin_HandleApiCall(int, v8::internal::Object**, v8::internal::Isolate*) [./node]"
},
{
"pc": "0x000055b57feeda0e",
"symbol": " [./node]"
}
],
"javascriptHeap": {
"totalMemory": 5660672,
"executableMemory": 524288,
"totalCommittedMemory": 5488640,
"availableMemory": 4341379928,
"totalGlobalHandlesMemory": 8192,
"usedGlobalHandlesMemory": 3136,
"usedMemory": 4816432,
"memoryLimit": 4345298944,
"mallocedMemory": 254128,
"externalMemory": 315644,
"peakMallocedMemory": 98752,
"nativeContextCount": 1,
"detachedContextCount": 0,
"doesZapGarbage": 0,
"heapSpaces": {
"read_only_space": {
"memorySize": 524288,
"committedMemory": 39208,
"capacity": 515584,
"used": 30504,
"available": 485080
},
"new_space": {
"memorySize": 2097152,
"committedMemory": 2019312,
"capacity": 1031168,
"used": 985496,
"available": 45672
},
"old_space": {
"memorySize": 2273280,
"committedMemory": 1769008,
"capacity": 1974640,
"used": 1725488,
"available": 249152
},
"code_space": {
"memorySize": 696320,
"committedMemory": 184896,
"capacity": 152128,
"used": 152128,
"available": 0
},
"map_space": {
"memorySize": 536576,
"committedMemory": 344928,
"capacity": 327520,
"used": 327520,
"available": 0
},
"large_object_space": {
"memorySize": 0,
"committedMemory": 0,
"capacity": 1520590336,
"used": 0,
"available": 1520590336
},
"new_large_object_space": {
"memorySize": 0,
"committedMemory": 0,
"capacity": 0,
"used": 0,
"available": 0
}
}
},
"resourceUsage": {
"rss": "35766272",
"free_memory": "1598337024",
"total_memory": "17179869184",
"available_memory": "1598337024",
"maxRss": "36624662528",
"constrained_memory": "36624662528",
"userCpuSeconds": 0.040072,
"kernelCpuSeconds": 0.016029,
"cpuConsumptionPercent": 5.6101,
"userCpuConsumptionPercent": 4.0072,
"kernelCpuConsumptionPercent": 1.6029,
"pageFaults": {
"IORequired": 0,
"IONotRequired": 4610
},
"fsActivity": {
"reads": 0,
"writes": 0
}
},
"uvthreadResourceUsage": {
"userCpuSeconds": 0.039843,
"kernelCpuSeconds": 0.015937,
"cpuConsumptionPercent": 5.578,
"userCpuConsumptionPercent": 3.9843,
"kernelCpuConsumptionPercent": 1.5937,
"fsActivity": {
"reads": 0,
"writes": 0
}
},
"libuv": [
{
"type": "async",
"is_active": true,
"is_referenced": false,
"address": "0x0000000102910900",
"details": ""
},
{
"type": "timer",
"is_active": false,
"is_referenced": false,
"address": "0x00007fff5fbfeab0",
"repeat": 0,
"firesInMsFromNow": 94403548320796,
"expired": true
},
{
"type": "check",
"is_active": true,
"is_referenced": false,
"address": "0x00007fff5fbfeb48"
},
{
"type": "idle",
"is_active": false,
"is_referenced": true,
"address": "0x00007fff5fbfebc0"
},
{
"type": "prepare",
"is_active": false,
"is_referenced": false,
"address": "0x00007fff5fbfec38"
},
{
"type": "check",
"is_active": false,
"is_referenced": false,
"address": "0x00007fff5fbfecb0"
},
{
"type": "async",
"is_active": true,
"is_referenced": false,
"address": "0x000000010188f2e0"
},
{
"type": "tty",
"is_active": false,
"is_referenced": true,
"address": "0x000055b581db0e18",
"width": 204,
"height": 55,
"fd": 17,
"writeQueueSize": 0,
"readable": true,
"writable": true
},
{
"type": "signal",
"is_active": true,
"is_referenced": false,
"address": "0x000055b581d80010",
"signum": 28,
"signal": "SIGWINCH"
},
{
"type": "tty",
"is_active": true,
"is_referenced": true,
"address": "0x000055b581df59f8",
"width": 204,
"height": 55,
"fd": 19,
"writeQueueSize": 0,
"readable": true,
"writable": true
},
{
"type": "loop",
"is_active": true,
"address": "0x000055fc7b2cb180",
"loopIdleTimeSeconds": 22644.8
},
{
"type": "tcp",
"is_active": true,
"is_referenced": true,
"address": "0x000055e70fcb85d8",
"localEndpoint": {
"host": "localhost",
"ip4": "127.0.0.1",
"port": 48986
},
"remoteEndpoint": {
"host": "localhost",
"ip4": "127.0.0.1",
"port": 38573
},
"sendBufferSize": 2626560,
"recvBufferSize": 131072,
"fd": 24,
"writeQueueSize": 0,
"readable": true,
"writable": true
}
],
"workers": [],
"environmentVariables": {
"REMOTEHOST": "REMOVED",
"MANPATH": "/opt/rh/devtoolset-3/root/usr/share/man:",
"XDG_SESSION_ID": "66126",
"HOSTNAME": "test_machine",
"HOST": "test_machine",
"TERM": "xterm-256color",
"SHELL": "/bin/csh",
"SSH_CLIENT": "REMOVED",
"PERL5LIB": "/opt/rh/devtoolset-3/root//usr/lib64/perl5/vendor_perl:/opt/rh/devtoolset-3/root/usr/lib/perl5:/opt/rh/devtoolset-3/root//usr/share/perl5/vendor_perl",
"OLDPWD": "/home/nodeuser/project/node/src",
"JAVACONFDIRS": "/opt/rh/devtoolset-3/root/etc/java:/etc/java",
"SSH_TTY": "/dev/pts/0",
"PCP_DIR": "/opt/rh/devtoolset-3/root",
"GROUP": "normaluser",
"USER": "nodeuser",
"LD_LIBRARY_PATH": "/opt/rh/devtoolset-3/root/usr/lib64:/opt/rh/devtoolset-3/root/usr/lib",
"HOSTTYPE": "x86_64-linux",
"XDG_CONFIG_DIRS": "/opt/rh/devtoolset-3/root/etc/xdg:/etc/xdg",
"MAIL": "/var/spool/mail/nodeuser",
"PATH": "/home/nodeuser/project/node:/opt/rh/devtoolset-3/root/usr/bin:/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin",
"PWD": "/home/nodeuser/project/node",
"LANG": "en_US.UTF-8",
"PS1": "\\u@\\h : \\[\\e[31m\\]\\w\\[\\e[m\\] > ",
"SHLVL": "2",
"HOME": "/home/nodeuser",
"OSTYPE": "linux",
"VENDOR": "unknown",
"PYTHONPATH": "/opt/rh/devtoolset-3/root/usr/lib64/python2.7/site-packages:/opt/rh/devtoolset-3/root/usr/lib/python2.7/site-packages",
"MACHTYPE": "x86_64",
"LOGNAME": "nodeuser",
"XDG_DATA_DIRS": "/opt/rh/devtoolset-3/root/usr/share:/usr/local/share:/usr/share",
"LESSOPEN": "||/usr/bin/lesspipe.sh %s",
"INFOPATH": "/opt/rh/devtoolset-3/root/usr/share/info",
"XDG_RUNTIME_DIR": "/run/user/50141",
"_": "./node"
},
"userLimits": {
"core_file_size_blocks": {
"soft": "",
"hard": "unlimited"
},
"data_seg_size_bytes": {
"soft": "unlimited",
"hard": "unlimited"
},
"file_size_blocks": {
"soft": "unlimited",
"hard": "unlimited"
},
"max_locked_memory_bytes": {
"soft": "unlimited",
"hard": 65536
},
"max_memory_size_bytes": {
"soft": "unlimited",
"hard": "unlimited"
},
"open_files": {
"soft": "unlimited",
"hard": 4096
},
"stack_size_bytes": {
"soft": "unlimited",
"hard": "unlimited"
},
"cpu_time_seconds": {
"soft": "unlimited",
"hard": "unlimited"
},
"max_user_processes": {
"soft": "unlimited",
"hard": 4127290
},
"virtual_memory_bytes": {
"soft": "unlimited",
"hard": "unlimited"
}
},
"sharedObjects": [
"/lib64/libdl.so.2",
"/lib64/librt.so.1",
"/lib64/libstdc++.so.6",
"/lib64/libm.so.6",
"/lib64/libgcc_s.so.1",
"/lib64/libpthread.so.0",
"/lib64/libc.so.6",
"/lib64/ld-linux-x86-64.so.2"
]
}
使用方法#
node --report-uncaught-exception --report-on-signal \
--report-on-fatalerror app.js
-
--report-uncaught-exception未処理の例外でレポートが生成されるようにします。ネイティブスタックやその他のランタイム環境データと併せてJavaScriptスタックを調査する際に便利です。 -
--report-on-signal実行中のNode.jsプロセスに指定された(または事前定義された)シグナルを受信した際にレポートが生成されるようにします。(レポートをトリガーするシグナルの変更方法については後述。) デフォルトのシグナルはSIGUSR2です。別のプログラムからレポートをトリガーする必要がある場合に便利です。アプリケーションモニターは、この機能を利用して定期的にレポートを収集し、豊富な内部ランタイムデータをビューにプロットできます。
シグナルベースのレポート生成はWindowsではサポートされていません。
通常、レポートをトリガーするシグナルを変更する必要はありません。しかし、SIGUSR2 がすでに他の目的で使用されている場合、このフラグはレポート生成用のシグナルを変更し、SIGUSR2 の本来の意味をその目的のために保持するのに役立ちます。
-
--report-on-fatalerrorアプリケーションの終了につながる致命的なエラー(メモリ不足など、Node.jsランタイム内の内部エラー)でレポートがトリガーされるようにします。ヒープ、スタック、イベントループの状態、リソース消費などの様々な診断データ要素を調査して、致命的なエラーの原因を究明するのに便利です。 -
--report-compactレポートをコンパクトな形式、つまり単一行のJSONで書き込みます。これは、人間が読むために設計されたデフォルトの複数行形式よりも、ログ処理システムで消費しやすい形式です。 -
--report-directoryレポートが生成される場所。 -
--report-filenameレポートが書き込まれるファイルの名前。 -
--report-signalレポート生成用のシグナルを設定またはリセットします(Windowsではサポートされていません)。デフォルトのシグナルはSIGUSR2です。 -
--report-exclude-network診断レポートからheader.networkInterfacesを除外し、libuv.*.(remote|local)Endpoint.hostでの逆引きDNSクエリを無効にします。デフォルトではこれは設定されておらず、ネットワークインターフェースは含まれます。 -
--report-exclude-env診断レポートからenvironmentVariablesを除外します。デフォルトではこれは設定されておらず、環境変数は含まれます。
レポートは、JavaScriptアプリケーションからのAPI呼び出しによってもトリガーできます。
process.report.writeReport();
この関数は、オプションの追加引数 filename を取ります。これは、レポートが書き込まれるファイルの名前です。
process.report.writeReport('./foo.json');
この関数は、オプションの追加引数 err を取ります。これは、レポートに出力されるJavaScriptスタックのコンテキストとして使用される Error オブジェクトです。コールバックや例外ハンドラでエラーを処理するためにレポートを使用する場合、これにより、元のエラーの場所とそれが処理された場所の両方をレポートに含めることができます。
try {
process.chdir('/non-existent-path');
} catch (err) {
process.report.writeReport(err);
}
// Any other code
filenameとエラーオブジェクトの両方を writeReport() に渡す場合、エラーオブジェクトは2番目のパラメータでなければなりません。
try {
process.chdir('/non-existent-path');
} catch (err) {
process.report.writeReport(filename, err);
}
// Any other code
診断レポートの内容は、JavaScriptアプリケーションからのAPI呼び出しによってJavaScriptオブジェクトとして返すことができます。
const report = process.report.getReport();
console.log(typeof report === 'object'); // true
// Similar to process.report.writeReport() output
console.log(JSON.stringify(report, null, 2));
この関数は、オプションの追加引数 err を取ります。これは、レポートに出力されるJavaScriptスタックのコンテキストとして使用される Error オブジェクトです。
const report = process.report.getReport(new Error('custom error'));
console.log(typeof report === 'object'); // true
APIバージョンは、リソース消費の自己調整、ロードバランシング、モニタリングなどを期待して、アプリケーション内からランタイムの状態を調査する際に便利です。
レポートの内容は、イベントタイプ、日付、時刻、PID、およびNode.jsのバージョンを含むヘッダーセクション、JavaScriptとネイティブのスタックトレースを含むセクション、V8ヒープ情報を含むセクション、libuv ハンドル情報を含むセクション、およびCPUとメモリの使用状況とシステム制限を示すOSプラットフォーム情報セクションで構成されます。レポートの例は、Node.js REPLを使用してトリガーできます。
$ node
> process.report.writeReport();
Writing Node.js report to file: report.20181126.091102.8480.0.001.json
Node.js report completed
>
レポートが書き込まれると、開始と終了のメッセージがstderrに出力され、レポートのファイル名が呼び出し元に返されます。デフォルトのファイル名には、日付、時刻、PID、およびシーケンス番号が含まれます。シーケンス番号は、同じNode.jsプロセスで複数回生成された場合に、レポートダンプをランタイムの状態と関連付けるのに役立ちます。
レポートのバージョン#
診断レポートには、レポートの形式を一意に表す単一の数字のバージョン番号 (report.header.reportVersion) が関連付けられています。バージョン番号は、新しいキーが追加または削除されたり、値のデータ型が変更されたりした場合にインクリメントされます。レポートバージョンの定義は、LTSリリース間で一貫しています。
バージョン履歴#
バージョン 5#
これらの値はバイト単位で与えられるため、userLimits セクションのキー data_seg_size_kbytes、max_memory_size_kbytes、および virtual_memory_kbytes を、それぞれ data_seg_size_bytes、max_memory_size_bytes、および virtual_memory_bytes に置き換えました。
{
"userLimits": {
// Skip some keys ...
"data_seg_size_bytes": { // replacing data_seg_size_kbytes
"soft": "unlimited",
"hard": "unlimited"
},
// ...
"max_memory_size_bytes": { // replacing max_memory_size_kbytes
"soft": "unlimited",
"hard": "unlimited"
},
// ...
"virtual_memory_bytes": { // replacing virtual_memory_kbytes
"soft": "unlimited",
"hard": "unlimited"
}
}
}
バージョン 4#
tcp および udp libuvハンドルのエンドポイントに新しいフィールド ipv4 と ipv6 が追加されました。例:
{
"libuv": [
{
"type": "tcp",
"is_active": true,
"is_referenced": true,
"address": "0x000055e70fcb85d8",
"localEndpoint": {
"host": "localhost",
"ip4": "127.0.0.1", // new key
"port": 48986
},
"remoteEndpoint": {
"host": "localhost",
"ip4": "127.0.0.1", // new key
"port": 38573
},
"sendBufferSize": 2626560,
"recvBufferSize": 131072,
"fd": 24,
"writeQueueSize": 0,
"readable": true,
"writable": true
},
{
"type": "tcp",
"is_active": true,
"is_referenced": true,
"address": "0x000055e70fcd68c8",
"localEndpoint": {
"host": "ip6-localhost",
"ip6": "::1", // new key
"port": 52266
},
"remoteEndpoint": {
"host": "ip6-localhost",
"ip6": "::1", // new key
"port": 38573
},
"sendBufferSize": 2626560,
"recvBufferSize": 131072,
"fd": 25,
"writeQueueSize": 0,
"readable": false,
"writable": false
}
]
}
バージョン 3#
resourceUsage セクションに以下のメモリ使用量キーが追加されました。
{
"resourceUsage": {
"rss": "35766272",
"free_memory": "1598337024",
"total_memory": "17179869184",
"available_memory": "1598337024",
"constrained_memory": "36624662528"
}
}
バージョン 2#
Worker サポートが追加されました。詳細については、ワーカースレッドとの連携セクションを参照してください。
バージョン 1#
これは診断レポートの最初のバージョンです。
設定#
レポート生成の追加のランタイム設定は、process.report の以下のプロパティを介して利用できます。
reportOnFatalError true の場合、致命的なエラーで診断レポートをトリガーします。デフォルトは false です。
reportOnSignal true の場合、シグナルで診断レポートをトリガーします。これはWindowsではサポートされていません。デフォルトは false です。
reportOnUncaughtException true の場合、未処理の例外で診断レポートをトリガーします。デフォルトは false です。
signal レポート生成の外部トリガーをインターセプトするために使用されるPOSIXシグナル識別子を指定します。デフォルトは 'SIGUSR2' です。
filename ファイルシステム内の出力ファイルの名前を指定します。stdout と stderr には特別な意味があります。これらを使用すると、レポートは関連する標準ストリームに書き込まれます。標準ストリームが使用される場合、directory の値は無視されます。URLはサポートされていません。デフォルトは、タイムスタンプ、PID、およびシーケンス番号を含む複合ファイル名です。
directory レポートが書き込まれるファイルシステムのディレクトリを指定します。URLはサポートされていません。デフォルトは、Node.jsプロセスの現在の作業ディレクトリです。
excludeNetwork 診断レポートから header.networkInterfaces を除外します。
// Trigger report only on uncaught exceptions.
process.report.reportOnFatalError = false;
process.report.reportOnSignal = false;
process.report.reportOnUncaughtException = true;
// Trigger report for both internal errors as well as external signal.
process.report.reportOnFatalError = true;
process.report.reportOnSignal = true;
process.report.reportOnUncaughtException = false;
// Change the default signal to 'SIGQUIT' and enable it.
process.report.reportOnFatalError = false;
process.report.reportOnUncaughtException = false;
process.report.reportOnSignal = true;
process.report.signal = 'SIGQUIT';
// Disable network interfaces reporting
process.report.excludeNetwork = true;
モジュール初期化時の設定は、環境変数を介しても利用できます。
NODE_OPTIONS="--report-uncaught-exception \
--report-on-fatalerror --report-on-signal \
--report-signal=SIGUSR2 --report-filename=./report.json \
--report-directory=/home/nodeuser"
特定のAPIドキュメントは、process APIドキュメントセクションにあります。
ワーカースレッドとの連携#
Worker スレッドは、メインスレッドと同じ方法でレポートを作成できます。
レポートには、現在のスレッドの子であるすべてのワーカーに関する情報が workers セクションの一部として含まれ、各ワーカーは標準のレポート形式でレポートを生成します。
レポートを生成しているスレッドは、ワーカースレッドからのレポートが完了するのを待ちます。ただし、実行中のJavaScriptとイベントループの両方がレポートを生成するために中断されるため、通常、この遅延は低いです。