系统工具日志设计：默认安静，出问题时足够详细

系统工具日志设计默认安静出问题时足够详细一、日志不是越多越专业写系统级工具时我一开始很喜欢到处打印日志感觉这样比较可控。但真正使用时会发现日志太多会淹没关键信息。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_idxxx。但注意 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 工具都应该具备的基础能力。