前端日志埋点 SDK 设计思路解析

设计一个前端日志埋点 SDK 是一个复杂但非常重要的任务，尤其是在现代 Web 应用中，日志埋点是监控用户行为、分析性能问题和优化用户体验的关键工具。以下是一个专业的前端日志埋点 SDK 的设计思路，涵盖了核心功能、架构设计和最佳实践。

1. 核心功能需求

一个完善的日志埋点 SDK 应具备以下核心功能：

• 日志采集：支持自动和手动埋点，采集用户行为、性能指标、错误日志等。
• 日志分类：支持多种日志类型（如点击事件、页面浏览、API 请求、错误日志等）。
• 日志过滤与采样：支持按规则过滤或采样日志，避免数据量过大。
• 日志上报：支持实时上报和批量上报，优化网络请求。
• 日志缓存与重试：在网络异常时缓存日志，并在恢复后重试上报。
• 性能优化：尽量减少对主线程的阻塞，避免影响用户体验。
• 扩展性：支持自定义日志格式、上报策略和插件机制。
• 安全性：防止日志数据被篡改或泄露。

2. 架构设计

2.1 模块划分

• 核心模块：负责日志的采集、缓存、上报等核心逻辑。
• 插件模块：支持扩展功能，如性能监控、错误捕获、用户行为分析等。
• 配置模块：提供灵活的配置选项，如上报地址、采样率、日志级别等。
• 工具模块：提供通用的工具函数，如 UUID 生成、时间格式化、数据序列化等。

2.2 数据流设计

1. 日志采集：通过事件监听、API 拦截等方式采集日志。
2. 日志处理：对日志进行格式化、过滤、采样等处理。
3. 日志缓存：将日志存储到本地（如 localStorage 或 IndexedDB）。
4. 日志上报：通过 HTTP 或 WebSocket 将日志发送到服务器。
5. 日志重试：如果上报失败，将日志重新加入队列，等待下次上报。

3. 关键技术实现

3.1 日志采集

• 自动埋点：
  • 使用 addEventListener 监听用户交互事件（如点击、滚动、输入等）。
  • 使用 MutationObserver 监听 DOM 变化，捕获动态加载的内容。
  • 使用 Performance API 采集页面加载性能数据。
• 手动埋点：
  • 提供 API 供开发者手动触发日志上报，如 trackEvent(eventName, data)。

3.2 日志上报

• 上报方式：
  • 使用 XMLHttpRequest 或 fetch 发送 HTTP 请求。
  • 使用 sendBeacon 在页面关闭时发送日志，确保数据不丢失。
• 批量上报：
  • 将多条日志合并为一个请求，减少网络开销。
• 实时上报：
  • 对于关键日志（如错误日志），立即上报。

3.3 日志缓存

• 使用 localStorage 或 IndexedDB 存储日志，确保在网络异常时数据不丢失。
• 设置缓存上限，避免占用过多存储空间。

3.4 性能优化

• 使用 Web Worker 将日志处理逻辑放到后台线程，避免阻塞主线程。
• 使用 requestIdleCallback 在浏览器空闲时处理日志。

3.5 错误处理

• 使用 window.onerror 和 window.onunhandledrejection 捕获全局错误。
• 提供 API 供开发者手动上报错误。

4. 配置与扩展

4.1 配置项

• reportUrl：日志上报地址。
• samplingRate：日志采样率（如 0.1 表示 10% 的日志会上报）。
• logLevel：日志级别（如 debug、info、warn、error）。
• maxCacheSize：日志缓存上限。
• enablePerformance：是否启用性能监控。

4.2 插件机制

• 提供插件接口，允许开发者扩展 SDK 功能。
• 示例插件：
  • 性能监控插件：采集页面加载时间、资源加载时间等。
  • 错误监控插件：捕获 JavaScript 错误、Promise 异常等。
  • 用户行为插件：分析用户点击路径、停留时间等。

5. 安全性设计

• 数据加密：对敏感日志数据进行加密。
• 防止篡改：使用签名机制确保日志数据在传输过程中未被篡改。
• 隐私保护：遵守 GDPR 等隐私法规，避免采集用户敏感信息。

6. 示例代码

以下是一个简单的日志埋点 SDK 示例：

class LogTracker {
  constructor(config) {
    this.config = {
      reportUrl: '',
      samplingRate: 1,
      logLevel: 'info',
      ...config,
    };
    this.queue = [];
    this.init();
  }

  init() {
    window.addEventListener('beforeunload', () => this.flush());
    setInterval(() => this.flush(), 10000); // 每 10 秒上报一次
  }

  trackEvent(eventName, data) {
    const log = {
      event: eventName,
      data,
      timestamp: Date.now(),
    };
    if (Math.random() < this.config.samplingRate) {
      this.queue.push(log);
    }
  }

  flush() {
    if (this.queue.length === 0) return;
    const logs = this.queue.splice(0, this.queue.length);
    navigator.sendBeacon(this.config.reportUrl, JSON.stringify(logs));
  }
}

// 使用示例
const tracker = new LogTracker({ reportUrl: 'https://example.com/log' });
tracker.trackEvent('click', { button: 'submit' });

7. 最佳实践

• 轻量级：尽量减少 SDK 的体积，避免影响页面加载性能。
• 可测试性：提供单元测试和集成测试，确保 SDK 的稳定性。
• 文档完善：提供详细的 API 文档和使用示例。
• 兼容性：确保 SDK 兼容主流浏览器和设备。

通过以上设计思路，可以构建一个功能强大、性能优异且易于扩展的前端日志埋点 SDK，为业务提供可靠的数据支持。