@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 信息。

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。

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 等系统中索引一致性。