@sentry-tools/core

Sentry工具库核心模块，提供统一的错误监控和上报管理能力。

功能特性

SentryTools

核心控制器类，整合了所有监控功能，提供统一的初始化和管理接口。

主要功能：

• 远程配置加载：支持从远程地址动态加载配置，方便动态更新监控规则。
• Sentry集成：封装Sentry初始化，集成浏览器追踪、HTTP客户端监控等能力。
• 白屏检测集成：自动集成白屏检测工具，在检测到白屏问题时自动上报。
• 错误事件处理：统一处理所有错误事件，自动分类和分发。
• 预加载错误处理：处理页面加载前发生的错误，从localStorage恢复并上报。

TransportManager

上报分发管理器，主要用于微前端场景下的错误上报分发。

功能特性：

• 多DSN支持：支持配置多个Sentry DSN，根据规则将错误分发到不同的项目。
• 智能分发规则：支持基于以下信息进行分发：
  • API接口地址（api）
  • 当前访问地址（location）
  • 错误栈中的源文件地址（fileAddresses）
  • 模块元数据（module_metadata）
• 默认传输：支持设置默认的DSN，当没有规则匹配时使用默认DSN。
• 自定义规则：支持通过函数自定义分发规则。

使用场景：

• 微前端架构中，不同子应用需要上报到不同的Sentry项目。
• 根据错误来源（API错误、资源错误、JS错误）分发到不同的监控项目。
• 根据代码模块来源进行错误分发。

CategoryManager

错误分类管理器，用于自动识别和标记错误的类型。

功能特性：

• 预定义分类：内置多种错误分类，按优先级排序：
  • blankScreen（优先级-5）：白屏相关错误
  • resource（优先级-4）：资源加载错误（ChunkLoadError、NetworkError等）
  • api（优先级-3）：API接口错误（HTTP客户端错误、接口超时等）
  • js（优先级-2）：JavaScript运行时错误（Error、TypeError、ReferenceError等）
  • biz（优先级-1）：业务逻辑错误
• 多种匹配模式：
  • inclusion：包含匹配
  • equal：完全相等匹配
  • regex：正则表达式匹配
• 布尔表达式匹配：支持复杂的布尔表达式规则，如 $value0 && $value1 || $value2。
• 自定义匹配器：支持通过函数自定义匹配逻辑。

匹配路径示例：

• errorName：错误名称
• exception.matchPath：异常信息路径
• exception.mechanism.type：错误机制类型
• event.tags.category：事件标签分类

配置选项

interface SentryConfig {
  // Sentry浏览器配置
  browser?: BrowserOptions;
  // Sentry集成配置
  integrations?: Record<string, any>;
  // 传输管理器配置
  transport?: {
    transportOptions: TransportOption[];
    transportKey?: string;
  };
  // 分类管理器配置
  category?: {
    defaultCategory?: string;
    categories?: Record<
      string,
      {
        priority?: number;
        rules?: (CategoryItem | CategoryExpression)[];
      }
    >;
  };
  // 白屏检测配置
  blankScreen?: BlankScreenOptions;
}

使用场景

• 统一错误监控：为应用提供统一的错误监控入口，自动处理错误分类和上报。
• 微前端架构：在微前端场景下，根据错误来源自动分发到对应的Sentry项目。
• 错误分类统计：通过自动分类，方便在Sentry中按错误类型进行统计和分析。
• 动态配置更新：通过远程配置，无需发版即可更新监控规则和分类规则。
• 白屏监控：自动集成白屏检测，及时发现页面渲染问题。

技术实现

• 使用 defu 进行配置合并，支持深度合并和默认值。
• 使用 makeMultiplexedTransport 实现多DSN上报。
• 使用事件处理器（Event Processor）统一处理所有错误事件。
• 支持从localStorage恢复预加载错误，确保不遗漏任何错误。
• 通过自定义事件通知配置加载完成，方便其他模块监听。