@step-monitor/core NPM

Step Monitor

简介

一个轻量级的步骤监控工具，用于追踪和记录多步骤流程的执行状态。

功能特点

🌳 支持多层级步骤嵌套
🔄 异步流程监控
📝 自动记录每个步骤的状态
⏱️ 记录执行时间
🎯 支持自定义数据存储
🔍 详细的输入输出追踪
🔁 支持流程断点恢复

安装

npm install @step-monitor/core

快速开始

import { StepMonitor,type MonitorRecord,type StepRecord } from "@step-monitor/core";

// 创建监控器实例
const monitor = new StepMonitor({
   // monitor.stepStart() 时会调用 insertMonitor
  insertStep: async (step: StepRecord): Promise<{ id: string }> => ({ id: "1" }),
  // monitor.stepEnd() 时会调用 updateStep
  updateStep: async (step: StepRecord): Promise<{ id: string }> => ({ id: step.id }),
  // monitor.start() 时会调用 insertMonitor
  insertMonitor: async (monitor: MonitorRecord): Promise<{ id: string }> => ({ id: "1" }),
  // monitor.end() 时会调用 updateMonitor
  updateMonitor: async (monitor: MonitorRecord): Promise<{ id: string }> => ({ id: monitor.id }),
  // monitor.recover() 时会调用 getMonitor
  getMonitor: async (monitorId: string): Promise<MonitorRecord | null> => null,
  // monitor.recover() 时会调用 getMonitorSteps
  getMonitorSteps: async (monitorId: string): Promise<StepRecord[]> => [],
});

// 使用监控器
async function example() {
  let currentMonitor;
  try {
    // 开始监控
    currentMonitor = (await monitor.start("示例流程"));

    // 执行顶级步骤
    const step1 = await monitor.stepStart("步骤1");
    await monitor.stepEnd(step1.step_id, { result: "ok" });

    // 执行带子步骤的步骤
    const step2 = await monitor.stepStart("步骤2");
    const childStep = await monitor.stepStart("子步骤2-1", step2.step_id);
    await monitor.stepEnd(childStep.step_id, { done: true });
    await monitor.stepEnd(step2.step_id, { success: true });

    // 从数据库恢复流程
    const recoveredMonitor = await monitor.recover(currentMonitor.monitor_id);
    console.log(JSON.stringify(recoveredMonitor, null, 2));

    // 恢复后可以继续执行子步骤的步骤
    const step3 = await monitor.stepStart("步骤3");
    await monitor.stepEnd(step3.step_id, { success: true });


    // 完成流程
    await monitor.end({ success: true });
  } catch (error) {
    await monitor.end(null, error);
  }

  // 获取监控树
  const monitorTree = monitor.getMonitorTree();
  console.log(JSON.stringify(monitorTree, null, 2));
}

使用示例

完整的示例代码可以在 examples 目录中找到：

运行示例

npm run example

API 参考

核心方法

流程控制

start(name, input?, description?): 开始新流程
recover(monitorId): 从数据库已有流程恢复
end(output, error?): 结束当前流程

步骤控制

stepStart(name, parentId?, input?, description?): 开始新步骤
stepEnd(stepId, output, error?): 结束步骤

状态查询

getMonitorTree(): 获取当前活动监控的树状结构
getMonitorDetails(monitorId): 获取指定监控的详细信息
listMonitors(options?): 查询监控列表

数据表设计参考

使用单表设计存储监控流程和步骤记录：

CREATE TABLE monitor_records (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    monitor_id VARCHAR(64) NOT NULL,         -- 监控ID
    step_id VARCHAR(64) UNIQUE NOT NULL,    -- 步骤ID
    parent_id VARCHAR(64),                    -- 父级ID：level=0时为空，level=1时为monitor_id，level>=2时为step_id
    type ENUM('monitor', 'step') NOT NULL,    -- 记录类型：监控流程/步骤
    level INT NOT NULL DEFAULT 0,             -- 步骤层级：0=监控，1=顶级步骤，2=子步骤...
    name VARCHAR(255) NOT NULL,               -- 名称
    status ENUM('pending', 'running', 'success', 'failed') NOT NULL,
    step_index INT,                           -- 同级步骤中的序号（从0开始）
    input JSON,                               -- 输入参数
    output JSON,                              -- 输出结果
    error TEXT,                               -- 错误信息
    description TEXT,                         -- 描述信息
    duration BIGINT,                          -- 执行时长(毫秒)
    metadata JSON,                            -- 扩展字段
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    INDEX idx_step_id (step_id),
    INDEX idx_monitor_id (monitor_id),
    INDEX idx_parent (parent_id),
    INDEX idx_type_status (type, status),
    INDEX idx_level (level),
    INDEX idx_created_at (created_at)
);