用法

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。

报告也可以通过 JavaScript 应用程序的 API 调用触发：

process.report.writeReport();

此函数接受可选的额外参数 filename，其是写入报告的文件的名称。

process.report.writeReport('./foo.json');

此函数接受可选的额外参数 err，其是 Error 对象，将用作报告中打印的 JavaScript 堆栈的上下文。 当使用报告处理回调或异常句柄中的错误时，这允许报告包括原始错误的位置以及处理它的位置。

try {
  process.chdir('/non-existent-path');
} catch (err) {
  process.report.writeReport(err);
}
// 任何其他代码

如果文件名和错误对象都传给 writeReport()，则错误对象必须是第二个参数。

try {
  process.chdir('/non-existent-path');
} catch (err) {
  process.report.writeReport(filename, err);
}
// 任何其他代码

诊断报告的内容可以通过 JavaScript 应用程序的 API 调用作为 JavaScript 对象返回：

const report = process.report.getReport();
console.log(typeof report === 'object'); // true

// 类似于 process.report.writeReport() 输出
console.log(JSON.stringify(report, null, 2));

此函数接受可选的额外参数 err，其是 Error 对象，将用作报告中打印的 JavaScript 堆栈的上下文。

const report = process.report.getReport(new Error('custom error'));
console.log(typeof report === 'object'); // true

API 版本在从应用程序内部检查运行时状态时很有用，期望自我调整资源消耗、负载平衡、监控等。

报告的内容由包含事件类型、日期、时间、PID 和 Node.js 版本的标题部分、包含 JavaScript 和本机堆栈跟踪的部分、包含 V8 堆信息的部分、包含 libuv 句柄信息的部分和显示 CPU 和内存使用情况以及系统限制的操作系统平台信息部分。 可以使用 Node.js 交互式解释器触发的示例报告：

$ node
> process.report.writeReport();
Writing Node.js report to file: report.20181126.091102.8480.0.001.json
Node.js report completed
>

当写入报告时，将开始和结束消息发送到标准错误，并将报告的文件名返回给调用者。 默认文件名包括日期、时间、PID、和序列号。 如果为同一个 Node.js 进程多次生成，则序列号有助于将报告转储与运行时状态相关联

诊断报告有一个相关的个位数版本号（report.header.reportVersion），唯一代表报告格式。 添加或删除新键或更改值的数据类型时，版本号会增加。 报告版本定义在 LTS 版本中是一致的。

node --report-uncaught-exception --report-on-signal \
--report-on-fatalerror app.js

  • --report-uncaught-exception Enables report to be generated on un-caught exceptions. Useful when inspecting JavaScript stack in conjunction with native stack and other runtime environment data.

  • --report-on-signal Enables report to be generated upon receiving the specified (or predefined) signal to the running Node.js process. (See below on how to modify the signal that triggers the report.) Default signal is SIGUSR2. Useful when a report needs to be triggered from another program. Application monitors may leverage this feature to collect report at regular intervals and plot rich set of internal runtime data to their views.

Signal based report generation is not supported in Windows.

Under normal circumstances, there is no need to modify the report triggering signal. However, if SIGUSR2 is already used for other purposes, then this flag helps to change the signal for report generation and preserve the original meaning of SIGUSR2 for the said purposes.

  • --report-on-fatalerror Enables the report to be triggered on fatal errors (internal errors within the Node.js runtime, such as out of memory) that leads to termination of the application. Useful to inspect various diagnostic data elements such as heap, stack, event loop state, resource consumption etc. to reason about the fatal error.

  • --report-compact Write reports in a compact format, single-line JSON, more easily consumable by log processing systems than the default multi-line format designed for human consumption.

  • --report-directory Location at which the report will be generated.

  • --report-filename Name of the file to which the report will be written.

  • --report-signal Sets or resets the signal for report generation (not supported on Windows). Default signal is SIGUSR2.

A report can also be triggered via an API call from a JavaScript application:

process.report.writeReport();

This function takes an optional additional argument filename, which is the name of a file into which the report is written.

process.report.writeReport('./foo.json');

This function takes an optional additional argument err which is an Error object that will be used as the context for the JavaScript stack printed in the report. When using report to handle errors in a callback or an exception handler, this allows the report to include the location of the original error as well as where it was handled.

try {
  process.chdir('/non-existent-path');
} catch (err) {
  process.report.writeReport(err);
}
// Any other code

If both filename and error object are passed to writeReport() the error object must be the second parameter.

try {
  process.chdir('/non-existent-path');
} catch (err) {
  process.report.writeReport(filename, err);
}
// Any other code

The content of the diagnostic report can be returned as a JavaScript Object via an API call from a JavaScript application:

const report = process.report.getReport();
console.log(typeof report === 'object'); // true

// Similar to process.report.writeReport() output
console.log(JSON.stringify(report, null, 2));

This function takes an optional additional argument err, which is an Error object that will be used as the context for the JavaScript stack printed in the report.

const report = process.report.getReport(new Error('custom error'));
console.log(typeof report === 'object'); // true

The API versions are useful when inspecting the runtime state from within the application, in expectation of self-adjusting the resource consumption, load balancing, monitoring etc.

The content of the report consists of a header section containing the event type, date, time, PID, and Node.js version, sections containing JavaScript and native stack traces, a section containing V8 heap information, a section containing libuv handle information, and an OS platform information section showing CPU and memory usage and system limits. An example report can be triggered using the Node.js REPL:

$ node
> process.report.writeReport();
Writing Node.js report to file: report.20181126.091102.8480.0.001.json
Node.js report completed
>

When a report is written, start and end messages are issued to stderr and the filename of the report is returned to the caller. The default filename includes the date, time, PID, and a sequence number. The sequence number helps in associating the report dump with the runtime state if generated multiple times for the same Node.js process.

Diagnostic report has an associated single-digit version number (report.header.reportVersion), uniquely representing the report format. The version number is bumped when new key is added or removed, or the data type of a value is changed. Report version definitions are consistent across LTS releases.