[[376545]]

Diagnostic report 是 Node.js v14.x 提供的一個穩定功能，在某些情況下會生成一個 JSON 格式的診斷報告，可用于開發、測試、生產環境。報告會提供有價值的信息，包括：JavaScript 和本機堆棧信息、堆統計信息、平臺信息、資源使用情況等，幫助用戶快速追蹤問題。

生成診斷報告

提供了多種觸發診斷報告的時機，包括：API 調用的方式觸發、針對未捕獲的異常觸發、用戶信號觸發、致命錯誤導致應用程序終止觸發。

API 觸發

調用 writeReport() 方法，會立即生成一份診斷報告，該方法可以寫在僅當你需要診斷報告時調用，以獲取所需的信息。

const process = require('process'); 
process.report.writeReport(); 

報告默認目錄：Node.js 進程當前工作目錄報告默認名稱：YYYYMMDD.HHMMSS.PID.SEQUENCE.txt

未捕獲錯誤觸發

當程序遇到未捕獲錯誤時主動觸發，需要在啟動服務時加上 --report-uncaught-exception 標志，例如：node --report-uncaught-exception app.js

// app.js 
throw new Error('testerror') 

信號觸發

正在運行的 Node.js 進程在接收到特定的信號后生成診斷報告，默認的信號為 -SIGUSR2，同樣在啟動服務時加上 --report-on-signal 標志。

// app.js 
console.log(`process id: ${process.pid}`) 
setInterval(() => {}, 1000); 

啟動服務 node --report-on-signal app.js 之后觸發信號 kill -SIGUSR2 55800 會看到如下信息：

process id: 3512 
Writing Node.js report to file: report.20210113.211250.3512.0.001.json 
Node.js report completed 

基于信號的報告生成，目前 Windows 系統是不支持的。通常無需修改觸發報告的信號，如果 -SIGUSR2 信號已用途其它用途，可通過 --report-signal 標志修改，例如在啟動服務時這樣執行：node --report-on-signal --report-signal SIGPIPE app.js

致命錯誤導致應用程序終止觸發

在啟動服務時上 --report-on-fatalerror 標志，當程序發生一些致命錯誤，例如內存泄漏、Node.js 運行時的內部錯誤等也會觸發生成診斷報告。以下是一個觸發內存泄漏的例子：

const format = bytes => (bytes / 1024 / 1024).toFixed(2) + ' MB'; 
const print = () => { 
  const memoryUsage = process.memoryUsage(); 
  console.log(`heapTotal: ${format(memoryUsage.heapTotal)}, heapUsed: ${format(memoryUsage.heapUsed)}`); 
} 
const total = []; 
setInterval(() => { 
  total.push(new Array(20, 1024, 1024)); 
  print(); 
}, 1000) 

用例分析

事件循環計時器(timer)句柄信息

以下代碼就是每 10 秒中程序執行一次，你可以通過上面講的信號的方式在啟動之后獲取診斷報告。

console.log(process id: ${process.pid}) 
setInterval(() => {}, 1000 * 10); 

診斷報告會有很多信息，我們要看 timer 的信息，定時器屬于事件循環的階段之一，所以定位到 libuv 這個數組里，以下報告則展示其句柄信息 is_active 就是活動的，firesInMsFromNow 是該計時器的觸發還需要多長時間，當前示例大約還要 9 秒多執行。

"libuv": [ 
  { 
    "type": "timer", 
    "is_active": true, 
    "is_referenced": true, 
    "address": "0x0000000105804100", 
    "repeat": 0, 
    "firesInMsFromNow": 9067, 
    "expired": false 
  } 
] 

參考：Easily identify problems in Node.js applications with Diagnostic Report

診斷工具(report-toolkit)

report-toolkit 是 IBM 開發的一款工具，用于簡化 Node.js 的診斷報告的使用，使用它在某些情況下可幫助我們快速定位問題。首先全局安裝它，如下命令，之后會生成一個全局的可執行命令 rtk

npm install report-toolkit --global 

inspect 命令

inspect 命令用于自動發現 Node.js 診斷報告中的潛在問題，如果檢測出問題會輸出一條信息，可能是警告。

const format = function (bytes) { 
  return (bytes / 1024 / 1024).toFixed(2) + ' MB'; 
}; 
const print = function() { 
  const memoryUsage = process.memoryUsage(); 
  console.log(`heapTotal: ${format(memoryUsage.heapTotal)}, heapUsed: ${format(memoryUsage.heapUsed)}`); 
} 
const total = []; 
setInterval(function() { 
  total.push(new Array(20 * 1024 * 1024)); // 大內存占用 
  print(); 
}, 1000) 

執行 node --report-on-fatalerror test.js 后過一小會報 avaScript heap out of memory 錯誤同時會生成一份診斷報告，下面是我們使用 rtk 診斷工具檢測得到如下結果：

diff 命令diff 命令正如它的名字一樣，是用來比較多個報告之間的不同。

關于診斷報告工具 report-toolkit 的更多使用指南參考 report-toolkit Quick Start。

Reference

• Node.js 14 版本：新的診斷工具、功能和性能增強
• Easily identify problems in Node.js applications with Diagnostic Report
• Introducing report-toolkit for Node.js Diagnostic Reports
• Node.js latest v14.x Diagnostic report