掌握 HiLog 五级日志规范、建立日志隐私脱敏体系、落地远程日志采集与崩溃日志联动、实现线上问题"分钟级定位"

---

一、前置思考：日志是线上问题的"唯一现场"

1.1 没有日志，线上问题就是盲人摸象

问题类型	没有日志	有规范日志
崩溃	只有堆栈	崩溃前操作路径 + 关键状态
卡顿	不知道哪帧卡	主线程耗时记录
功能异常	用户说不清	完整调用链 + 参数
数据错误	无从查起	输入输出快照

核心认知：日志不是"事后补丁"，而是埋点即设计——每个关键路径的日志
都是线上定位的一枚坐标。

1.2 日志体系的三大目标

目标	说明
分级输出	生产/开发不同级别，噪音可控
隐私合规	敏感数据必须脱敏（个保法/上架要求）
可溯源	崩溃/卡顿能回溯到操作路径

1.3 日志的代价

日志也有成本：写入开销 + 存储开销 + 隐私风险。

维度	影响	对策
性能	高频日志写 IO	分级控制频率
体积	日志膨胀	滚动裁剪/压缩
隐私	敏感信息泄露	强制脱敏
噪音	淹没关键信息	分级 + Tag 规范

---

二、核心原理：HiLog 分级体系

2.1 HiLog 五级日志

HarmonyOS 的日志能力为 HiLog，提供五级输出：

级别	API	含义	使用场景
DEBUG	hilog.debug	调试	开发期临时信息
INFO	hilog.info	信息	关键流程节点
WARN	hilog.warn	警告	可恢复异常
ERROR	hilog.error	错误	业务失败
FATAL	hilog.fatal	致命	不可恢复

import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0001;              // 业务域(16进制)
const TAG = 'OrderService';

hilog.info(DOMAIN, TAG, '创建订单开始, userId=%{public}s', 'u_1001');
hilog.warn(DOMAIN, TAG, '库存不足, 回退订单 %{public}d', 10086);
hilog.error(DOMAIN, TAG, '支付回调失败, error=%{public}d', -1);

2.2 隐私占位符（核心特性）

HiLog 的格式占位符自带隐私控制：

占位符	含义	显示
%{public}s	公开信息	明文显示
%{private}s	隐私信息	显示为 <private>
%{public}d	公开数字	明文
%{public}j	公开JSON	明文

// ❌ 手机号明文输出 (隐私泄露风险)
hilog.info(DOMAIN, TAG, '登录成功, phone=%{public}s', userPhone);

// ✅ 手机号隐私占位 (日志中显示 <private>)
hilog.info(DOMAIN, TAG, '登录成功, phone=%{private}s', userPhone);
// 日志显示: 登录成功, phone=<private>

关键认知：%{private}s 在日志中直接输出 <private>，
日志文件层面就已脱敏——这是 HiLog 最强大的安全特性。

2.3 日志开关与级别控制

生产环境应控制日志输出级别，避免性能与噪音：

// 运行时日志级别开关
let currentLevel = 3;   // 0=debug 1=info 2=warn 3=error

function log(level: number, tag: string, msg: string): void {
  if (level < currentLevel) { return; }   // 低于阈值的丢弃
  switch (level) {
    case 0: hilog.debug(0x0001, tag, '%{public}s', msg); break;
    case 1: hilog.info(0x0001, tag, '%{public}s', msg); break;
    case 2: hilog.warn(0x0001, tag, '%{public}s', msg); break;
    default: hilog.error(0x0001, tag, '%{public}s', msg); break;
  }
}

---

三、源码/API 深度解析：完整日志体系

3.1 隐私脱敏体系

除了 HiLog 隐私占位符，业务层还需自定义脱敏规则（覆盖字符串拼接场景）：

// 脱敏工具: 手机号/身份证/邮箱/Token
export class MaskUtil {
  /** 手机号: 138****1234 */
  static maskPhone(phone: string): string {
    if (phone.length < 7) { return '***'; }
    return phone.substring(0, 3) + '****' + phone.substring(phone.length - 4);
  }

  /** 身份证: 110***********1234 */
  static maskIdCard(id: string): string {
    if (id.length < 8) { return '***'; }
    return id.substring(0, 3) + '***********' + id.substring(id.length - 4);
  }

  /** Token: 只留前 4 位 */
  static maskToken(token: string): string {
    if (token.length <= 4) { return '****'; }
    return token.substring(0, 4) + '****';
  }
}

// 使用: 日志统一走脱敏
hilog.info(0x0001, 'Login', '用户 %{public}s 登录, token=%{public}s',
  MaskUtil.maskPhone(phone), MaskUtil.maskToken(token));

脱敏规则表：

数据类型	规则	示例
手机号	前3后4	138****1234
身份证	前3后4	110***********1234
银行卡	后4位	**** **** **** 5678
Token/密钥	前4后4	abcd****wxyz
邮箱	用户名打码	a***@example.com
地址	小区级截断	北京市****

3.2 远程日志采集

架构：本地日志环形缓冲 → 定期打包 → 上报服务器 → 分析看板。

应用进程
  ├─ HiLog 输出 → 本地环形缓冲(内存) + 落盘
  ├─ 定期(如30s/触发条件) → 打包压缩 → 上传
  └─ 崩溃时 → 自动附带最近N条日志 → FaultLogger

服务器: 解析 → 聚类 → 看板 → 告警

// 日志上报器（伪代码示意）
export class LogReporter {
  static report(tag: string, level: number, msg: string): void {
    // 1. 写入环形缓冲
    RingBuffer.push({ tag, level, msg, time: Date.now() });
    // 2. 达到批量阈值或定时 → 上传
    if (RingBuffer.size() >= 50) {
      this.upload(RingBuffer.drain());
    }
  }

  static upload(batch: LogItem[]): void {
    // 压缩 + 加密 + 上报
    const body = compress(JSON.stringify(batch));
    httpPost('/log/collect', body);
  }
}

上报策略：

策略	说明
定时批量	每 30s 或 50 条一次
触发上报	崩溃/ANR 时立即附带
网络条件	WiFi 全量, 蜂窝只传错误级
隐私过滤	上报前统一脱敏
采样控制	用户量按比例采样

3.3 崩溃日志：FaultLogger

HarmonyOS 提供 FaultLogger 查询崩溃/卡死日志：

import { faultLogger } from '@kit.PerformanceAnalysisKit';

// 查询最近崩溃日志
const faultType = faultLogger.FaultType.JS_CRASH;
faultLogger.query(faultType, 10).then((logs) => {
  for (const log of logs) {
    // log.reason: 崩溃原因
    // log.stack: 完整堆栈
    // log.summary: 摘要
    handleCrashReport(log);
  }
});

崩溃日志内容：

字段	说明
reason	崩溃原因（空指针/越界/类型错误）
stack	完整调用堆栈
summary	崩溃摘要
appVersion	版本号（定位回归）
deviceInfo	设备信息
osVersion	系统版本
moduleName	模块名

与业务日志联动：崩溃日志 + 环形缓冲的业务日志 = 完整"事故现场"。

3.4 日志规范：Tag 与格式

规范	示例	目的
Tag 分级	OrderService / UI_Home	按模块隔离
统一前缀	[Order]	快速检索
上下文编号	orderId=10086	关联链路
结构化字段	key=value	可解析
级别正确	错误用 error 不用 info	告警准确

---

四、企业级实战：日志体系落地

4.1 采集架构总览

                     ┌─────────────────────────────┐
                     │         服务器端              │
                     │ 日志接收 → 解析 → 索引 → 看板  │
                     └──────────────┬──────────────┘
                                    │ 上报(加密/压缩)
┌───────────────────────────────────┴───────────────────┐
│                      客户端                            │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐            │
│  │ HiLog    │  │ 业务日志  │  │ 崩溃日志   │            │
│  │ 分级输出  │→ │ 脱敏+缓冲 │→ │ FaultLogger│            │
│  └──────────┘  └──────────┘  └───────────┘            │
└───────────────────────────────────────────────────────┘

4.2 埋点即设计：关键路径日志清单

关键路径	必打日志
启动	各阶段耗时（联动 31 篇）
网络请求	URL/参数摘要/耗时/状态码
登录	用户标识(脱敏)/结果
支付	订单号/状态流转
崩溃前	最近操作路径
数据同步	增量/冲突记录

4.3 线上问题定位闭环

步骤	动作	耗时
① 告警	崩溃率/错误率超阈值告警	分钟级
② 拉日志	平台按版本/设备拉取日志	分钟级
③ 关联	崩溃栈 + 业务日志上下文	分钟级
④ 定位	找到根因	小时级
⑤ 修复	发版 + 验证	天级

目标：从"用户报障 → 定位根因"控制在 1 小时内。

4.4 日志成本控制

手段	效果
分级阈值	生产仅 warn+ 落盘
环形缓冲	内存日志有上限
压缩上报	减少流量
采样	大用户量按比例
定时清理	本地日志 7 天滚动

---

五、排查与优化：日志体系自检

5.1 日志规范自检清单

• 所有日志是否使用 HiLog 分级 API？
• 敏感字段是否用 %{private}s 或脱敏工具？
• 生产环境日志级别是否合理？
• Tag 是否按模块统一规范？
• 关键路径是否都有日志埋点？
• 日志上报是否加密压缩？
• 崩溃日志是否与业务日志联动？
• 本地日志是否有滚动清理？
• 上报是否按网络条件分级？
• 是否有日志查询平台/看板？

5.2 高频坑点速查

• 日志里有没有打明文手机号/Token？
• 是否用字符串拼接代替 HiLog 占位符？
• 生产环境是否还开着 debug 全量日志？
• 有没有 Tag 混乱无法检索？
• 崩溃时能否拿到操作路径？
• 上报失败是否有重试？
• 日志是否导致主线程卡顿（高频打点）？
• 敏感字段是否在多处重复拼接暴露？

---

六、总结与进阶

6.1 收益模型（参考实测）

指标	治理前	治理后
问题定位平均耗时	2.5 天	3 小时
崩溃现场完整度	20%	85%
隐私泄露事件	季度 3 起	0 起
日志噪音	海量	分级可控
线上问题闭环率	40%	92%

6.2 工程规范

1. 日志统一封装：通过工具类输出，强制占位符与脱敏；
2. 分级阈值：debug 全量 / release 仅 warn+；
3. 埋点评审：关键路径日志纳入 CR 清单；
4. 脱敏红线：手机号/身份证/Token 强制脱敏（自动化检查）；
5. 崩溃联动：崩溃上报自动附带环形缓冲日志（第 40 篇联动）。

6.3 进阶方向

• 结构化日志：JSON 格式输出便于机器解析；
• 日志检索平台：ElasticSearch 类日志中心；
• 行为轨迹回放：用户操作路径完整重建；
• 日志与监控大盘：错误率/日志量接入看板（第 41 篇联动）。

---

附：Demo 演示说明

Tab	演示内容
📜 日志分级	HiLog 五级输出演示（debug→fatal 不同颜色）
🔒 隐私脱敏	手机号/身份证/Token 脱敏前后对照（%{private}s 原理）
📡 远程采集	本地缓冲 → 打包 → 加密上报 采集链路演示
💥 崩溃日志	FaultLogger 崩溃日志字段解析（reason/stack/version）
📊 日志规范	Tag/格式/级别规范清单 + 治理收益对比