3. SDK 日志系统组成：模块、级别与输出目标
日志系统，说白了就是给程序装一个“黑匣子”。
出了问题，翻日志是最直接的办法。今天我们就来拆解 HSM SDK 的日志系统。
我个人习惯把日志系统分成三块：谁在记录（日志模块）、记录什么（日志级别）、记录到哪（输出目标）。
下面一个一个聊。
3.1 日志模块——谁在干活
HSM SDK 里日志模块不是单打独斗的。不同功能区域有自己的“笔者”。
我接手过一个项目，只看全局日志根本找不到根因。后来发现是加密模块和会话模块的日志混在一起了。
常见的日志模块划分方式：
- 核心库模块（libhsm）——记录初始化和销毁过程
- 会话管理模块——记录连接、断开、超时
- 密钥操作模块——记录密钥生成、导入、导出
- 加密/解密模块——记录算法调用和错误
- 网络通信模块——记录报文收发和握手状态
每个模块都有一个独立的名字标签，比如 [CORE]、[SESSION]、[KEY]。
在日志输出时，你会看到类似 [CORE] [ERROR] Device not found 这样的前缀。
例如怀疑会话断开，就用
grep '\[SESSION\]' /var/log/hsm.log。
3.2 日志级别——记多记少自己定
级别控制的就是“粗细粒度”。我见过不少同事把日志全开成 DEBUG，结果一天产生几十 GB 日志。
我说，你想想看，线上环境真的需要记录每次函数调用吗？
HSM SDK 通常支持以下级别（按严重性升序）：
| 级别 | 说明 | 典型场景 |
|---|---|---|
| TRACE | 最详细，几乎每行代码都打 | 开发调试，定位死循环或竞态 |
| DEBUG | 开发用，含变量值和流程节点 | 功能开发、单元测试 |
| INFO | 正常运行信息 | 服务启动、连接建立、任务完成 |
| WARN | 异常但不影响继续运行 | 证书即将过期、重试超过 3 次 |
| ERROR | 功能受损，需要人工介入 | 签名失败、密钥不可用、设备断开 |
| FATAL | 系统不可恢复，直接退出 | HSM 固件崩溃、内存耗尽 |
选级别有个原则：线上环境至少设为 WARN，只有追踪特定 bug 时才短期开 INFO 或 DEBUG。
后来我强制在应用层加了一个逻辑：
if (currentLevel <= LOG_LEVEL_INFO) return; 防止误配置。
3.3 日志输出目标——流向哪里
日志打出来总得有个去处。HSM SDK 通常支持以下输出目标：
- stdout/stderr——直接输出到终端，适合调试，不适合生产
- 文件——最常用，可配置日志轮转（rotate）
- syslog——Linux 系统日志，适合集中管理
- 远程日志服务器——通过 TCP/UDP 发送，适合分布式场景
- Windows 事件日志——仅 Windows 平台
每个目标都有自己的配置参数。举个例子，文件输出需要设置：路径、最大大小、保留份数、自动压缩开关。我习惯把 max_file_size 设为 10 MB，保留 5 个备份，避免长期堆积。
# 示例：HSM SDK 日志配置（简化）
[log]
level = WARN
output = file
file.path = /var/log/hsm/hsm.log
file.max_size_mb = 10
file.max_backup = 5
file.compress = true也可以同时输出到多个目标。比如文件作为持久存储，syslog 作为实时告警。
syslog 可以配置远程服务器，这样即使 HSM 主机挂了，日志也能保留。
3.4 三者之间的关系——一张图说清楚
下面我用一张 SVG 图把模块、级别、输出目标串起来。你看完应该能秒懂整个日志流动过程。
流程很清晰：应用代码调用日志接口，带上模块标签；然后进入级别过滤器，低于设定级别的直接丢弃；通过的消息被路由到所有配置的输出目标。
3.5 配置示例——实战中长什么样
最后放一个真实项目里的配置文件片段。HSM SDK 通常通过环境变量或配置文件控制。
# hsm_sdk_log.conf
[log]
enable = true
default_level = WARN
[log.module]
CORE = DEBUG # 调试核心模块，临时开
SESSION = WARN
KEY = ERROR
CRYPT = WARN
[log.output]
target = file,syslog
[log.output.file]
path = /var/log/hsm/hsm.log
max_size = 10M
backup = 3
[log.output.syslog]
facility = local0
default_priority = WARN你想想看，有了这种配置，排查问题时可以单独降低某个模块的级别。比如怀疑核心模块初始化有问题，我把 CORE 改为 DEBUG，其他模块继续保持 WARN，这样日志量可控，信息又够用。
好了，日志系统的三块拼图——日志模块、日志级别、输出目标——你已经清楚了。
下回看日志的时候，试着先识别这三块，排查效率至少提升一倍。