日志等级定义与分类标准
日志等级这东西，说起来简单，用起来容易乱。我见过不少团队把 INFO 当成万能等级，线上跑起来刷得满屏都是，真出问题根本找不到重点。也有团队把所有异常都扔到 ERROR，结果告警系统天天响，反倒没人看了。
先定个调子：日志等级不是越多越好，也不是越少越好。关键是每一级都有自己的职责。咱们先看看业界常用的标准，再结合加密 SDK 的场景，说说怎么用才顺手。
标准日志等级定义
最通用的五级模型，从低到高依次是：DEBUG、INFO、WARNING、ERROR、CRITICAL。有些框架还会加 TRACE 或 FATAL，但核心还是这五个。
| 等级 | 含义 | 典型使用场景 | 加密 SDK 举例 |
|---|---|---|---|
| DEBUG | 调试信息，开发阶段使用 | 变量值、函数入口/出口、性能耗时 | 密钥派生参数、加密中间结果 |
| INFO | 正常流程的关键里程碑 | 系统启动、配置加载、任务完成 | 会话建立、证书验证通过 |
| WARNING | 潜在问题，但系统仍可用 | 配置项已弃用、重试即将超限 | 证书即将过期、随机数质量偏低 |
| ERROR | 功能级别的错误或异常 | 操作失败、输入校验不通过 | 解密失败、签名校验不匹配 |
| CRITICAL | 系统级严重故障，需立即介入 | 内存耗尽、关键资源不可用 | 安全模块崩溃、硬件安全模块离线 |
嗯，这表基本够用了。但我个人习惯还会加一层 TRACE，专门记录函数调用链和参数详情，开发完直接关掉，线上不开。
分类标准：按什么维度切
光有等级还不够，你想想看，一个加密 SDK 包含密钥管理、加解密运算、网络传输、硬件交互这么多模块，所有日志混在一起，还是没法查。所以还要考虑分类。
我归纳了三种常用的分类维度：
- 按严重程度 —— 就是上面五级，竖向切。
- 按功能模块 —— 横向切，比如
KEY_MGMT、CRYPTO_OP、NETWORK、HSM。 - 按日志性质 —— 比如 业务日志（加密操作的业务上下文）、系统日志（内存、线程、资源）、安全日志（认证、授权、敏感操作）。
记得有一次，我在定位一个联机加密失败的问题。客户端说加密成功，服务端说解密失败。两边日志等级全是 ERROR，但没有模块分类，根本不知道是算法不一致还是密钥不对。后来我强制要求 SDK 输出日志时必须带上模块标签，问题一下就暴露了——原来是客户端用了 SM4，服务端还在用 AES。所以说，分类比等级还重要。
黄金组合：等级 + 模块 + 上下文
很多日志框架支持用 logger.crypto.error("decrypt failed, key_id={}", keyId) 这种方式，既定了等级，又带了上下文。我建议把这三者有意识地组合：
- 等级：控制日志是否输出，线上一般开到
WARNING以上。 - 模块：方便 grep 或过滤，一眼定位到出问题的子域。
- 上下文：记录 session ID、transaction ID、密钥句柄等，用于关联前后端。
这里有个坑，我走过一次——曾经把密钥内容直接打印到日志里。幸好那是测试环境，生产环境这么干就严重泄露了。所以加密 SDK 的上下文日志必须做脱敏处理，比如密钥只打前 4 位和后 4 位，中间用 **** 代替。
日志等级使用建议（加密 SDK）
我总结了一个简单的决策树，帮你判断某条日志该用哪一级：
| 条件 | 推荐等级 |
|---|---|
| 只在开发调试时关注 | DEBUG / TRACE |
| 正常流程的标志性事件 | INFO |
| 一种可恢复的异常状态 | WARNING |
| 功能请求失败，但系统整体可用 | ERROR |
| 系统即将无法提供正常服务 | CRITICAL |
特别提醒：INFO 和 DEBUG 的边界，很多人分不清。我的原则是——如果线上开了 INFO 之后，这条日志每秒出现超过 10 次，那它就应该是 DEBUG。加密 SDK 里像「密钥加载成功」这种每天只出现几次的，算 INFO；而「计算哈希值耗时 X ms」这种高频细节，必须 DEBUG。
小技巧： 在初始化时通过环境变量或配置文件动态设置日志级别，比如 LOG_LEVEL=DEBUG 只在 debug 模式下生效，线上默认为 WARNING。这样开发阶段可以打开所有细节，线上又不会出现性能开销。
标准日志格式
光定义了等级和分类还不够，日志本身的格式也要统一。我推荐的结构是：
[时间] [等级] [模块] [线程ID] [会话ID] 消息内容 [键值对上下文]示例：
2025-06-30 14:23:45.123 WARN [KEY_MGMT] [thr-12] [sess-9ab3] 证书即将过期，剩余天数：15 cert_serial=0xABCDEF这么写的好处是：所有日志分析工具（比如 ELK、Graylog）都能直接解析字段，搜索和聚合非常快。我见过一些团队直接把异常堆栈打在一行里，整行超过 2000 个字符，导致日志系统截断——嗯，所以每个字段都要控制长度，堆栈可以拆成多行。
等级与分类的联动关系图
下面这张图展示了我认为比较合理的日志体系结构。从下到上是等级递增，从左到右是分类扩展。橙色框是需要注意的地方——安全相关日志即使只是 INFO，也建议额外归档。
核心理念：
- 等级是“阀门” —— 控制日志的产量和粒度。
- 分类是“标签” —— 帮助快速过滤和定位。
- 上下文是“线索” —— 关联分布式调用链的唯一凭证。
三者缺一不可，尤其是在加密 SDK 这种对安全性和可追溯性要求极高的场景。
常见错误与避坑
最后聊几个我踩过的坑：
- 把所有异常都打成
ERROR—— 这不合理。比如重试 3 次后成功，第一次失败可以WARNING，第三次还失败才ERROR。 - 打印敏感信息 —— 除了密钥本身，还有 IV、nonce、认证令牌等，都要做脱敏或直接不打印。
- 日志等级混乱 —— 同一个团队用同一个等级白皮书，否则 A 觉得
INFO就够了，B 非要ERROR。 - 忽略日志的性能开销 —— 加密运算本身就重，日志打印太多会雪上加霜。我建议在
DEBUG等级下加一个频率限制，比如每秒同一个日志最多输出 10 次。
曾经有一个线上事故，就是因为 HSM 连接失败，try-catch 里每 100ms 打印一次 ERROR，结果 10 分钟写了 2GB 日志，磁盘撑爆，整个服务挂掉。所以日志等级和频率控制，真的不能忽视。
警告： 生产环境绝不要开 DEBUG 或 TRACE 级别，除非你明确知道自己在做什么，并且有完善的日志轮转策略。加密 SDK 的调试日志可能包含大量中间状态，开启后不仅影响性能，还可能暴露内部算法细节。
好了，这一章的核心就是——把等级、分类、上下文三个维度对齐，配合严格的脱敏和频率控制，才算是一套合格的加密 SDK 日志体系。你可以在项目落地时直接拿这个框架去套，遇到具体场景再微调。