@skyroc/logger

概览

项	值
包名	`@skyroc/logger`
版本	1.0.0
依赖	`loglayer`、`@loglayer/transport`、`idb`、`@react-native-async-storage/async-storage`、`serialize-error`、`nanoid`
测试	❌ 无

基于 LogLayer 的跨端日志系统，提供「写入本地存储 → 命中白名单后批量上传 → 按保留期清理」一整套生命周期。

适用场景

移动端 / Web 端故障日志上报
灰度用户的精准日志采集（只对白名单内用户上传）
离线场景：先落本地，恢复网络后补传

平台适配

平台	存储	适配器
Web	IndexedDB	`WebStorageAdapter`（基于 `idb`）
React Native	AsyncStorage	`RNStorageAdapter`
小程序（预留）	文件系统	常量 `MP_LOG_DIRECTORY` / `MP_LOG_FILE_EXTENSION`

createLogger({ platform }) 会自动选择对应适配器。

核心组件

              ┌──── DevTransport (console，仅 isDev)
LogLayer ────┤
              └──── StorageTransport ──→ IStorageAdapter ──→ IndexedDB / AsyncStorage

WhitelistManager  ──→ 定期请求接口判断设备是否在白名单
UploadManager     ──→ 命中白名单后分批上传
CleanupManager    ──→ 按 retentionDays 清理过期日志

主入口导出

类别	符号
工厂	`createLogger`、`createConsoleLogger`
适配器	`BaseStorageAdapter`、`WebStorageAdapter`、`RNStorageAdapter`
Transport	`StorageTransport`
管理器	`WhitelistManager`、`UploadManager`、`CleanupManager`
工具	`getOrCreateDeviceId`
类型	`LoggerConfig`、`LoggerInstance`、`LogRecord`、`LogUploadRequest/Response`、`WhitelistRequest/Response`、`Platform`、`UploadResult`
Re-export	`LogLayer`、`LogLevel`（来自 `loglayer`）

默认常量

DAY_IN_MS                              // 24*60*60*1000
DEFAULT_RETENTION_DAYS                 // 默认保留 7 天
DEFAULT_BUFFER_SIZE                    // 写入 batch 大小
DEFAULT_FLUSH_INTERVAL                 // 缓冲刷盘间隔
DEFAULT_UPLOAD_BATCH_SIZE
DEFAULT_WHITELIST_CHECK_INTERVAL
DEVICE_ID_STORAGE_KEY
IDB_DATABASE_NAME / IDB_STORE_NAME / IDB_VERSION
RN_LOG_INDEX_KEY / RN_LOG_KEY_PREFIX
MP_LOG_DIRECTORY / MP_LOG_FILE_EXTENSION

使用示例

仅控制台（开发态）

import { createConsoleLogger } from '@skyroc/logger';

const { logger } = createConsoleLogger({ isDev: true });
logger.info('hello');

完整生产配置

import { createLogger } from '@skyroc/logger';

const { logger, uploadLogs, cleanupLogs, dispose } = await createLogger({
  platform: 'web',
  isDev: false,
  retentionDays: 7,
  whitelistEndpoint: '/api/log/whitelist',
  uploadEndpoint: '/api/log/upload'
});

// LogLayer 链式 API
logger.info('Application started');
logger.withMetadata({ userId: '123' }).info('User action');
logger.withError(new Error('boom')).error('Operation failed');

// 应用退出
dispose();

LogLayer API 亮点

结构化 metadata：logger.withMetadata({ ... }).info(...)
错误对象序列化：logger.withError(e).error(...)（用 serialize-error）
级别：trace / debug / info / warn / error / fatal

白名单 + 上传流程

应用启动
  └─ WhitelistManager 周期请求 whitelistEndpoint
     ├─ 设备不在白名单 → 只写本地，不上传（默认行为）
     └─ 设备首次入白名单 → 触发历史日志全量上传 + 之后持续上传新增

UploadManager 命中白名单后：
  - 从存储读出待传 LogRecord[]
  - 按 batchSize 分批 POST uploadEndpoint
  - 成功删除已传记录；失败下次再试

设备 ID

getOrCreateDeviceId() 用 nanoid 生成持久化设备 ID，跨平台存储（key 为 DEVICE_ID_STORAGE_KEY）。每条日志通过 LogRecord.deviceId 关联设备。

注意

当前 monorepo 内部 grep 未发现 apps/admin 主动消费 @skyroc/logger，包属于「随项目沉淀，按需启用」型基础设施。
README 在 packages/@core/logger/README.md，包含更详细的 API 说明。

@skyroc/logger

On this page