@lark-apaas/observable 1.0.1-alpha.9 → 1.0.2-alpha.2

package/README.md

@@ -0,0 +1,97 @@
+# @lark-apaas/observable (Observable Server SDK)
+
+面向服务端的日志可观测 SDK，基于 OpenTelemetry Logs，提供结构化日志导出能力，并内置请求上下文透传与环境标识，便于在网关或日志采集侧车中统一解析、聚合与检索。
+
+## 功能特性
+- 自定义日志导出器 `CustomExporter`，实现了 OTel `LogRecordExporter` 接口（src/core/exporter.ts:28），以 OTLP-like 的结构将日志输出到标准输出。
+- 自动注入通用属性：
+  - `uuid`：请求/日志链路 ID（src/core/exporter.ts:41-44）
+  - `app_env`：环境标识（Dev/Prod，依据 `NODE_ENV`）（src/core/exporter.ts:40-44）
+  - `user_id`、`tenant_id`、`app_id`、`method`、`path`：由 `ContextProvider` 提供的请求上下文（src/core/exporter.ts:46-57）
+- 属性安全转换：所有属性值统一转为字符串，保证 JSON 可序列化（src/core/exporter.ts:19-26）。
+- 时间精度：将 `HrTime` 转换为纳秒数用于时间戳字段（src/utils/hrTimeToNanoNumber.ts:6-18）。
+- 输出前缀/后缀：通过强制前后缀包裹日志行，方便采集器按行切割（src/core/exporter.ts:30-31, 87-89）。
+
+## 安装
+该包在工作区内使用 Yarn 管理。
+
+```bash
+# 在 monorepo 根目录
+yarn install
+```
+
+外部项目使用：
+```bash
+yarn add @lark-apaas/observable
+```
+
+环境要求：
+- Node.js >= 18
+- peerDependencies：`@nestjs/common`、`@nestjs/core`（^10.4.20）
+
+## 快速开始（概念示例）
+本包提供的 `CustomExporter` 可直接接入 OpenTelemetry Logs 管道。以下示例展示了如何在应用启动阶段注册日志导出：
+
+```ts
+import { LoggerProvider, BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
+// 从本包导入 CustomExporter 与 ContextProvider 的实现（根据你的导出入口而定）
+// import { CustomExporter, MyContextProvider } from '@lark-apaas/observable';
+
+const provider = new LoggerProvider();
+const contextProvider = /* 你的 ContextProvider 实例 */;
+const exporter = new CustomExporter(contextProvider);
+
+provider.addLogRecordProcessor(new BatchLogRecordProcessor(exporter));
+const logger = provider.getLogger('app');
+
+// 记录一条结构化日志
+logger.emit({
+  body: 'hello observable',
+  attributes: { level: 'INFO', module: 'bootstrap' },
+});
+```
+
+在 NestJS 项目中，可在根模块的 `onModuleInit` 或专用日志模块中进行以上注册。`ContextProvider` 需在你的请求处理中维护用户/租户等上下文并可被注入。
+
+## 日志输出格式
+每条日志以一行 JSON 输出到 stdout，并被前后缀包裹：
+
+```
+force-log-prefix{ "resource": { "attributes": {} }, "logRecords": [{
+  "timeUnixNano": 173..., "observedTimeUnixNano": 173...,
+  "severityNumber": 9, "severityText": "INFO",
+  "body": "hello observable",
+  "attributes": {
+    "uuid": "...",
+    "app_env": "Dev",
+    "user_id": "...",
+    "tenant_id": "...",
+    "app_id": "...",
+    "method": "GET",
+    "path": "/api/ping",
+    "level": "INFO",
+    "module": "bootstrap"
+  },
+  "traceId": "...",
+  "spanId": "..."
+}] }force-log-suffix
+```
+
+采集侧可按前缀 `force-log-prefix` 与后缀 `force-log-suffix` 截取完整 JSON，再进行解析与入库。
+
+## 注意事项
+- 时间精度：`hrTimeToNanosNumber` 将 `HrTime` 转为 `number`，在超过 `2^53` 时可能发生精度损失（src/utils/hrTimeToNanoNumber.ts:4-18）。如需绝对精度，建议在采集器中支持 `BigInt` 或字符串时间戳。
+- 资源属性：当前 `resource.attributes` 为空占位（src/core/exporter.ts:70-73），如需补充服务名、版本等，可在初始化时合并 `sdk.resource` 信息。
+- 输出介质：默认写入 stdout
+
+## 开发与测试
+在本仓库中：
+```bash
+yarn build
+yarn dev
+yarn typecheck
+yarn test
+```
+
+## 许可证
+MIT