设计灵活可扩展的前端日志解决方案:提升应用稳定性与可观测性
在前端开发的世界里,日志记录是一项至关重要的任务。它不仅能够帮助开发者快速定位和解决问题,还能为应用的健康监控和性能优化提供有力支持。然而,随着项目的不断发展和业务需求的日益复杂,传统的日志记录方式往往难以满足灵活扩展的需求。本文将介绍一种灵活可扩展的前端日志解决方案------awesome-logger,并详细阐述其设计思路、架构特点以及使用方法。
一、设计目标与需求分析
在设计前端日志解决方案时,我们通常会面临以下几个关键需求:
- 快速定位用户问题:能够自动收集完整的上下文信息,如操作系统、设备型号、用户代理等,以便在用户反馈异常时,能够快速定位问题根源。
- 应用健康度监控 :支持多等级日志管理,如
info
、warn
和error
级别,帮助开发者构建稳定性大盘,实时监控应用的健康状态。 - 多日志系统同构上报:能够同时接入多个日志服务,如阿里云 SLS、腾讯云 CLS 等,实现一次上报同步多平台。
- 自定义日志扩展:允许开发者根据业务需求自定义日志上报逻辑,如接入私有日志系统、进行数据加密等。
- 高效开发与标准化:提供开箱即用的主流插件,减少基础设施的重复开发,提高开发效率。
二、awesome-logger
架构设计
awesome-logger
采用分层架构,确保功能解耦与扩展性,主要分为以下三层:
- 核心层(
@awesome-logger/core
)- Logger 类 :管理日志生成、等级控制及插件注册。提供
info
、warn
、error
等方法,支持基础字段配置。 - LogPlugin 抽象类 :定义插件开发规范。所有插件需实现
sendLog
方法,将日志数据发送到目标服务。
- Logger 类 :管理日志生成、等级控制及插件注册。提供
- 插件层(
@awesome-logger/plugin-*
) 提供具体日志服务的实现。例如,@awesome-logger/plugin-sls
对接阿里云 SLS 日志服务。开发者可根据规范自定义插件,扩展日志能力。 - 使用层(
@awesome-logger/client
)- Client 类 :封装核心功能,简化用户接入。支持通过
usePlugin
注册插件,并提供统一的日志接口。
- Client 类 :封装核心功能,简化用户接入。支持通过
三、awesome-logger
核心优势
- 内置标准化日志字段,助力高效排查 预定义了如
os
(操作系统)、device
(设备型号)、ua
(用户代理)等关键环境字段,无需额外开发即可收集全面的上下文信息,帮助开发者快速定位问题根源。 - 基础字段灵活配置,支持实时查询分析 允许用户自定义基础字段(如
uid
、env
等),这些字段会自动附加到每条日志中。结合阿里云 SLS 等服务,可实现日志的实时过滤与查询,精准定位用户反馈场景。 - 多等级日志管理,构建应用健康监控 支持
info
、warn
、error
等多种日志等级,帮助开发者建立稳定性大盘,实时监控应用健康状态。通过不同等级的日志分类,可快速识别潜在风险与异常。 - 插件化架构设计,轻松对接任意日志服务 采用插件机制,开发者可自由扩展日志能力。内置支持阿里云 SLS、腾讯云 CLS 等主流日志服务,同时允许自定义插件,适配私有日志系统或其他第三方服务。
四、快速开始
1. 安装依赖
bash
npm install @awesome-logger/client @awesome-logger/core @awesome-logger/plugin-sls
2. 初始化与配置
typescript
import Client from '@awesome-logger/client';
import { Logger } from '@awesome-logger/core';
import { SLSLogPlugin } from '@awesome-logger/plugin-sls';
// 创建 Logger 实例
const logger = new Logger({
uid: 'test_user_1',
release: '1.0.0',
env: 'production',
});
// 也可以使用 logger.setBaseField 方法处理异步场景
logger.setBaseField({ uid: 'user_001' });
// 配置基础字段
const client = new Client(logger);
// 注册阿里云 SLS 插件
const slsPlugin = new SLSLogPlugin({
host: 'your-sls-endpoint', // 公网域名
project: 'your-project',
logstore: 'your-logstore',
count: 20, // 发送条数阈值
time: 3, // 发送时间阈值
});
client.usePlugin(slsPlugin);
3. 日志上报
typescript
// 上报信息日志
client.info('enter_home_page', { page: 'home' });
// 上报警告日志
client.warn('api_timeout', { latency: 500 });
// 上报错误日志
client.error('api_fail', { errorCode: 500, endpoint: '/api/data' });
4. 日志上报到阿里云 SLS
效果如下图:

注意事项
- 在使用 plugin-sls 之前,您需要创建一个阿里云账户。
- 开通 SLS 日志服务,支持免费试用一个月,50GB 容量。
- 创建一个日志项目(log project)。
- 然后创建一个日志库(logstore,前端上报时记得开启 Web Tracking 选项)。
- 上报一些日志后,方可创建索引。
- 索引支持设置、追加和覆盖。
五、自定义插件开发
awesome-logger
支持开发者自定义插件,轻松对接私有日志系统或其他服务:
1. 创建插件类
typescript
import { LogPlugin } from '@awesome-logger/core';
class CustomLogPlugin extends LogPlugin {
sendLog(logData: Record<string, any>) {
// 自定义日志上报逻辑
console.log('自定义日志服务上报:', logData);
// 示例:发送到自研日志系统
fetch('https://your-log-service.com', {
method: 'POST',
body: JSON.stringify(logData)
});
}
}
export default CustomLogPlugin;
2. 使用自定义插件
typescript
import Client from '@awesome-logger/client';
import CustomLogPlugin from './CustomLogPlugin';
const client = new Client();
const customPlugin = new CustomLogPlugin({ /* 自定义配置 */ });
client.usePlugin(customPlugin);
client.info('click', { message: 'click button' });
3. 效果展示

六、日志内置字段
awesome-logger
的日志包含了丰富的内置字段,这些字段可以帮助开发者更好地了解日志的上下文信息,具体如下:
字段 | 类型 | 说明 |
---|---|---|
uid | string | number | 用户 UID |
release | string | 前端应用版本号 |
env | string | 环境:local、pre、prod |
type | string | 类型,如日志等级:info、warn、error |
key | string | 日志 key,用以标识一条日志记录 |
data | Record<string, any> | string | 日志 key 对应的数据 |
ua | string | 浏览器 navigator.userAgent 信息 |
url | string | 当前页面的 URL 信息 |
os | string | 当前设备的操作系统信息 |
osVersion | string | 当前设备的操作系统版本 |
traceId | string | 前后端约定的 UUID,用以追踪问题 |
sessionId | string | 会话 ID,用以区分同一会话范围内的日志 |
browser | string | 浏览器:Chrome、Safari、iOS Safari 等 |
browserVersion | string | 浏览器版本信息 |
container | string | 页面运行所在容器信息,如:钉钉、浏览器 |
device | string | 设备类型,如:手机、桌面端 |
clientTime | string | number | 客户端时间戳 |
七、贡献与反馈
我们欢迎社区贡献!如果您有功能建议、Bug 反馈或想参与开发,请提交 GitHub Issue 或 Pull Request。如果您觉得这个项目有用,不妨给它一个 Star 支持一下吧!
通过 awesome-logger
,您可以轻松实现前端日志的标准化、可观测性与灵活上报,让日志成为您应用稳定性的强大助力!快来体验吧!