Logger 日志采集

@rydeen/logger 是统一的 前端日志采集组件，支持 Console、阿里云 SLS、腾讯云 CLS、华为云 LTS、AWS CloudWatch 等多种驱动，业务代码只需依赖 LoggerManage 即可发送结构化日志。

设计定位

多驱动一套接口：相同的 send / sendBatch / info / warn / error 接口，对应不同云厂商驱动。
结构化日志：通过 LoggerMessage 描述 level、code、content、sendTime，方便后端检索与分析。
终端统一采集：配合门店终端、Electron 客户端等，将前端异常与业务埋点统一采集到日志平台。

安装

npm install @rydeen/logger

各云厂商日志服务（SLS/CLS/LTS/CloudWatch）需要在运行环境中配置好 endpoint、密钥与网络访问权限。

驱动依赖（peerDependencies）

@rydeen/logger 本身只封装了日志采集与分发逻辑，并不内置各云厂商的 SDK。
对于不同的日志驱动，需要在业务工程中按需安装对应的 SDK，这些依赖在库的 package.json 中以 peerDependencies 形式声明：

通用依赖
- moment ＞用于时间格式化等基础能力，建议无论使用哪个驱动都安装
阿里云 SLS 驱动（DriverType.ALI_SLS）
- @aliyun-sls/web-track-browser
腾讯云 CLS 驱动（DriverType.TENCENT_CLS）
- tencentcloud-cls-sdk-js-web
华为云 LTS 驱动（DriverType.HUAWEI_LTS）
- lts-web-sdk
AWS CloudWatch 驱动（DriverType.AWS_CLOUD_WATCH）
- @aws-sdk/client-cloudwatch-logs

根据你在项目中实际启用的驱动，选择性安装对应依赖即可。例如：只使用 Console + 阿里云 + 腾讯云：

npm install @rydeen/logger \
  moment \
  @aliyun-sls/web-track-browser \
  tencentcloud-cls-sdk-js-web

如果仅在开发环境使用 Console 日志，可以暂时只安装 @rydeen/logger 和 moment；

上线前切换到云厂商驱动时，再补充安装对应 SDK，并在配置中启用相应 DriverType。

快速开始

import { LoggerManage, DriverType } from '@rydeen/logger'

// 1. 创建统一的 logger（可在应用启动时初始化）
export const logger = new LoggerManage({
  driver: DriverType.CONSOLE, // 开发环境可先用控制台
  code: 'store-terminal',     // 客户端/应用标识
})

// 2. 在业务中使用
logger.info('应用启动')
logger.warn('网络波动')
logger.error('下单失败')

// 3. 发送结构化日志
logger.send({
  content: {
    event: 'order_submit',
    orderId: '202401010001',
    status: 'FAILED',
  },
  sendTime: new Date().toISOString(),
})

实战示例：与 MQTT / Storage 配合的错误链路

场景：终端在通过 MQTT 发送订单时，如果失败，需要落库并上报日志，用于后续排查。

import { logger } from './logger'
import { storage } from './storage'

export async function safePublishOrder(orderId: string, payload: any) {
  try {
    // 这里省略 MQTT 发送的具体实现
    // await Mqtt.publish(...)
  } catch (e) {
    // 1. 本地存储离线订单
    await storage.insert('offline_order', [
      { column: 'id', value: orderId },
      { column: 'payload', value: JSON.stringify(payload) },
      { column: 'created_at', value: Date.now() },
    ])

    // 2. 上报错误日志
    logger.error(
      JSON.stringify({
        event: 'order_mqtt_failed',
        orderId,
        error: String(e),
      }),
    )

    throw e
  }
}

API 与类型参考

主要类型

LoggerOptions
- driver：日志驱动类型（通常配合 DriverType 枚举使用）。
- code：客户端/应用标识。
- projectId?：日志项目 ID。
- groupName?：日志分组名称。
- storeName?：日志存储库名称。
- host?：日志服务域名。
- endpoint?：日志服务端点。
- region?：日志服务区域。
- accessKey? / accessSecret?：访问密钥（不建议硬编码在前端）。
- apiVersion?：日志服务版本。
- debug?：调试日志等级或开关。
LoggerMessage
- level?：LogLevel（INFO / WARN / ERROR）。
- code?：客户端标识（默认使用 options.code）。
- content：日志内容（任意类型，序列化由驱动处理）。
- sendTime?：发送时间。
DriverType 枚举
- CONSOLE、ALI_SLS、TENCENT_CLS、HUAWEI_LTS、AWS_CLOUD_WATCH。

完整类型定义

以下类型与 @rydeen/logger 源码中的 src/types/logger.d.ts 保持一致：

import { LogLevel } from '../enums/level'

/**
 * 日志配置
 */
export interface LoggerOptions {
  /**
   * 日志驱动类型
   */
  driver: string
  /**
   * 客户端标识
   */
  code: string
  /**
   * 项目ID
   */
  projectId?: string
  /**
   * 日志分组
   */
  groupName?: string
  /**
   * 日志储存库名称
   */
  storeName?: string
  /**
   * 日志服务域名
   */
  host?: string
  /**
   * 日志服务端点
   */
  endpoint?: string
  /**
   * 日志服务区域
   */
  region?: string
  /**
   * 日志服务访问KEY
   */
  accessKey?: string
  /**
   * 日志服务访问秘钥
   */
  accessSecret?: string
  /**
   * 日志服务版本
   */
  apiVersion?: string
  /**
   * 调试日志等级
   */
  debug?: string | boolean
}

export interface LoggerMessage {
  /**
   * 日志级别
   */
  level?: LogLevel
  /**
   * 客户端标识
   */
  code?: string
  /**
   * 日志内容
   */
  content: any
  /**
   * 发送时间（可不填写）
   */
  sendTime?: string
}

方法列表

方法	签名	说明
构造函数	`new LoggerManage(options: LoggerOptions)`	按 driver 创建对应驱动实例，未匹配时回退到 Console。
send	`send(message: LoggerMessage): void`	发送单条结构化日志。
sendBatch	`sendBatch(logs: LoggerMessage[]): void`	批量发送日志。
info	`info(log: string): void`	发送 info 级别日志。
warn	`warn(log: string): void`	发送 warn 级别日志。
error	`error(log: string): void`	发送 error 级别日志。
code（getter/setter）	`get code(): string; set code(v: string)`	获取或设置当前客户端标识。

运行环境支持

运行环境	说明
Web / Node / Capacitor	纯 TypeScript 实现，无原生依赖；云日志驱动依赖 HTTP/API 调用能力。

实际可用性取决于所选驱动：Console 几乎任意环境可用；SLS/CLS/LTS/CloudWatch 需配置正确 endpoint、密钥及网络权限。

使用建议

敏感信息：不要在前端硬编码云厂商密钥，应通过配置中心/环境变量注入。
分环境配置：开发/测试环境可使用 Console 驱动，生产环境再启用云日志驱动。
统一封装：推荐再封装一层 AppLogger，统一加上业务字段（如 tenantId、storeId、deviceId）。

设计定位​

安装​

驱动依赖（peerDependencies）​

快速开始​

实战示例：与 MQTT / Storage 配合的错误链路​

API 与类型参考​

主要类型​

完整类型定义​

方法列表​

运行环境支持​

使用建议​