@lark-apaas/observable-web

基于 OpenTelemetry 的前端可观测性 SDK，提供日志记录和指标收集能力，支持自动上报页面访问量(PV)等关键指标。

1. Project Context (项目背景与定位)

Architectural Role: Core (核心底层)

Observable Web 是一个核心底层库，为 Lark Apaas 前端生态提供统一的可观测性能力，包括日志记录和指标收集。

Key Consumers (谁在用我)

• 🛠️ @lark-apaas/toolkit: 前端工具包，集成了该库作为底层可观测性基础

Core Dependencies (我依赖谁)

• 🔧 @opentelemetry/resources: 资源检测与管理
• 📝 @opentelemetry/sdk-logs: 日志 SDK
• 📊 @opentelemetry/sdk-metrics: 指标 SDK
• 🔗 @opentelemetry/core: 核心功能库

2. Real-world Scenarios (基于真实挖掘)

Scenario A: The Standard Usage

说明： 在应用中初始化和配置 Observable Web SDK（参考自 @lark-apaas/toolkit）

import { observable, AppEnv } from "@lark-apaas/observable-web";

export const initObservable = () => {
    observable.start({
        serviceName: "app",
        env: process.env.NODE_ENV === 'development' ? AppEnv.Dev : AppEnv.Prod,
        collectorUrl: {
            log: `/spark/app/${(window as unknown as {appId: string}).appId}/runtime/api/v1/observability/logs/collect`,
            metric: `/spark/app/${(window as unknown as {appId: string}).appId}/runtime/api/v1/observability/metrics/collect`,
        },
    });
};

Scenario B: Logging Usage

说明： 在业务组件中使用 SDK 记录日志

import { observable } from "@lark-apaas/observable-web";

// 在业务逻辑中记录日志
export const handleSubmit = () => {
    try {
        // 业务逻辑
        
        // 记录成功日志
        observable.log("INFO", "表单提交成功", {
            formType: "userRegistration",
            timestamp: Date.now(),
        });
    } catch (error) {
        // 记录错误日志
        observable.log("ERROR", "表单提交失败", {
            errorType: "validationError",
            errorMessage: (error as Error).message,
        });
    }
};

Scenario C: Metric Usage

说明： 记录自定义指标

import { observable } from "@lark-apaas/observable-web";

// 记录用户操作次数
export const trackUserAction = (actionType: string) => {
    observable.addCount("user_actions", 1, {
        action_type: actionType,
        timestamp: Date.now(),
    });
};

3. API Reference

Core Exports

| 导出项 | 类型 | 说明 | |--------|------|------| | observable | WebObservableSdk | 单例 SDK 实例，提供所有可观测性功能 | | AppEnv | enum | 应用环境枚举（Dev = "preview", Prod = "runtime"） |

WebSdkConfig Interface

| 属性 | 类型 | 说明 | |------|------|------| | serviceName | string | 服务名称 | | env | AppEnv | 应用环境（开发环境下不会上报数据） | | collectorUrl | { log: string; metric: string } | 日志和指标收集器 URL | | headers? | Record<string, string> | 可选的请求头信息 |

Public Methods

start(config: WebSdkConfig)

• 初始化 SDK，启动日志和指标收集
• 参数：
  • config: SDK 配置对象

log(level: 'INFO' | 'ERROR' | 'WARN', message: string, attributes: Record<string, any> = {})

• 记录日志
• 参数：
  • level: 日志级别
  • message: 日志消息内容
  • attributes: 自定义属性（可选）

addCount(name: string, value: number = 1, attributes: Record<string, any> = {})

• 增加计数器指标
• 参数：
  • name: 指标名称
  • value: 增加的值（默认为 1）
  • attributes: 自定义属性（可选）

shutdown()

• 关闭 SDK，清理资源

4. Automatic Instrumentation

Page View (PV) Tracking

• SDK 自动初始化 PV 监控
• 记录页面访问量、停留时间等关键指标
• 通过 OpenTelemetry 的指标系统上报

Lifecycle Management

• 监听页面可见性变化（visibilitychange 事件）
• 页面隐藏时自动刷新数据
• 兼容老旧浏览器（pagehide 事件兜底）

5. Installation

npm install @lark-apaas/observable-web

需要 react 和 react-dom 作为 peer 依赖。

6. Performance Considerations

• 批量处理：日志采用批量处理机制，每 5 秒上报一次
• 指标采集：指标每 10 秒采集并上报一次
• 环境控制：开发环境下自动禁用上报，避免干扰开发
• 资源优化：使用懒加载和按需初始化，减少初始加载时间

License

MIT