用途
Logging 是一套客户端(浏览器端)的结构化日志、错误上报与分析事件模式,适用于实现控制台日志、错误追踪、用户会话追踪或分析事件等场景。其核心理念是:日志应当结构化、可 JSON 序列化以便解析;不同环境需要不同的详细程度,可按日志级别过滤;需具备隐私意识,绝不记录 PII 或敏感数据;关键日志应可靠投递,使用 sendBeacon。
主要能力
- 日志级别:定义 LogLevel 枚举,ERROR: 0、WARN: 1、INFO: 2、DEBUG: 3;并通过 getLogLevel 从环境读取级别(window.LOG_LEVEL,默认 info)。
- 环境配置:在脚本加载前于 HTML 中设置 window.LOG_LEVEL,例如开发环境设为 debug、生产环境设为 warn。
- 结构化 Logger:createLogger 输出可 JSON 序列化的结构化数据,包含 level、message、timestamp、sessionId、url 及自定义 data;开发环境输出带颜色的可读控制台信息,生产环境输出 JSON 以便日志聚合。
- 控制台增强(开发用):createDevConsole 提供 labeled 带样式标题输出、group 分组、table 表格展示、time 计时与 timeAsync 异步计时。
- 错误上报:createErrorReporter 支持通过 navigator.sendBeacon 可靠上报错误(页面卸载时仍可用),失败时回退到 keepalive 的 fetch;可设置用户 ID,并可安装全局处理程序捕获未捕获错误与未处理的 Promise 拒绝。
- 会话上下文:createSessionContext 记录 sessionId、userId、entryPage、referrer、userAgent、startTime,可设置用户、获取会话时长并导出为 JSON。
- 分析事件:createAnalytics 提供 track 自定义事件、pageView 页面浏览、click 点击追踪,采用队列与防抖(1 秒)批量发送,并在页面可见性变为 hidden 时刷新队列。
- 性能日志:createPerformanceLogger 提供 mark、measure、time(超过 100ms 时告警)以及 logWebVitals(LCP、FID、CLS)。
- 隐私处理:SENSITIVE_FIELDS 列出不应记录的字段(password、token、secret、apiKey、creditCard、ssn、authorization),提供 scrubSensitiveData 脱敏对象与 scrubEmails 替换邮箱;createConsentLogger 支持基于同意的分析日志记录。
使用方式
该技能以 JavaScript 代码模板形式提供。按需引入上述函数:创建 logger 实例后调用 logger.info / warn / error / debug;开发时使用 dev.labeled、dev.group、dev.table、dev.time;配置错误上报端点后安装全局处理程序并设置用户;创建 analytics 实例后调用 track、pageView、click 并调用 flush;需要隐私保护时使用脱敏函数与同意包装。代码中所有示例、注释与函数签名均以其原始形式给出。
适用场景
需要在前端实现结构化控制台日志、集中式错误追踪、用户会话关联、分析事件采集以及性能指标(Web Vitals)记录的项目。
限制
本资料未提供安装命令、包管理方式、版本信息、收费或价格、平台兼容性范围及具体效果数据,均暂未提供。资料末尾关联技能(observability、javascript-author)的说明文字不完整。