开源 CLI 工具诊断日志设计：轻量级 Context 传递与结构化 Trace 捕获

开源 CLI 工具诊断日志设计：轻量级 Context 传递与结构化 Trace 捕获

开源 CLI 的 Issue 常以“运行mycli deploy报fatal error”的形式出现，缺少上下文时难以定位。

如果此时 CLI 工具打印的日志只有孤零零的一行exit status 1，维护者除了回复“请提供更详细的日志”之外别无选择。

但命令行工具与常驻的服务端微服务截然不同：CLI 运行在用户本地千差万别的 OS 环境中，不可能配置复杂的大型 OpenTelemetry Agent，也无法直接上传全量日志到云端。

因此，开源 CLI 工具的诊断系统必须兼顾轻量无侵入、本地结构化持久化以及一键导出调试证据。使用 Go 1.21+ 标准库原生的log/slog，就能优雅地完成这一机制的设计。

1. 设计思路：从“控制台终端输出”到“结构化诊断包”

为了不影响用户正常使用体验，我们将 CLI 的日志处理拆分为双通道：控制台屏幕仅输出简洁的彩色高亮信息，而后台文件打点器则保留包含完整堆栈、Context 字段与 Trace ID 的 JSON 结构化日志。

这不仅保护了终端界面的干净爽朗，也为开发者排查极端边界条件下的 Bug 留下了充足的诊断证据。

2. 生产级 Go 代码：基于log/slog的轻量诊断拦截器

下面展示了如何在零依赖前提下，使用 Go 标准库slog实现带有 Context 属性注入、错误堆栈自动捕获以及崩溃时导出日志的完整 CLI 日志中间件。

package clilog import ( "context" "fmt" "io" "log/slog" "os" "path/filepath" "runtime" "sync" "time" ) type contextKey string const traceIDKey contextKey = "cli_trace_id" // DiagnosticLogger 包装 slog 提供轻量级 CLI 日志处理 type DiagnosticLogger struct { logger *slog.Logger logFile *os.File mu sync.Mutex } func NewDiagnosticLogger(cliName string) (*DiagnosticLogger, error) { homeDir, err := os.UserHomeDir() if err != nil { homeDir = os.TempDir() } logDir := filepath.Join(homeDir, fmt.Sprintf(".%s", cliName), "logs") if err := os.MkdirAll(logDir, 0755); err != nil { return nil, fmt.Errorf("failed to create log directory: %w", err) } logPath := filepath.Join(logDir, "diagnostics.log") file, err := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644) if err != nil { return nil, fmt.Errorf("failed to open log file: %w", err) } // 通道 1: JSON 格式文件输出 (包含详细时间与源码行号) jsonHandler := slog.NewJSONHandler(file, &slog.HandlerOptions{ Level: slog.LevelDebug, AddSource: true, }) // 通道 2: 终端 Console 输出 (仅包含用户关心的 Info 及以上) consoleHandler := slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ Level: slog.LevelInfo, }) // 组合 MultiHandler multiHandler := &multiLogHandler{ fileHandler: jsonHandler, consoleHandler: consoleHandler, } logger := slog.New(multiHandler) return &DiagnosticLogger{ logger: logger, logFile: file, }, nil } // WithTraceID 生成带 Trace ID 的 Context func WithTraceID(ctx context.Context) context.Context { traceID := fmt.Sprintf("trace_%d_%d", time.Now().Unix(), os.Getpid()) return context.WithValue(ctx, traceIDKey, traceID) } func (l *DiagnosticLogger) ErrorContext(ctx context.Context, msg string, err error, args ...any) { l.mu.Lock() defer l.mu.Unlock() traceID, _ := ctx.Value(traceIDKey).(string) // 拼接异常参数与堆栈 attrs := append([]any{ slog.String("trace_id", traceID), slog.String("error", err.Error()), slog.String("go_version", runtime.Version()), slog.String("os_arch", fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH)), }, args...) l.logger.ErrorContext(ctx, msg, attrs...) } func (l *DiagnosticLogger) Close() { if l.logFile != nil { _ = l.logFile.Close() } } // multiLogHandler 简易分流 Handler 实现 type multiLogHandler struct { fileHandler slog.Handler consoleHandler slog.Handler } func (m *multiLogHandler) Enabled(ctx context.Context, level slog.Level) bool { return m.fileHandler.Enabled(ctx, level) || m.consoleHandler.Enabled(ctx, level) } func (m *multiLogHandler) Handle(ctx context.Context, record slog.Record) error { _ = m.fileHandler.Handle(ctx, record) if record.Level >= slog.LevelInfo { return m.consoleHandler.Handle(ctx, record) } return nil } func (m *multiLogHandler) WithAttrs(attrs []slog.Attr) slog.Handler { return &multiLogHandler{ fileHandler: m.fileHandler.WithAttrs(attrs), consoleHandler: m.consoleHandler.WithAttrs(attrs), } } func (m *multiLogHandler) WithGroup(name string) slog.Handler { return &multiLogHandler{ fileHandler: m.fileHandler.WithGroup(name), consoleHandler: m.consoleHandler.WithGroup(name), } }

3. 开源工程实践收获

将这套诊断日志方案集成到开源 CLI 工具中后，我们收到的用户 Issue 质量有了质的提升。现在遇到问题，用户只需粘贴一行~/.mycli/logs/diagnostics.log中自动生成的 JSON，我们就能清晰看到命令执行时的操作系统环境、Go Runtime 版本、传入的参数 Hash 以及准确的报错 Line Number。

开发轻量级的开源工具，并不意味着要放弃工程严谨度。用最小的标准库组件搭建好可观测试图，既尊重了用户的终端体验，也放大了开发者定位问题的效率。

先处理最可能伤害用户的路径

实现方案写得再完整，也要经得起维护时的追问：谁能修改、谁能定位、出问题后怎样停止。CLI 诊断信息应能由用户主动打开，默认输出只保留操作所需信息，避免日志噪声压过错误线索。 这几个问题不必等到事故发生后才回答，写在配置说明、接口注释或任务卡里都比口头约定可靠。

许多问题并非来自核心逻辑，而是来自默认值、超时、重试和权限这些边角。它们在演示里很安静，到了真实输入或并发变化时才露出来。对这些地方多做一次检查，往往比继续堆功能更划算。

文章中的方法可以按团队现有工具调整；真正要保住的是因果关系。知道某次改动为什么生效、又会在哪些条件下失效，后续才有稳妥的选择。

回到“开源 CLI 工具诊断日志设计：轻量级 Context 传递与结构化 Trace 捕获”，先把这些信号接到现有工作流。缺少必要信息时应明确标为待确认，不能用想象补上细节。

日志先服务于定位

诊断开关应支持按命令或请求打开，并对敏感字段做脱敏。用户需要定位问题时才增加细节，日常使用不该被大段日志淹没。

这一段不需要另起一套复杂流程。把必要的信息放进现有的发布记录、问题单或测试说明里即可：目标对象是什么，操作前后的状态怎样，未达到预期时采取了什么处理。信息越贴近当时的操作，后面定位越省时间。

对于“开源 CLI 工具诊断日志设计：轻量级 Context 传递与结构化 Trace 捕获”这类主题，最容易被忽略的是旧路径。新增能力能跑通不代表原有请求仍按预期工作，因此应保留一条不经过新逻辑的对照路径。出现差异时先比较输入与环境，再决定是否扩大改动范围。这样做会慢一点，但能避免把一次偶然波动写成长期结论。