# @lark-apaas/observable

`@lark-apaas/observable` 是一个面向服务端的链路追踪与日志观测 SDK。它基于 OpenTelemetry 构建，为 Monorepo 中的 Node.js 应用提供统一的、具备上下文感知的可观测性能力。

---

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

- **Architectural Role**: **Core Infrastructure** - 位于系统底层，作为服务端可观测性的基础库，屏蔽了 OpenTelemetry 的复杂配置。
- **Key Consumers (谁在用我)**:
    - 📦 `@lark-apaas/nestjs-observable`: NestJS 框架集成层，将其封装为 NestJS 模块和拦截器。
- **Core Dependencies (我依赖谁)**:
    - 🛠️ `OpenTelemetry APIs & SDKs`: 提供核心的 Trace 和 Logs 处理能力。
    - 🔗 `rxjs`: 用于处理流式数据的生命周期管理（如 Span 的自动结束）。

---

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

### Scenario A: The Standard Usage (Middleware 自动开启上下文)
这是在 `@lark-apaas/nestjs-observable` 中最标准的用法，用于在请求进入时自动开启根 Span，并从 Header 中透传 Trace 信息。

```typescript
import { appSdk } from '@lark-apaas/observable';

// 在中间件或拦截器中调用
appSdk.startContext(req.headers, 'GET /api/user', (span) => {
  // 此时上下文已建立，后续的 log 或 trace 会自动关联
  res.on('finish', () => {
    span.setAttributes({ 'http_status_code': res.statusCode });
    span.end();
  });
  next();
});
```

### Scenario B: Integration Example (业务代码手动打点)
展示如何在业务 Service 中进行手动链路追踪和日志记录，SDK 会自动从当前上下文中提取 Trace ID。

```typescript
import { appSdk } from '@lark-apaas/observable';

class UserService {
  async getUser(id: string) {
    // 自动关联到中间件开启的 Root Span 下
    return appSdk.trace('UserService.getUser', async (span) => {
      span.setAttribute('user.id', id);
      
      const user = await this.db.find(id);
      
      // 日志会自动带上当前 Trace 的上下文信息
      appSdk.log('info', 'Fetch user success', { userId: id });
      
      return user;
    });
  }
}
```

---

## 3. API Reference

### Core API (`appSdk`)

| 函数名 | 说明 | 参数类型 |
| :--- | :--- | :--- |
| `start()` | 初始化并启动 OTel SDK。 | `void` |
| `startContext()` | [框架专用] 根据 Header 开启一个活动的根上下文。 | `(headers, name, callback)` |
| `trace<T>()` | [用户专用] 手动创建一个子 Span，支持同步、Async 和 Observable。 | `(name, callback)` |
| `log()` | 记录结构化日志，自动关联当前 Trace 上下文。 | `(level, message, extra?)` |
| `flush()` | 强制刷新并导出内存中积压的 Trace 和 Logs 数据。 | `Promise<void>` |

### Configuration
SDK 默认采用以下配置：
- **Batch Processing**: 日志和 Trace 均采用批处理（BatchProcessor），延迟 2000ms 或达到批次上限时导出。
- **Resource Detection**: 内置 `PlatformDetector`，自动识别并添加平台相关的资源属性。
- **Log Format**: 自动将所有日志属性转换为字符串，确保在 ElasticSearch 等系统中索引一致性。