客户端日志规范指南

工程实践
1.4k 词

一、日志分类体系

1.1 核心分类矩阵

1.2 分类定义

类型 记录内容 存储周期
诊断日志 程序运行状态、异常堆栈 90天
统计日志 用户行为埋点、业务转化率 365天
审计日志 敏感操作记录、权限变更 永久

二、日志级别标准

2.1 五级日志对照表

级别 触发场景 采样率
DEBUG 开发环境调试日志 100%
INFO 常规流程节点记录 30%
WARNING 可恢复的异常状态 100%
ERROR 影响主流程的异常 100%
FATAL 导致应用崩溃的致命错误 100%

2.2 级别使用示例

1
2
3
4
5
6
7
8
9
10
// 关键函数调用记录
func didSelectItem(at index: IndexPath) {
    Logger.info("用户点击单元格", metadata: ["section": "2", "row": "5"])
  
    guard isValidIndex(index) else {
        Logger.error("非法索引路径", metadata: index.debugDescription)
        return
    }
    //...
}

三、关键场景日志规范

3.1 业务流程监控

1
2
3
4
5
6
7
8
9
10
11
12
@startuml
start
:流程开始;
:记录START日志;
if (关键操作) then (成功)
  :记录SUCCESS日志;
else (失败)
  :记录FAILURE日志;
endif
:流程结束;
:记录END日志;
@enduml

3.2 异常处理规范

1
2
3
4
5
6
7
8
9
10
{
  "error_code": "E1003",
  "error_type": "BUSINESS",
  "expected": false,
  "stack_trace": "...",
  "device_info": {
    "os_version": "iOS 16.4.1",
    "network": "WiFi"
  }
}

四、高级记录规范

4.1 耗时操作监控

1
2
3
4
5
6
7
8
9
fun handleLargeFile(file: File) {
    val traceId = Logger.beginTrace("FILE_PROCESSING")
    try {
        Logger.debug("开始处理文件", metadata: file.metadata)
        // 实际处理逻辑
    } finally {
        Logger.endTrace(traceId)
    }
}

4.2 环境信息记录

信息维度 采集字段 隐私处理
设备信息 型号、OS版本、分辨率 MD5哈希处理
网络环境 连接类型、信号强度、IP地址 脱敏处理
用户上下文 当前页面、登录状态、时区 加密存储

最佳实践推荐：

  1. 使用OpenTelemetry实现标准化日志采集
  2. 通过Grafana Loki构建日志监控体系
  3. 采用Splunk进行日志分析与告警

文档版本：v2.3.1
更新日期：2025-03-14