pm2-perfmonitor 1.2.1 → 2.1.1

package/README.md

@@ -5,28 +5,44 @@ A pm2 module for performance monitor.
 # Features
 
 - Automatically detect **zombie** processes and restart it.
-- Monitor the number of zombie process restarts (pm2 monit).
+- Monitor the number of zombie process restarts (`pm2 monit`).
+- [Added in v2] Support **CPU overload** protection (automatic restart + `perf` collection).
+- [Added in v2] Monitor the number of CPU Overload process restarts (`pm2 monit`).
 
 # Installation
 
 ```bash
+# install or update
 $ pm2 install pm2-perfmonitor
+
+# uninstall
+$ pm2 uninstall pm2-perfmonitor
 ```
 
 > NOTE: the command is `pm2 install` NOT `npm install`
 
 # Configure
 
-|            Property             | Default Value |                                     Description                                      |
-| :-----------------------------: | :-----------: | :----------------------------------------------------------------------------------: |
-|            `enabled`            |    `true`     |                        Specify whether to enable this module                         |
-|          `excludeApps`          |       -       |       Specify the application name that needs to be excluded from guardianship       |
-|          `includeApps`          |       -       |                Specify the application name that needs to be guarded                 |
-|        `workerInterval`         |    `60000`    |                          Timed task execution interval (ms)                          |
-|        `zombieDetection`        |    `true`     |                 Specify whether to enable zombie process protection                  |
-|         `zombieMaxHits`         |     `10`      |              Specify the maximum occurrence frequency of zombie status               |
-| `autoRestartWhenZombieDetected` |    `true`     |              Specify whether to automatically restart zombie processes               |
-|       `zombieMaxRestarts`       |      `0`      | The maximum number of zombie process restarts can be set to `0` to indicate no limit |
+|            Property             |      Defaults       |                                               Description                                               |  Supported   |
+| :-----------------------------: | :-----------------: | :-----------------------------------------------------------------------------------------------------: | :----------: |
+|            `enabled`            |       `true`        |                                  Specify whether to enable this module                                  | v1 and above |
+|          `excludeApps`          |          -          |                Specify the application name that needs to be excluded from guardianship                 | v1 and above |
+|          `includeApps`          |          -          |                          Specify the application name that needs to be guarded                          | v1 and above |
+|        `workerInterval`         |       `60000`       |                                   Timed task execution interval (ms)                                    | v1 and above |
+|        `zombieDetection`        |       `true`        |                           Specify whether to enable zombie process protection                           | v1 and above |
+|         `zombieMaxHits`         |        `10`         |                        Specify the maximum occurrence frequency of zombie status                        | v1 and above |
+| `autoRestartWhenZombieDetected` |       `true`        |                        Specify whether to automatically restart zombie processes                        | v1 and above |
+|       `zombieMaxRestarts`       |         `0`         |      Specify the maximum number of restarts for zombie processes (set to `0` to indicate no limit)      | v1 and above |
+|     `cpuOverloadDetection`      |       `false`       |                            Specify whether to enable CPU overload protection                            |      v2      |
+|     `cpuOverloadThreshold`      |        `90`         |                           Specify the threshold for determining CPU overload                            |      v2      |
+|      `cpuOverloadMaxHits`       |         `5`         | Maximum number of consecutive occurrences of CPU overload allowed (automatically restarts when reached) |      v2      |
+| `enableNodeInspectorCollection` |       `false`       |                    Specify whether to enable `node:inspector` performance collection                    |      v2      |
+|  `nodeInspectorSampleDuration`  |        `10`         |                  Specify the performance collection duration (s) for `node:inspector`                   |      v2      |
+|     `enablePerfCollection`      |       `false`       |                         Specify whether to enable `perf` performance collection                         |      v2      |
+|    `perfReportGenerationDir`    | `/var/log/pm2/perf` |                   Specify the directory for generating performance reports for `perf`                   |      v2      |
+|         `flamegraphDir`         |  `/opt/FlameGraph`  |                    Specify the directory for `flamegraph` flame map generation tool                     |      v2      |
+|      `perfSampleDuration`       |        `10`         |                              Specify the sampling duration (s) for `perf`                               |      v2      |
+|      `perfSampleFrequency`      |        `99`         |                             Specify the sampling frequency (Hz) for `perf`                              |      v2      |
 
 # How to set these values ?
 
@@ -36,3 +52,4 @@ After having installed the module you have to type : `pm2 set pm2-perfmonitor:<p
 
 - `pm2 set pm2-perfmonitor:includeApps myNuxtApp1, myNextApp2` （Only detect applications named `myNuxtApp1` and `myNextApp2`）
 - `pm2 set pm2-perfmonitor:workerInterval 120000` （Check every `2` minutes）
+- `pm2 set pm2-perfmonitor:cpuOverloadDetection true`（enable **CPU overload** protection）

package/lib/app.js

@@ -1,39 +1,15 @@
 const pmx = require('pmx')
 const pm2 = require('pm2')
-const { getPm2ListAsync } = require('./pm2-extra')
-const { parseParamToArray, parseParamToNumber, parseBool } = require('./utils')
-
-const defaultOptions = {
-  enabled: true,
-  /**
-   * 排除的 app 名
-   */
-  excludeApps: [],
-  /**
-   * 包含的 app 名
-   */
-  includeApps: [],
-  /**
-   * 定时检测间隔（ms）
-   */
-  workerInterval: 60000,
-  /**
-   * 是否开启僵尸进程守护
-   */
-  zombieDetection: true,
-  /**
-   * 僵尸状态最大出现次数
-   */
-  zombieMaxHits: 10,
-  /**
-   * 僵尸状态达到最大容忍度时，是否自动重启僵尸进程
-   */
-  autoRestartWhenZombieDetected: true,
-  /**
-   * 僵尸进程最大重启次数，设置为0表示不限制
-   */
-  zombieMaxRestarts: 0,
-}
+const { listAppsAsync, restartAppAsync } = require('./pm2-extra')
+const {
+  parseParamToArray,
+  parseParamToNumber,
+  parseBool,
+  sleepAsync,
+} = require('./utils')
+const { defaultOptions } = require('./defaults')
+const { sendMessage } = require('./message')
+const { performPerfSampling } = require('./perf-sampler')
 
 const conf = pmx.initModule({}, (err, incomingConf) => {
   if (err) {
@@ -60,11 +36,29 @@ const AUTO_RESTART_WHEN_ZOMBIE_DETECTED = parseBool(
 const ZOMBIE_MAX_HITS = parseParamToNumber(conf.zombieMaxHits)
 const ZOMBIE_MAX_RESTARTS = parseParamToNumber(conf.zombieMaxRestarts)
 
+const cpuOverloadDetection = parseBool(conf.cpuOverloadDetection)
+const cpuOverloadThreshold = parseParamToNumber(conf.cpuOverloadThreshold)
+const cpuOverloadMaxHits = parseParamToNumber(conf.cpuOverloadMaxHits)
+const enablePerfCollection = parseBool(conf.enablePerfCollection)
+const perfReportGenerationDir = conf.perfReportGenerationDir
+const flamegraphDir = conf.flamegraphDir
+const perfSampleDuration = parseParamToNumber(conf.perfSampleDuration)
+const perfSampleFrequency = parseParamToNumber(conf.perfSampleFrequency)
+const enableNodeInspectorCollection = parseBool(
+  conf.enableNodeInspectorCollection,
+)
+const nodeInspectorSampleDuration = parseParamToNumber(
+  conf.nodeInspectorSampleDuration,
+)
+
 // 存储每个进程的 CPU 采样历史（pm_id -> [cpu1, cpu2, ...]）
-const cpuHistory = new Map()
+const zombieCpuHistory = new Map()
 const zombieRestartHistory = new Map()
 const restartFailedHistory = new Map()
 
+const cpuOverloadHistory = new Map()
+const cpuOverloadRestartHistory = new Map()
+
 /**
  * @param {'log' | 'info' | 'error' | 'warn'} type
  *
@@ -82,82 +76,129 @@ const isZombie = (history) => {
 }
 
 /**
- * check zombie process
+ * @param { number[] } history
  */
-const zombieProcessChecker = async () => {
-  if (!ZOMBIE_DETECTION) return
+const isCpuOverload = (history) => {
+  return (
+    history.length >= cpuOverloadMaxHits &&
+    history.every((v) => v >= cpuOverloadThreshold)
+  )
+}
+
+/**
+ * @param { number } pm_id
+ * @param { number  } appCpuUsage
+ * @returns { number[] } 对应 pm_id 的 CPU 使用率数组
+ */
+const setZombieCpuHistory = (pm_id, appCpuUsage) => {
+  if (!zombieCpuHistory.has(pm_id)) {
+    zombieCpuHistory.set(pm_id, [])
+  }
+
+  const history = zombieCpuHistory.get(pm_id)
+
+  history.push(appCpuUsage)
+
+  // 只保留最近 ZOMBIE_MAX_HITS 次记录
+  if (history.length > ZOMBIE_MAX_HITS) {
+    history.shift()
+  }
+
+  return history
+}
+
+/**
+ * @param { number } pm_id
+ * @param { number  } appCpuUsage
+ * @returns { number[] } 对应 pm_id 的 CPU 使用率数组
+ */
+const setCpuOverloadHistory = (pm_id, appCpuUsage) => {
+  if (!cpuOverloadHistory.has(pm_id)) {
+    cpuOverloadHistory.set(pm_id, [])
+  }
 
+  const history = cpuOverloadHistory.get(pm_id)
+
+  history.push(appCpuUsage)
+
+  // 只保留最近 x 次记录
+  if (history.length > cpuOverloadMaxHits) {
+    history.shift()
+  }
+
+  return history
+}
+
+const setRestartFailedHistory = (pm_id) => {
+  if (!restartFailedHistory.has(pm_id)) {
+    restartFailedHistory.set(pm_id, 1)
+  } else {
+    restartFailedHistory.set(pm_id, restartFailedHistory.get(pm_id) + 1)
+  }
+}
+
+/**
+ * check process
+ */
+const processChecker = async () => {
   try {
-    const apps = await getPm2ListAsync()
+    const apps = await listAppsAsync()
 
-    apps.forEach((app) => {
-      const { name, pm_id, monit, pm2_env } = app
+    for (const app of apps) {
+      const { name, pm_id, monit, pm2_env, pid } = app
 
       const appStatus = pm2_env?.status
       const appCpuUsage = monit?.cpu || 0
 
+      // 非目标应用，跳过
       if (
         MODULE_NAME === name ||
         (INCLUDE_APPS.length > 0 && !INCLUDE_APPS.includes(name)) ||
         (EXCLUDE_APPS.length > 0 && EXCLUDE_APPS.includes(name))
       ) {
-        return
+        continue
       }
 
-      // 2. 只处理 online 状态的进程
+      // 只处理 online 状态的进程
       if (appStatus !== 'online') {
         // 进程不在 online 状态时，清空其历史记录，避免干扰
-        cpuHistory.delete(pm_id)
-        return
-      }
+        zombieCpuHistory.delete(pm_id)
+        cpuOverloadHistory.delete(pm_id)
 
-      if (!cpuHistory.has(pm_id)) {
-        cpuHistory.set(pm_id, [])
+        continue
       }
 
-      const history = cpuHistory.get(pm_id)
-
-      history.push(appCpuUsage)
+      const history = setZombieCpuHistory(pm_id, appCpuUsage)
+      const history2 = setCpuOverloadHistory(pm_id, appCpuUsage)
 
-      // 只保留最近 ZOMBIE_MAX_HITS 次记录
-      if (history.length > ZOMBIE_MAX_HITS) {
-        history.shift()
+      // 发送消息通知对应应用进程，采样 CPU 性能
+      if (enableNodeInspectorCollection) {
+        if (appCpuUsage >= cpuOverloadThreshold) {
+          await sendMessage(pm_id, 'cpu-profile-start')
+          await sleepAsync(nodeInspectorSampleDuration * 1000)
+          await sendMessage(pm_id, 'cpu-profile-stop')
+        }
       }
 
-      // 4. 判断是否为僵尸：最近 ZOMBIE_MAX_HITS 次全是 0%
-
-      if (isZombie(history)) {
-        logger('info', `Zombie detected: ${name} (pm_id: ${pm_id})`)
+      // 判断是否为僵尸：最近 ZOMBIE_MAX_HITS 次全是 0%
+      if (ZOMBIE_DETECTION && isZombie(history)) {
+        logger(
+          'info',
+          `Zombie detected: ${name} (pm_id: ${pm_id}, pid: ${app.pid})`,
+        )
 
         if (AUTO_RESTART_WHEN_ZOMBIE_DETECTED) {
           if (
             ZOMBIE_MAX_RESTARTS > 0 &&
             zombieRestartHistory.get(pm_id) >= ZOMBIE_MAX_RESTARTS
           ) {
-            return
+            continue
           }
 
           logger('info', 'restarting...')
 
-          pm2.restart(pm_id, (restartErr) => {
-            if (restartErr) {
-              logger(
-                'error',
-                `Restart failed for ${name} (pm_id: ${pm_id}):`,
-                restartErr,
-              )
-
-              if (!restartFailedHistory.has(pm_id)) {
-                restartFailedHistory.set(pm_id, 1)
-              } else {
-                restartFailedHistory.set(
-                  pm_id,
-                  restartFailedHistory.get(pm_id) + 1,
-                )
-              }
-
-              return
-            }
+          try {
+            await restartAppAsync(pm_id)
 
             if (!zombieRestartHistory.has(pm_id)) {
               zombieRestartHistory.set(pm_id, 1)
@@ -169,15 +210,71 @@ const zombieProcessChecker = async () => {
 
             logger(
               'info',
-              `Restarted ${name} (pm_id: ${pm_id}) successfully!!! Restarted ${zombieRestartHistory.get(pm_id)} times`,
+              `[ZOMBIE] Restarted ${name} (pm_id: ${pm_id}) successfully!!! Restarted ${zombieRestartHistory.get(pm_id)} times`,
             )
 
             // 重启后清除该进程的历史记录，避免刚重启又被判定为僵尸
-            cpuHistory.delete(pm_id)
+            zombieCpuHistory.delete(pm_id)
+          } catch (restartErr) {
+            logger(
+              'error',
+              `[ZOMBIE] Restart failed for ${name} (pm_id: ${pm_id}):`,
+              restartErr,
+            )
+
+            setRestartFailedHistory(pm_id)
+          }
+        }
+      }
+      // CPU 是否持续过载
+      else if (cpuOverloadDetection && isCpuOverload(history2)) {
+        logger(
+          'info',
+          `CPU Overload detected: ${name} (pm_id: ${pm_id}, pid: ${app.pid})`,
+        )
+
+        if (enablePerfCollection) {
+          await performPerfSampling({
+            pid,
+            moduleName: MODULE_NAME,
+            perfDir: perfReportGenerationDir,
+            flamegraphDir,
+            sampleDuration: perfSampleDuration,
+            sampleFrequency: perfSampleFrequency,
           })
         }
+
+        try {
+          logger('info', 'restarting...')
+
+          await restartAppAsync(pm_id)
+
+          if (!cpuOverloadRestartHistory.has(pm_id)) {
+            cpuOverloadRestartHistory.set(pm_id, 1)
+          } else {
+            cpuOverloadRestartHistory.set(
+              pm_id,
+              cpuOverloadRestartHistory.get(pm_id) + 1,
+            )
+          }
+
+          logger(
+            'info',
+            `[CPU OVERLOAD] Restarted ${name} (pm_id: ${pm_id}) successfully!!! Restarted ${cpuOverloadRestartHistory.get(pm_id)} times`,
+          )
+
+          cpuOverloadHistory.delete(pm_id)
+        } catch (restartErr) {
+          logger(
+            'error',
+            `[CPU OVERLOAD] Restart failed for ${name} (pm_id: ${pm_id}):`,
+            restartErr,
+          )
+
+          setRestartFailedHistory(pm_id)
+        }
       }
-    })
+    }
   } catch (err) {
     logger('error', err)
   }
@@ -196,10 +293,10 @@ const runModule = () => {
 
     logger('info', 'Connected to PM2, starting monitor...')
 
-    zombieProcessChecker()
+    processChecker()
 
     setInterval(() => {
-      zombieProcessChecker()
+      processChecker()
     }, WORKER_INTERVAL)
   })
 
@@ -243,7 +340,7 @@ const runModule = () => {
     value: () => {
       const res = []
 
-      for (const [pmId, arr] of cpuHistory) {
+      for (const [pmId, arr] of zombieCpuHistory) {
         if (isZombie(arr)) {
           res.push(pmId)
         }
@@ -254,6 +351,40 @@ const runModule = () => {
       return res.join(',')
     },
   })
+
+  Probe.metric({
+    name: 'CPU Overload Restarts',
+    value: () => {
+      const res = []
+
+      for (const [k, v] of cpuOverloadRestartHistory) {
+        if (v > 0) {
+          res.push([k, v])
+        }
+      }
+
+      if (!res.length) return 'N/A'
+
+      return res.map((v) => `[${v[0]}]:${v[1]}`).join(' ; ')
+    },
+  })
+
+  Probe.metric({
+    name: 'CPU Overload Processes',
+    value: () => {
+      const res = []
+
+      for (const [pmId, arr] of cpuOverloadHistory) {
+        if (isCpuOverload(arr)) {
+          res.push(pmId)
+        }
+      }
+
+      if (!res.length) return 'N/A'
+
+      return res.join(',')
+    },
+  })
 }
 
 runModule()

package/lib/defaults.js

@@ -0,0 +1,85 @@
+const defaultOptions = {
+  enabled: true,
+  /**
+   * 排除的 app 名
+   */
+  excludeApps: [],
+  /**
+   * 包含的 app 名
+   */
+  includeApps: [],
+  /**
+   * 定时检测间隔（ms）
+   */
+  workerInterval: 60000,
+  /**
+   * 是否开启僵尸进程守护
+   */
+  zombieDetection: true,
+  /**
+   * 僵尸状态最大出现次数
+   */
+  zombieMaxHits: 10,
+  /**
+   * 僵尸状态达到最大容忍度时，是否自动重启僵尸进程
+   */
+  autoRestartWhenZombieDetected: true,
+  /**
+   * 僵尸进程最大重启次数，设置为0表示不限制
+   */
+  zombieMaxRestarts: 0,
+
+  /**
+   * 是否开启 CPU 过载守护
+   */
+  cpuOverloadDetection: false,
+
+  /**
+   * 判定 CPU 过载阈值
+   */
+  cpuOverloadThreshold: 90,
+
+  /**
+   * 允许 CPU 过载最大连续出现次数，达到时自动重启
+   */
+  cpuOverloadMaxHits: 5,
+
+  /**
+   * 是否开启 perf 性能采集
+   */
+  enablePerfCollection: false,
+
+  /**
+   * 性能报告生成目录
+   */
+  perfReportGenerationDir: '/var/log/pm2/perf',
+
+  /**
+   * flamegraph 火焰图生成工具目录
+   */
+  flamegraphDir: '/opt/FlameGraph',
+
+  /**
+   * perf 采样持续时间 (s)
+   */
+  perfSampleDuration: 10,
+
+  /**
+   * perf 采样频率 (Hz)
+   */
+  perfSampleFrequency: 99,
+
+  /**
+   * 是否开启 node:inspector 性能采集
+   */
+  enableNodeInspectorCollection: false,
+
+  /**
+   * node:inspector 性能采集持续时间 (s)
+   */
+  nodeInspectorSampleDuration: 10,
+}
+
+module.exports = {
+  defaultOptions,
+}

package/lib/message.js

@@ -0,0 +1,35 @@
+const pm2 = require('pm2')
+
+/**
+ * @param { number } pm_id - pm2 应用id
+ * @param { string } eventName - 事件名
+ * @param { object } [data] - 发送的数据
+ * @returns { Promise<void> }
+ */
+const sendMessage = (pm_id, eventName, data) => {
+  return new Promise((resolve, reject) => {
+    pm2.sendDataToProcessId(
+      pm_id,
+      {
+        id: pm_id,
+        type: 'process:msg',
+        topic: true,
+        data: {
+          event: `pm2-perfmonitor:${eventName}`,
+          data,
+        },
+      },
+      (err) => {
+        if (err) {
+          return reject(err)
+        }
+
+        resolve()
+      },
+    )
+  })
+}
+
+module.exports = {
+  sendMessage,
+}

package/lib/perf-sampler.js

@@ -0,0 +1,246 @@
+const fs = require('fs-extra')
+const path = require('path')
+
+let execaCommandCache
+
+/**
+ * 获取 execa 函数（缓存）
+ * @returns { import('execa')['execa'] }
+ */
+const getExeca = async () => {
+  if (!execaCommandCache) {
+    const execaModule = await import('execa')
+    execaCommandCache = execaModule.execa
+  }
+  return execaCommandCache
+}
+
+/**
+ * 执行命令（不通过 shell，直接使用参数数组）
+ * @param {string} cmd - 命令名称
+ * @param {string[]} args - 参数列表
+ * @param {object} options - execa 选项
+ * @returns {Promise<boolean>} 是否成功
+ */
+const execCommand = async (cmd, args, options = {}) => {
+  try {
+    const execa = await getExeca()
+    await execa(cmd, args, {
+      stdio: 'inherit',
+      ...options,
+    })
+    return true
+  } catch (err) {
+    console.error(`Command failed: ${cmd} ${args.join(' ')}`, err.message)
+    return false
+  }
+}
+
+/**
+ * 生成安全的文件时间戳（不依赖区域）
+ */
+const getSafeTimestamp = () => {
+  const now = new Date()
+  const y = now.getFullYear()
+  const m = String(now.getMonth() + 1).padStart(2, '0')
+  const d = String(now.getDate()).padStart(2, '0')
+  const h = String(now.getHours()).padStart(2, '0')
+  const min = String(now.getMinutes()).padStart(2, '0')
+  const s = String(now.getSeconds()).padStart(2, '0')
+  return `${y}${m}${d}_${h}${min}${s}`
+}
+
+/**
+ * 执行 Perf 采样并生成火焰图
+ * @param {Object} options - 配置项
+ * @param {number} options.pid - 进程 PID
+ * @param {string} options.moduleName - 模块名（用于日志前缀）
+ * @param {string} options.perfDir - Perf 文件存储目录（当未提供 perfDataFile 时用于生成默认路径）
+ * @param {string} options.flamegraphDir - 火焰图工具目录
+ * @param {number} [options.sampleDuration=10] - 采样时长（秒）
+ * @param {number} [options.sampleFrequency=99] - 采样频率（Hz）
+ * @param {string} [options.perfDataFile] - 自定义 perf 数据文件路径（若未提供则自动生成）
+ * @param {boolean} [options.keepPerfData=false] - 是否保留原始 perf 数据文件（默认 false，即采样后删除）
+ */
+const performPerfSampling = async ({
+  pid,
+  moduleName,
+  perfDir,
+  flamegraphDir,
+  sampleDuration = 10,
+  sampleFrequency = 99,
+  perfDataFile: customPerfDataFile,
+  keepPerfData = false,
+}) => {
+  const logger = (type, ...args) => {
+    console[type](`[${moduleName}]`, ...args)
+  }
+
+  // --- 参数校验 ---
+  if (!perfDir) {
+    logger('error', 'perfDir cannot be empty')
+    return
+  }
+  if (!flamegraphDir) {
+    logger('error', 'flamegraphDir cannot be empty')
+    return
+  }
+
+  // PID 必须为数字且为正整数
+  const pidNum = Number(pid)
+  if (!Number.isInteger(pidNum) || pidNum <= 0) {
+    logger('error', `Invalid PID: ${pid} – must be a positive integer`)
+    return
+  }
+
+  const finalDuration =
+    typeof sampleDuration === 'number' && sampleDuration > 0
+      ? sampleDuration
+      : 10
+  const finalFrequency =
+    typeof sampleFrequency === 'number' && sampleFrequency > 0
+      ? sampleFrequency
+      : 99
+
+  // 确保 perf 目录存在（用于默认路径，或自定义路径的父目录）
+  try {
+    await fs.ensureDir(perfDir)
+    logger('info', `Perf directory ready: ${perfDir}`)
+  } catch (err) {
+    logger('error', `Failed to create perf directory: ${err.message}`)
+    return
+  }
+
+  // 检查  perf 权限
+  try {
+    const execa = await getExeca()
+
+    await execa('perf', ['--version'], { timeout: 5000 })
+
+    logger('info', 'Perf permission check passed')
+  } catch (err) {
+    logger('error', `Perf permission check failed: ${err.message}`)
+    logger(
+      'error',
+      'Please ensure the perf command is installed and the user has permission to run it.\n' +
+        'You can configure the system to allow non-root perf by setting:\n' +
+        '  echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid\n' +
+        '  sudo setcap cap_sys_admin+ep $(which perf)',
+    )
+    return // 无权限则直接退出
+  }
+
+  // 生成时间戳（仅当需要默认路径时）
+  const timestamp = getSafeTimestamp()
+
+  // 确定 perf 数据文件路径
+  let perfDataFile
+  if (customPerfDataFile) {
+    perfDataFile = customPerfDataFile
+    // 确保自定义路径的父目录存在
+    const parentDir = path.dirname(perfDataFile)
+    try {
+      await fs.ensureDir(parentDir)
+    } catch (err) {
+      logger(
+        'error',
+        `Failed to create directory for custom perfDataFile: ${err.message}`,
+      )
+      return
+    }
+  } else {
+    perfDataFile = path.join(perfDir, `perf.${pidNum}.${timestamp}.data`)
+  }
+
+  // 定义其他文件路径（基于 perfDir 和时间戳，与 perfDataFile 解耦）
+  const perfStacksFile = path.join(
+    perfDir,
+    `perf.${pidNum}.${timestamp}.stacks`,
+  )
+  const perfFoldedFile = path.join(
+    perfDir,
+    `perf.${pidNum}.${timestamp}.folded`,
+  )
+  const perfSvgFile = path.join(perfDir, `perf.${pidNum}.${timestamp}.svg`)
+
+  try {
+    logger(
+      'info',
+      `PID:${pidNum} Starting perf sampling (${finalDuration}s, ${finalFrequency}Hz)`,
+    )
+
+    // --- Step 1: perf record ---
+    const recordOk = await execCommand('perf', [
+      'record',
+      '-o',
+      perfDataFile,
+      '-F',
+      String(finalFrequency),
+      '-p',
+      String(pidNum),
+      '-g',
+      '--',
+      'sleep',
+      String(finalDuration),
+    ])
+    if (!recordOk) return
+
+    // --- Step 2: perf script 导出为文本堆栈 ---
+    const scriptOk = await execCommand('perf', ['script', '-i', perfDataFile], {
+      stdout: fs.createWriteStream(perfStacksFile),
+    })
+    if (!scriptOk) return
+
+    logger('info', `PID:${pidNum} Perf sampling completed: ${perfStacksFile}`)
+
+    // 根据 keepPerfData 决定是否删除原始数据文件
+    if (!keepPerfData) {
+      await fs.remove(perfDataFile).catch(() => {})
+    }
+
+    // --- Step 3: 检查火焰图工具 ---
+    const stackcollapsePath = path.join(flamegraphDir, 'stackcollapse-perf.pl')
+    const flamegraphPath = path.join(flamegraphDir, 'flamegraph.pl')
+
+    const isStackcollapseValid = await fs
+      .access(stackcollapsePath, fs.constants.X_OK)
+      .then(() => true)
+      .catch(() => false)
+    const isFlamegraphValid = await fs
+      .access(flamegraphPath, fs.constants.X_OK)
+      .then(() => true)
+      .catch(() => false)
+
+    if (isStackcollapseValid && isFlamegraphValid) {
+      // --- Step 4: 生成折叠文件 ---
+      const collapseOk = await execCommand(
+        stackcollapsePath,
+        [perfStacksFile],
+        {
+          stdout: fs.createWriteStream(perfFoldedFile),
+        },
+      )
+      if (!collapseOk) return
+
+      // --- Step 5: 生成 SVG 火焰图 ---
+      const flameOk = await execCommand(flamegraphPath, [perfFoldedFile], {
+        stdout: fs.createWriteStream(perfSvgFile),
+      })
+      if (flameOk) {
+        logger('info', `PID:${pidNum} Flame graph generated: ${perfSvgFile}`)
+      }
+    } else {
+      const missing = []
+      if (!isStackcollapseValid) missing.push('stackcollapse-perf.pl')
+      if (!isFlamegraphValid) missing.push('flamegraph.pl')
+      logger(
+        'info',
+        `PID:${pidNum} Skip flame graph – missing/not executable: ${missing.join(', ')}`,
+      )
+    }
+  } catch (err) {
+    logger('error', `PID:${pidNum} Perf sampling exception: ${err.message}`)
+  }
+}
+
+module.exports = { performPerfSampling }

package/lib/pm2-extra.js

@@ -3,7 +3,7 @@ const pm2 = require('pm2')
 /**
  * @returns { Promise<pm2.ProcessDescription[]> }
  */
-const getPm2ListAsync = () => {
+const listAppsAsync = () => {
   return new Promise((resolve, reject) => {
     pm2.list((err, apps) => {
       if (err) {
@@ -19,7 +19,7 @@ const getPm2ListAsync = () => {
  * @param { string | number} pm_id
  * @returns { Promise<void> }
  */
-const pm2StopAsync = (pm_id) => {
+const stopAppAsync = (pm_id) => {
   return new Promise((resolve, reject) => {
     pm2.stop(pm_id, (err) => {
       if (err) {
@@ -31,7 +31,24 @@ const pm2StopAsync = (pm_id) => {
   })
 }
 
+/**
+ * @param { string | number} pm_id
+ * @returns { Promise<void> }
+ */
+const restartAppAsync = (pm_id) => {
+  return new Promise((resolve, reject) => {
+    pm2.restart(pm_id, (err) => {
+      if (err) {
+        return reject(err)
+      }
+
+      resolve()
+    })
+  })
+}
+
 module.exports = {
-  getPm2ListAsync,
-  pm2StopAsync,
+  listAppsAsync,
+  stopAppAsync,
+  restartAppAsync,
 }

package/lib/utils.js

@@ -28,8 +28,18 @@ const parseBool = (value, defaultVal = false) => {
   return defaultVal
 }
 
+/**
+ * @param { number} duration - sleep duration (ms)
+ */
+const sleepAsync = (duration = 0) => {
+  return new Promise((resolve) => {
+    setTimeout(resolve, duration)
+  })
+}
+
 module.exports = {
   parseParamToArray,
   parseParamToNumber,
   parseBool,
+  sleepAsync,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pm2-perfmonitor",
-  "version": "1.2.1",
+  "version": "2.1.1",
   "description": "A pm2 module for performance monitoring. Automatically detect zombie processes and restart it",
   "author": {
     "name": "elenh",
@@ -20,8 +20,12 @@
   },
   "homepage": "https://github.com/yisibell/pm2-perfmonitor",
   "scripts": {
-    "start": "pm2 delete app1 || true && pm2 start ecosystem.app.config.cjs",
-    "dev": "pm2 start ecosystem.dev.config.cjs",
+    "start-or-restart:app": "pm2 startOrRestart ecosystem.app.config.cjs --update-env",
+    "start:app": "pm2 start ecosystem.app.config.cjs",
+    "restart:app": "pm2 restart ecosystem.app.config.cjs",
+    "delete-start:app": "pm2 delete app1 || true && pm2 start ecosystem.app.config.cjs",
+    "start": "node ./scripts/app.js --env=app",
+    "dev": "pm2 restart ecosystem.dev.config.cjs",
     "release": "changelogen --release && npm publish --access=public && git push --follow-tags"
   },
   "keywords": [
@@ -38,11 +42,14 @@
   ],
   "config": {},
   "dependencies": {
+    "execa": "^9.6.1",
+    "fs-extra": "^11.3.4",
     "pm2": "latest",
     "pmx": "latest"
   },
   "devDependencies": {
     "changelogen": "^0.6.2",
-    "cz-conventional-changelog": "^3.3.0"
+    "cz-conventional-changelog": "^3.3.0",
+    "minimist": "^1.2.8"
   }
-}
+}