[[376545]]

Diagnostic report 是 Node.js v14.x 提供的一個(gè)穩(wěn)定功能，在某些情況下會(huì)生成一個(gè) JSON 格式的診斷報(bào)告，可用于開發(fā)、測試、生產(chǎn)環(huán)境。報(bào)告會(huì)提供有價(jià)值的信息，包括：JavaScript 和本機(jī)堆棧信息、堆統(tǒng)計(jì)信息、平臺信息、資源使用情況等，幫助用戶快速追蹤問題。

生成診斷報(bào)告

提供了多種觸發(fā)診斷報(bào)告的時(shí)機(jī)，包括：API 調(diào)用的方式觸發(fā)、針對未捕獲的異常觸發(fā)、用戶信號觸發(fā)、致命錯(cuò)誤導(dǎo)致應(yīng)用程序終止觸發(fā)。

API 觸發(fā)

調(diào)用 writeReport() 方法，會(huì)立即生成一份診斷報(bào)告，該方法可以寫在僅當(dāng)你需要診斷報(bào)告時(shí)調(diào)用，以獲取所需的信息。

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

報(bào)告默認(rèn)目錄：Node.js 進(jìn)程當(dāng)前工作目錄報(bào)告默認(rèn)名稱：YYYYMMDD.HHMMSS.PID.SEQUENCE.txt

未捕獲錯(cuò)誤觸發(fā)

當(dāng)程序遇到未捕獲錯(cuò)誤時(shí)主動(dòng)觸發(fā)，需要在啟動(dòng)服務(wù)時(shí)加上 --report-uncaught-exception 標(biāo)志，例如：node --report-uncaught-exception app.js

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

信號觸發(fā)

正在運(yùn)行的 Node.js 進(jìn)程在接收到特定的信號后生成診斷報(bào)告，默認(rèn)的信號為 -SIGUSR2，同樣在啟動(dòng)服務(wù)時(shí)加上 --report-on-signal 標(biāo)志。

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

啟動(dòng)服務(wù) node --report-on-signal app.js 之后觸發(fā)信號 kill -SIGUSR2 55800 會(huì)看到如下信息：

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

基于信號的報(bào)告生成，目前 Windows 系統(tǒng)是不支持的。通常無需修改觸發(fā)報(bào)告的信號，如果 -SIGUSR2 信號已用途其它用途，可通過 --report-signal 標(biāo)志修改，例如在啟動(dòng)服務(wù)時(shí)這樣執(zhí)行：node --report-on-signal --report-signal SIGPIPE app.js

致命錯(cuò)誤導(dǎo)致應(yīng)用程序終止觸發(fā)

在啟動(dòng)服務(wù)時(shí)上 --report-on-fatalerror 標(biāo)志，當(dāng)程序發(fā)生一些致命錯(cuò)誤，例如內(nèi)存泄漏、Node.js 運(yùn)行時(shí)的內(nèi)部錯(cuò)誤等也會(huì)觸發(fā)生成診斷報(bào)告。以下是一個(gè)觸發(fā)內(nèi)存泄漏的例子：

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) 

用例分析

事件循環(huán)計(jì)時(shí)器(timer)句柄信息

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

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

診斷報(bào)告會(huì)有很多信息，我們要看 timer 的信息，定時(shí)器屬于事件循環(huán)的階段之一，所以定位到 libuv 這個(gè)數(shù)組里，以下報(bào)告則展示其句柄信息 is_active 就是活動(dòng)的，firesInMsFromNow 是該計(jì)時(shí)器的觸發(fā)還需要多長時(shí)間，當(dāng)前示例大約還要 9 秒多執(zhí)行。

"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 開發(fā)的一款工具，用于簡化 Node.js 的診斷報(bào)告的使用，使用它在某些情況下可幫助我們快速定位問題。首先全局安裝它，如下命令，之后會(huì)生成一個(gè)全局的可執(zhí)行命令 rtk

npm install report-toolkit --global 

inspect 命令

inspect 命令用于自動(dòng)發(fā)現(xiàn) Node.js 診斷報(bào)告中的潛在問題，如果檢測出問題會(huì)輸出一條信息，可能是警告。

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)); // 大內(nèi)存占用 
  print(); 
}, 1000) 

執(zhí)行 node --report-on-fatalerror test.js 后過一小會(huì)報(bào) avaScript heap out of memory 錯(cuò)誤同時(shí)會(huì)生成一份診斷報(bào)告，下面是我們使用 rtk 診斷工具檢測得到如下結(jié)果：

diff 命令diff 命令正如它的名字一樣，是用來比較多個(gè)報(bào)告之間的不同。

關(guān)于診斷報(bào)告工具 report-toolkit 的更多使用指南參考 report-toolkit Quick Start。

Reference

• Node.js 14 版本：新的診斷工具、功能和性能增強(qiáng)
• 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