系统工具日志设计:默认安静,出问题时足够详细
一、日志不是越多越专业
写系统级工具时,我一开始很喜欢到处打印日志,感觉这样比较可控。但真正使用时会发现,日志太多会淹没关键信息。CLI 工具默认应该安静,成功时只输出用户需要的结果;出问题时,才提供足够定位的信息。日志设计也是用户体验。
对于 AI 工具、WASM 插件运行器或文件扫描器,日志至少要回答:执行了什么、耗时多久、失败在哪、有没有请求 ID、是否重试、影响了哪些文件。默认输出和调试输出要分开,否则用户复制结果时会带上一堆内部信息。
我帮团队排查过一次问题。同事的 CLI 工具失败了,他把终端输出复制给我。我翻了 200 行日志,全是 debug: enter function parse_config、debug: reading line 23 这类内部信息,真正有用的错误出现在第 187 行。更糟的是,失败信息夹杂在进度输出和换行里,乱成一团。如果一开始就把默认输出和调试信息分开,排查时间至少减半。
二、日志层级:结果输出和诊断信息分离
flowchart TD
A[工具执行] --> B[用户结果 stdout]
A --> C[诊断日志 stderr]
C --> D[info]
C --> E[warn]
C --> F[error]
C --> G[debug]
命令行工具里,stdout 适合放机器可读或用户真正要的结果,stderr 适合放进度、警告和错误。这样用户可以把 stdout 重定向到文件,而不被日志污染。很多成熟 CLI 都遵循这个习惯,自己写工具时也应该学起来。
日志级别要有边界。info 记录关键阶段,warn 记录可恢复异常,error 记录最终失败,debug 记录请求参数摘要、耗时和内部状态。不要把所有东西都打成 info。默认模式下,debug 不应出现。
三、代码示例:tracing 初始化
Rust 里可以用 tracing 和 tracing-subscriber 管理日志。下面是一个简化初始化。
use tracing_subscriber::EnvFilter;
pub fn init_logging(verbose: bool) {
let level = if verbose { "debug" } else { "warn" };
tracing_subscriber::fmt()
.with_env_filter(EnvFilter::new(level))
.with_target(false)
.init();
}
业务代码里可以写结构化字段:
tracing::info!(
command = "cargo test",
elapsed_ms = 1280,
"command finished"
);
结构化字段比拼字符串更适合后续分析。即使现在只是终端输出,将来接入文件日志或 JSON 日志时,也更容易扩展。
生产环境实战经验
用 tracing 的一大好处是可以给日志加 context。比如文件处理工具里,每个文件的日志都携带 file_name 和 request_id。当批量处理 500 个文件,其中一个失败时,不用翻全量日志,直接 grep request_id=xxx。但注意 span 太多会有性能开销。我测了一次,每个 span 大约增加 2-3 微秒。处理十万级文件时,这笔开销需要考虑。
四、隐私和安全:日志不要泄漏密钥
AI 工具很容易处理 API Key、Prompt、文件内容和模型响应。日志里不要打印完整密钥,也要谨慎打印用户输入。可以记录长度、hash、文件路径和请求 ID,而不是完整敏感内容。调试方便不能换来凭据泄漏。
一个日志泄漏密钥的真实教训
团队一个内部工具在 debug 模式下输出了完整的 HTTP 请求 body,其中包含了 API Key。这份日志被轮转到一个只读共享目录,谁都能看到。虽然后来改了,但那几个小时暴露的 Key 需要全部轮换。从那以后,我在所有日志初始化的地方加了一个过滤器:任何看起来像 sk- 或 Bearer 开头的内容,一律替换为 ***REDACTED***。这个过滤器还加了测试,确保未来不会漏。
错误日志要能定位,但不要吓人。用户配置错时,提示应该说明缺少哪个字段、如何修复;网络失败时,说明是否可以重试;内部 bug 才需要建议开启 verbose 或提交 issue。日志不是给作者一个人看的,也要照顾使用者。
最后,长任务需要进度,但进度不等于日志。可以用进度条或阶段提示,完成后保持输出干净。失败时再展示详细日志路径。默认安静,调试有料,这是我现在更喜欢的工具气质。
五、总结
系统工具日志设计要区分用户结果和诊断信息,默认安静,出问题时足够详细。stdout/stderr 分离、日志级别清晰、结构化字段、敏感信息脱敏,是 Rust CLI 和 Agent 工具都应该具备的基础能力。
435



被折叠的 条评论
为什么被折叠?



