Trace Insight

The vscode plugin used internally

Features

Trace Insight provides tools for analyzing and visualizing trace data in your development workflow.

Requirements

No additional requirements.

使用文档

配置文件

Trace Insight 需要通过配置文件来设置监控面板和访问凭证。配置文件名为 trace-insight.config.mjs，需要放置在项目根目录。

配置文件查找顺序

1. 工作区根目录：优先从当前打开的 VS Code 工作区根目录查找
2. 向上查找：如果工作区根目录未找到，会从当前活动文件所在目录向上查找，直到找到配置文件或到达文件系统根目录

配置文件格式

配置文件使用 ES Module 格式，必须使用 export default 导出配置对象：

export default {
  dashboardId: 'your-dashboard-id',
  access_token: 'your-access-token',
  scanPaths: ['src', 'app'], // 可选
};

配置选项

dashboardId (必需)

• 类型: string | string[]

• 说明: 监控面板 ID，支持单个面板 ID 或多个面板 ID 数组

• 示例:

  // 单个面板 ID
  dashboardId: 'abc123xyz';
  
  // 多个面板 ID
  dashboardId: ['abc123xyzsss', 'abc123xyz'];
  

access_token (必需)

• 类型: string
• 说明: 访问令牌，用于 API 认证
• 示例:

  access_token: 'xxx';
  

scanPaths (可选)

• 类型: string[]

• 说明: 指定需要扫描的目录路径数组。如果不配置，将扫描整个项目

• 示例:

  // 只扫描 src 和 app 目录
  scanPaths: ['src', 'app'];
  
  // 扫描多个目录
  scanPaths: ['src', 'lib', 'components'];
  

tracePatterns (可选)

• 类型: string[]

• 说明: 自定义匹配规则前缀数组。默认值为 ['c_corp_', 'o_corp_']

• 示例:

  // 使用默认规则（可不配置）
  tracePatterns: ['c_corp_', 'o_corp_'];
  
  // 自定义匹配规则
  tracePatterns: ['trace_', 'metric_', 'event_'];
  

完整配置示例

export default {
  // 单个面板 ID
  dashboardId: 'abc123xyz',
  access_token: 'xxx',
  scanPaths: ['src', 'app'],
};

或者使用多个面板 ID 和自定义匹配规则：

export default {
  // 多个面板 ID
  dashboardId: ['abc123xyzzzz', 'abc123xyz'],
  access_token: 'xxx',
  scanPaths: ['src', 'lib', 'components'],
  // 自定义匹配规则（可选，默认为 ['c_corp_', 'o_corp_']）
  tracePatterns: ['c_corp_', 'o_corp_', 'custom_trace_'],
};

配置验证

插件会在启动时自动验证配置文件：

• ✅ 配置文件必须存在且格式正确
• ✅ dashboardId 不能为空（字符串不能为空，数组不能为空数组）
• ✅ access_token 不能为空
• ✅ scanPaths 如果配置，必须是字符串数组，且数组元素不能为空字符串
• ✅ tracePatterns 如果配置，必须是字符串数组

如果配置验证失败，插件会在 VS Code 中显示错误提示信息。

使用方法

1. 初始设置

1. 创建配置文件：在项目根目录创建 trace-insight.config.mjs 文件
2. 填写配置：按照上述配置选项填写相应的值
3. 重启 VS Code：配置完成后，重启 VS Code 或重新加载窗口以使配置生效

2. 功能使用

2.1 悬停查看监控信息（Hover）

在代码编辑器中，将鼠标悬停在匹配配置规则的字符串上时（默认为 c_corp_ 或 o_corp_ 开头），插件会自动显示该字符串的监控状态：

• ✅ 已有监控：显示绿色对勾，表示该字符串已在监控面板中配置
• ❌ 暂无监控：显示红色叉号，表示该字符串尚未配置监控

悬停信息包含：

• 字符串的监控状态
• 相关的监控面板信息（如果有）
• 可点击的链接，直接跳转到对应的监控面板

支持的字符串格式：

• c_corp_xxx - 直接使用的字符串
• o_corp_xxx - 直接使用的字符串
• ClassName.c_corp_xxx - 类静态属性访问形式
• ClassName.o_corp_xxx - 类静态属性访问形式

使用示例：

// 将鼠标悬停在以下字符串上即可查看监控信息
const traceId = 'c_corp_user_login';
const orderId = 'o_corp_order_create';

// 也支持类静态属性形式
class TraceIds {
  static USER_LOGIN = 'c_corp_user_login';
}

2.2 扫描项目监控情况

扫描整个项目，分析所有 trace 字符串的监控状态，并生成详细报告。

触发方式（任选其一）：

1. 状态栏按钮：

   • 在 VS Code 状态栏右侧找到 🔍 Trace Insight 按钮
   • 点击按钮即可开始扫描

2. 命令面板：

   • 按 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux) 打开命令面板
   • 输入 Trace Insight: 扫描项目监控情况
   • 选择并执行该命令

扫描过程：

• 插件会显示进度通知，包括：
  • 初始化 Dashboard 数据
  • 读取项目文件
  • 分析文件内容
  • 生成报告

扫描范围：

• 默认扫描 src、app、server 目录
• 可通过配置文件中的 scanPaths 选项自定义扫描目录
• 如果未配置 scanPaths，将使用默认目录

扫描报告： 扫描完成后，会在新的编辑器中打开报告，报告包含：

1. 概览统计：

   • 总字符串数量
   • 已有监控数量
   • 暂无监控数量
   • 监控覆盖率

2. 详细列表：

   • 每个 trace 字符串的监控状态
   • 字符串所在文件路径和行号
   • 相关的监控面板信息（如果有）
   • 可点击的链接，直接跳转到监控面板或代码位置

3. 分类展示：

   • 按监控状态分类（已有监控 / 暂无监控）
   • 便于快速定位需要配置监控的字符串

3. 常见使用场景

场景 1：开发时快速检查

• 在编写代码时，将鼠标悬停在 trace 字符串上，快速确认是否已配置监控

场景 2：项目监控审计

• 定期执行项目扫描，生成完整的监控状态报告
• 检查项目中哪些 trace 字符串尚未配置监控
• 确保重要业务流程都有相应的监控

场景 3：新功能开发

• 开发新功能时，使用悬停功能实时检查监控配置
• 功能完成后，执行扫描确认所有新增的 trace 字符串都已配置监控

4. 注意事项

• ⚠️ 首次使用或配置变更后，插件需要初始化 Dashboard 数据，可能需要几秒钟
• ⚠️ 扫描大型项目时，可能需要较长时间，请耐心等待
• ⚠️ 确保网络连接正常，插件需要访问 Dashboard API 获取监控数据
• ⚠️ 如果配置文件不存在或格式错误，插件会显示错误提示，请按照提示修复配置

Extension Settings

This extension does not currently contribute any VS Code settings.

Release Notes

0.0.1

Initial release of Trace Insight.