npm package: @lark-apaas/observable-web
Description: Observable SDK For Web
Latest version: 1.0.6

# @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`）

```typescript
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 记录日志

```typescript
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
**说明：** 记录自定义指标

```typescript
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

```bash
npm install @lark-apaas/observable-web
```

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

## 6. Performance Considerations

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

## License

MIT