如何设计灵活可扩展的前端日志解决方案：提升应用稳定性与可观测性

设计灵活可扩展的前端日志解决方案：提升应用稳定性与可观测性

在前端开发的世界里，日志记录是一项至关重要的任务。它不仅能够帮助开发者快速定位和解决问题，还能为应用的健康监控和性能优化提供有力支持。然而，随着项目的不断发展和业务需求的日益复杂，传统的日志记录方式往往难以满足灵活扩展的需求。本文将介绍一种灵活可扩展的前端日志解决方案——awesome-logger，并详细阐述其设计思路、架构特点以及使用方法。

一、设计目标与需求分析

在设计前端日志解决方案时，我们通常会面临以下几个关键需求：

1. 快速定位用户问题：能够自动收集完整的上下文信息，如操作系统、设备型号、用户代理等，以便在用户反馈异常时，能够快速定位问题根源。
2. 应用健康度监控：支持多等级日志管理，如 info、warn 和 error 级别，帮助开发者构建稳定性大盘，实时监控应用的健康状态。
3. 多日志系统同构上报：能够同时接入多个日志服务，如阿里云 SLS、腾讯云 CLS 等，实现一次上报同步多平台。
4. 自定义日志扩展：允许开发者根据业务需求自定义日志上报逻辑，如接入私有日志系统、进行数据加密等。
5. 高效开发与标准化：提供开箱即用的主流插件，减少基础设施的重复开发，提高开发效率。

二、awesome-logger 架构设计

awesome-logger 采用分层架构，确保功能解耦与扩展性，主要分为以下三层：

1. 核心层（@awesome-logger/core）
   • Logger 类：管理日志生成、等级控制及插件注册。提供 info、warn、error 等方法，支持基础字段配置。
   • LogPlugin 抽象类：定义插件开发规范。所有插件需实现 sendLog 方法，将日志数据发送到目标服务。
2. 插件层（@awesome-logger/plugin-*） 提供具体日志服务的实现。例如，@awesome-logger/plugin-sls 对接阿里云 SLS 日志服务。开发者可根据规范自定义插件，扩展日志能力。
3. 使用层（@awesome-logger/client）
   • Client 类：封装核心功能，简化用户接入。支持通过 usePlugin 注册插件，并提供统一的日志接口。

三、awesome-logger 核心优势

1. 内置标准化日志字段，助力高效排查 预定义了如 os（操作系统）、device（设备型号）、ua（用户代理）等关键环境字段，无需额外开发即可收集全面的上下文信息，帮助开发者快速定位问题根源。
2. 基础字段灵活配置，支持实时查询分析 允许用户自定义基础字段（如 uid、env 等），这些字段会自动附加到每条日志中。结合阿里云 SLS 等服务，可实现日志的实时过滤与查询，精准定位用户反馈场景。
3. 多等级日志管理，构建应用健康监控 支持 info、warn、error 等多种日志等级，帮助开发者建立稳定性大盘，实时监控应用健康状态。通过不同等级的日志分类，可快速识别潜在风险与异常。
4. 插件化架构设计，轻松对接任意日志服务 采用插件机制，开发者可自由扩展日志能力。内置支持阿里云 SLS、腾讯云 CLS 等主流日志服务，同时允许自定义插件，适配私有日志系统或其他第三方服务。

四、快速开始

1. 安装依赖

npm install @awesome-logger/client @awesome-logger/core @awesome-logger/plugin-sls

2. 初始化与配置

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. 日志上报

// 上报信息日志
client.info('enter_home_page', { page: 'home' });

// 上报警告日志
client.warn('api_timeout', { latency: 500 });

// 上报错误日志
client.error('api_fail', { errorCode: 500, endpoint: '/api/data' });

4. 日志上报到阿里云 SLS

效果如下图:

注意事项

1. 在使用 plugin-sls 之前，您需要创建一个阿里云账户。
2. 开通 SLS 日志服务，支持免费试用一个月，50GB 容量。
3. 创建一个日志项目（log project）。
4. 然后创建一个日志库（logstore，前端上报时记得开启 Web Tracking 选项）。
5. 上报一些日志后，方可创建索引。
6. 索引支持设置、追加和覆盖。

五、自定义插件开发

awesome-logger 支持开发者自定义插件，轻松对接私有日志系统或其他服务：

1. 创建插件类

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. 使用自定义插件

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，您可以轻松实现前端日志的标准化、可观测性与灵活上报，让日志成为您应用稳定性的强大助力！快来体验吧！