Flytrap 引擎

智能异常监控与全链路追踪引擎 - 为每一位追求完美的代码工匠而生

简介

Flytrap 是 Spark 的核心调试引擎，提供极致的异常捕获、堆栈回溯、内存监控和请求追踪能力。它像一只敏锐的蜘蛛，捕获每一个可能导致程序崩溃的"飞虫"。

核心特性

• 智能异常捕获 - 自动捕获未处理的异常和 Promise 拒绝
• 全链路追踪 - 追踪从用户操作到后端响应的完整链路
• 内存泄漏检测 - 实时监控内存使用，发现潜在泄漏
• 请求监控 - 记录所有 HTTP 请求，分析性能瓶颈
• 堆栈快照 - 在关键时刻保存程序状态，便于复现问题
• 智能分析 - AI 驱动的异常分析，提供修复建议

安装

在您的项目中安装 Flytrap SDK：

npm

npm install @spark-center/flytrap

yarn

yarn add @spark-center/flytrap

pnpm

pnpm add @spark-center/flytrap

快速开始

基础配置

import { Flytrap } from '@spark-center/flytrap'

// 初始化 Flytrap
const flytrap = new Flytrap({
  apiKey: 'your-api-key',
  environment: 'production',
  release: '1.0.0',
  // 配置采样率
  tracesSampleRate: 1.0,
  // 配置异常捕获
  integrations: [
    new Flytrap.BrowserTracing(),
    new Flytrap.Replay()
  ]
})

flytrap.init()

异常捕获

Flytrap 会自动捕获以下类型的异常：

// 自动捕获
// 1. 未处理的错误
throw new Error('Something went wrong')

// 2. 未处理的 Promise 拒绝
Promise.reject(new Error('Async error'))

// 3. 网络请求错误
fetch('/api/unknown')

手动上报

// 捕获特定错误
try {
  riskyOperation()
} catch (error) {
  flytrap.captureException(error, {
    tags: {
      module: 'payment',
      action: 'checkout'
    },
    extra: {
      userId: '12345',
      cartItems: 3
    }
  })
}

// 发送自定义消息
flytrap.captureMessage('User completed checkout', {
  level: 'info'
})

全链路追踪

Flytrap 的追踪功能可以帮助您了解用户操作的完整路径。

分布式追踪

// 创建自定义事务
const transaction = flytrap.startTransaction('checkout', 'process')

// 添加子操作
const paymentSpan = transaction.startChild({
  op: 'payment',
  description: 'Process payment'
})

// 完成操作
paymentSpan.finish()

transaction.finish()

性能监控

// 监控特定函数的性能
flytrap.monitorFunction('calculateTotal', () => {
  return expensiveCalculation()
})

堆栈快照

在关键时刻保存程序状态，便于后续分析。

// 保存堆栈快照
flytrap.captureSnapshot({
  name: 'before-checkout',
  data: {
    cart: getCartState(),
    user: getUserState()
  }
})

高级配置

错误分组

new Flytrap({
  // 自定义错误分组
  errorGroupId: (event) => {
    // 根据错误类型分组
    if (event.exception?.values[0]?.type === 'TypeError') {
      return 'type-errors'
    }
    return 'other-errors'
  }
})

过滤敏感信息

new Flytrap({
  // 过滤请求头中的敏感信息
  beforeSend(event) {
    // 移除 Authorization 头
    if (event.request?.headers) {
      delete event.request.headers['authorization']
    }
    return event
  },
  // 过滤用户数据
  beforeBreadcrumb(crumb) {
    if (crumb.category === 'user') {
      delete crumb.data?.creditCard
    }
    return crumb
  }
})

采样策略

new Flytrap({
  // 错误采样率
  errorSampleRate: 0.1, // 10% 的错误被采样
  // 性能采样率
  tracesSampleRate: (samplingContext) => {
    // 生产环境采样 10%，其他环境采样 100%
    return samplingContext.environment === 'production' ? 0.1 : 1.0
  }
})

Spark 集成

作为 Spark 插件使用 Flytrap 可以获得更强的能力。

插件配置

{
  "name": "my-app-with-flytrap",
  "permissions": [
    "network:request",
    "storage:read"
  ]
}

本地数据存储

// 使用 Spark 的本地存储
const storage = await window.sparkAPI.getLocalStorage()

// 存储异常报告
await storage.set('flytrap-reports', reports)

// 读取历史报告
const reports = await storage.get('flytrap-reports')

最佳实践

1. 设置合理的采样率 - 生产环境建议错误采样率 10-20%，性能采样率 1-10%
2. 添加有意义的上下文 - 在捕获异常时添加用户 ID、操作类型等上下文信息
3. 使用环境变量 - 根据 NODE_ENV 设置不同的配置
4. 定期审查异常报告 - 设置定期提醒，及时处理高频异常

常见问题

Flytrap 会影响性能吗？

Flytrap 的性能影响极小。通过合理的采样配置，可以将性能影响降到最低。建议生产环境使用较低的采样率。

如何处理源码映射？

Flytrap 自动支持 Source Maps。确保您的构建过程生成了 .map 文件，并上传到 Flytrap 控制台。

可以离线使用吗？

可以。Flytrap 支持离线模式，异常会先存储在本地，待网络恢复后批量上传。

相关资源

• Flytrap 官方文档
• Flytrap GitHub
• 异常处理最佳实践