@lark-apaas/observable-web 1.0.0-alpha.8 → 1.0.0

package/README.md

@@ -1 +1,151 @@
-# @lark-apaas/miaoda-inspector-jsx-runtime
+# @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

package/dist/{lib/core/sdk.d.ts → index.d.ts}

@@ -1,4 +1,7 @@
-import { AppEnv } from '../const.js';
+declare enum AppEnv {
+    Dev = "preview",
+    Prod = "runtime"
+}
 
 interface WebSdkConfig {
     serviceName: string;
@@ -24,10 +27,12 @@ declare class WebObservableSdk {
     private initLogs;
     private initMetrics;
     private initAutoPv;
+    private flushData;
+    private registerLifecycleListeners;
     log(level: 'INFO' | 'ERROR' | 'WARN', message: string, attributes?: Record<string, any>): void;
     addCount(name: string, value?: number, attributes?: Record<string, any>): void;
     shutdown(): Promise<void>;
 }
 declare const observable: WebObservableSdk;
 
-export { WebObservableSdk, type WebSdkConfig, observable };
+export { AppEnv, observable };