351 lines
8.7 KiB
Markdown
351 lines
8.7 KiB
Markdown
# slog Structured Logging Design
|
||
|
||
日期：2026-07-02
|
||
|
||
## 目标
|
||
|
||
为 codespace 后端增加基于 Go 标准库 `log/slog` 的结构化日志。目标是建立清晰、低噪音、不会泄露用户内容的日志边界，而不是到处撒日志。
|
||
|
||
本次目标：
|
||
|
||
- 使用 `log/slog` 替代当前 `log.Logger`。
|
||
- 默认输出 JSON 日志。
|
||
- 支持日志 level 和 format 配置。
|
||
- 为 Gin 增加 request logging middleware。
|
||
- 记录 workspace/process 生命周期关键事件。
|
||
- 建立全局约束：后续所有应用日志都必须使用 `log/slog`。
|
||
- 不记录文件内容、请求 body、token、环境变量、OpenCode 输出、宿主机绝对路径。
|
||
|
||
## 当前状态
|
||
|
||
当前代码：
|
||
|
||
- `pkg/logger.New()` 返回 `*log.Logger`。
|
||
- `cmd/server/main.go` 使用 `log.Fatalf` 和 `lg.Printf`。
|
||
- `internal/api.NewRouter(...)` 没有 logger 参数。
|
||
- Gin router 使用 `gin.New()` + `gin.Recovery()`。
|
||
- service/process/workspace 层基本没有日志。
|
||
|
||
## 非目标
|
||
|
||
本次不做：
|
||
|
||
- 不引入第三方日志库。
|
||
- 不接入 OpenTelemetry、Prometheus、ELK、Loki。
|
||
- 不实现 request ID / trace ID。
|
||
- 不记录文件内容、请求 body、OpenCode stdout/stderr。
|
||
- 不记录 workspace root 绝对路径。
|
||
- 不在高频文件读写路径里打业务日志。
|
||
- 不增加认证、CORS、rate limit、Git、LSP、Agent 功能。
|
||
|
||
## 全局日志约束
|
||
|
||
从本次改动开始，后续所有应用日志必须走 `log/slog`。
|
||
|
||
禁止在应用代码中重新引入这些旁路日志方式：
|
||
|
||
- `log.Printf` / `log.Println` / `log.Fatal` / `log.Fatalf`，除非是在 logger 初始化失败前的最后兜底。
|
||
- `fmt.Print*` 用作日志。
|
||
- `gin.Logger()` 或 `gin.Default()` 隐式 request logger。
|
||
- 第三方日志库。
|
||
|
||
允许：
|
||
|
||
- 测试中使用 `t.Log*`。
|
||
- CLI/工具脚本中显式面向用户的 stdout 输出，但不能混进服务端运行路径。
|
||
- logger 初始化失败之前，`cmd/server/main.go` 可以使用标准库 `log.Fatalf` 作为兜底，因为此时 slog logger 尚未存在。
|
||
|
||
验证方式：
|
||
|
||
```sh
|
||
grep -R "log\.Printf\|log\.Println\|log\.Fatal\|fmt\.Print\|gin\.Default\|gin\.Logger" cmd internal pkg || true
|
||
```
|
||
|
||
预期只允许出现 logger 初始化失败前的兜底 `log.Fatalf`，不允许出现运行期旁路日志。
|
||
|
||
## 配置设计
|
||
|
||
`configs/config.yaml` 增加：
|
||
|
||
```yaml
|
||
log:
|
||
level: "info"
|
||
format: "json"
|
||
```
|
||
|
||
`pkg/config` 增加：
|
||
|
||
```go
|
||
type LogConfig struct {
|
||
Level string `yaml:"level"`
|
||
Format string `yaml:"format"`
|
||
}
|
||
```
|
||
|
||
`Config` 增加：
|
||
|
||
```go
|
||
type Config struct {
|
||
Server ServerConfig `yaml:"server"`
|
||
Workspace WorkspaceConfig `yaml:"workspace"`
|
||
Process ProcessConfig `yaml:"process"`
|
||
Log LogConfig `yaml:"log"`
|
||
}
|
||
```
|
||
|
||
默认值：
|
||
|
||
- `level`: `info`
|
||
- `format`: `json`
|
||
|
||
环境变量：
|
||
|
||
- `CODESPACE_LOG_LEVEL`
|
||
- `CODESPACE_LOG_FORMAT`
|
||
|
||
支持 level：
|
||
|
||
- `debug`
|
||
- `info`
|
||
- `warn`
|
||
- `error`
|
||
|
||
支持 format：
|
||
|
||
- `json`
|
||
- `text`
|
||
|
||
虽然默认使用 JSON，但保留 text 是低成本本地调试能力。
|
||
|
||
## Logger 包设计
|
||
|
||
`pkg/logger` 改为创建 `*slog.Logger`：
|
||
|
||
```go
|
||
func New(cfg config.LogConfig) (*slog.Logger, error)
|
||
```
|
||
|
||
行为：
|
||
|
||
- `format=json` 使用 `slog.NewJSONHandler(os.Stdout, opts)`。
|
||
- `format=text` 使用 `slog.NewTextHandler(os.Stdout, opts)`。
|
||
- `level` 解析成 `slog.LevelDebug/Info/Warn/Error`。
|
||
- 非法 level 或 format 返回 error。
|
||
- 成功创建后调用 `slog.SetDefault(lg)`。
|
||
|
||
不保留旧 `*log.Logger` 包装层。项目还小，直接切干净。
|
||
|
||
## main.go 设计
|
||
|
||
启动流程：
|
||
|
||
1. 先加载 config。
|
||
2. 用 `logger.New(cfg.Log)` 初始化 slog。
|
||
3. 初始化失败时使用标准库 `log.Fatalf`，因为此时结构化 logger 还不存在。
|
||
4. 后续全部使用 `lg.Info/Warn/Error`。
|
||
|
||
启动日志：
|
||
|
||
```go
|
||
lg.Info("server starting",
|
||
"addr", cfg.Server.Addr,
|
||
"workspace_root", cfg.Workspace.Root,
|
||
"read_timeout", cfg.Server.ReadTimeout.String(),
|
||
"write_timeout", cfg.Server.WriteTimeout.String(),
|
||
"idle_timeout", cfg.Server.IdleTimeout.String(),
|
||
"max_header_bytes", cfg.Server.MaxHeaderBytes,
|
||
)
|
||
```
|
||
|
||
注意：启动日志可以记录配置里的 workspace root，因为这是服务启动配置；但 request/process/workspace lifecycle 日志不记录宿主机绝对路径。
|
||
|
||
错误日志：
|
||
|
||
```go
|
||
lg.Error("server failed", "error", err)
|
||
os.Exit(1)
|
||
```
|
||
|
||
`slog` 没有 `Fatal`，不要自己造复杂 wrapper。
|
||
|
||
## Gin request logging middleware
|
||
|
||
新增 middleware：
|
||
|
||
```go
|
||
func requestLogger(lg *slog.Logger) gin.HandlerFunc
|
||
```
|
||
|
||
`api.NewRouter` 签名改为：
|
||
|
||
```go
|
||
func NewRouter(
|
||
workspaces *service.WorkspaceService,
|
||
files *service.FileService,
|
||
processes *service.ProcessService,
|
||
lg *slog.Logger,
|
||
) *gin.Engine
|
||
```
|
||
|
||
如果 `lg == nil`，使用 `slog.Default()`。
|
||
|
||
middleware 字段：
|
||
|
||
- `method`
|
||
- `path`
|
||
- `status`
|
||
- `latency_ms`
|
||
- `client_ip`
|
||
- `error`
|
||
|
||
level 规则：
|
||
|
||
- 2xx/3xx：`Info`
|
||
- 4xx：`Warn`
|
||
- 5xx：`Error`
|
||
|
||
`/healthz` 不记录，避免健康检查刷屏。
|
||
|
||
request logging 不记录：
|
||
|
||
- request body
|
||
- response body
|
||
- query string 中的敏感内容
|
||
|
||
`path` 使用路由模板或 URL path，不包含 query string。
|
||
|
||
## 业务日志边界
|
||
|
||
### WorkspaceService
|
||
|
||
增加 logger 字段：
|
||
|
||
```go
|
||
type WorkspaceService struct {
|
||
workspaces workspace.Manager
|
||
processes process.Manager
|
||
logger *slog.Logger
|
||
}
|
||
```
|
||
|
||
构造函数接受 logger：
|
||
|
||
```go
|
||
func NewWorkspaceService(workspaces workspace.Manager, processes process.Manager, lg *slog.Logger) *WorkspaceService
|
||
```
|
||
|
||
如果 `lg == nil`，使用 `slog.Default()`。
|
||
|
||
记录：
|
||
|
||
- create 成功：`workspace created`，字段 `workspace_id`
|
||
- delete 成功：`workspace deleted`，字段 `workspace_id`
|
||
- delete 前停止进程失败：`failed to stop workspace process before delete`，字段 `workspace_id`、`error`
|
||
|
||
不记录 workspace root。
|
||
|
||
### ProcessService
|
||
|
||
增加 logger 字段：
|
||
|
||
```go
|
||
type ProcessService struct {
|
||
workspaces workspace.Manager
|
||
processes process.Manager
|
||
logger *slog.Logger
|
||
}
|
||
```
|
||
|
||
构造函数接受 logger：
|
||
|
||
```go
|
||
func NewProcessService(workspaces workspace.Manager, processes process.Manager, lg *slog.Logger) *ProcessService
|
||
```
|
||
|
||
如果 `lg == nil`，使用 `slog.Default()`。
|
||
|
||
记录：
|
||
|
||
- start 成功：`process started`，字段 `workspace_id`、`pid`
|
||
- start 失败：`process start failed`，字段 `workspace_id`、`error`
|
||
- stop 成功：`process stopped`，字段 `workspace_id`
|
||
- stop 失败：`process stop failed`，字段 `workspace_id`、`error`
|
||
- restart 成功：`process restarted`，字段 `workspace_id`、`pid`
|
||
- restart 失败：`process restart failed`，字段 `workspace_id`、`error`
|
||
|
||
不记录 command、env、workspace root。
|
||
|
||
### FileService
|
||
|
||
第一版不增加业务日志。文件操作高频且容易泄露用户路径/内容。request logging 已足够覆盖 HTTP 访问。
|
||
|
||
## API 兼容性
|
||
|
||
现有 API 路径、method、响应 JSON 不变。
|
||
|
||
唯一函数签名变化是内部构造函数：
|
||
|
||
- `api.NewRouter(..., lg *slog.Logger)`
|
||
- `service.NewWorkspaceService(..., lg *slog.Logger)`
|
||
- `service.NewProcessService(..., lg *slog.Logger)`
|
||
|
||
测试可传 `nil`，由实现回退到 `slog.Default()`。
|
||
|
||
## 测试策略
|
||
|
||
### logger tests
|
||
|
||
覆盖：
|
||
|
||
- `logger.New(config.LogConfig{Level: "info", Format: "json"})` 成功。
|
||
- `logger.New(config.LogConfig{Level: "debug", Format: "text"})` 成功。
|
||
- 非法 level 返回 error。
|
||
- 非法 format 返回 error。
|
||
|
||
### config tests
|
||
|
||
覆盖：
|
||
|
||
- 默认 log config 是 `info/json`。
|
||
- YAML 能覆盖 log config。
|
||
- 环境变量能覆盖 log config。
|
||
|
||
### API tests
|
||
|
||
现有 `httptest` 行为不变。
|
||
|
||
额外覆盖：
|
||
|
||
- `api.NewRouter(..., nil)` 不 panic。
|
||
- `/healthz` 正常返回，不受 logging middleware 影响。
|
||
|
||
### 全局验证
|
||
|
||
必须通过：
|
||
|
||
```sh
|
||
gofmt -w cmd internal pkg
|
||
go test ./...
|
||
go run ./cmd/server
|
||
curl http://localhost:8080/healthz
|
||
```
|
||
|
||
## 风险与处理
|
||
|
||
- 风险：日志泄露用户内容。处理：禁止记录 body、文件内容、OpenCode 输出、env、token。
|
||
- 风险：日志噪音过大。处理：不记录 `/healthz`，不记录 FileService 高频业务日志。
|
||
- 风险：logger 注入让构造函数变多。处理：只给 router、workspace service、process service 加 logger；FileService 不加。
|
||
- 风险：测试输出被 JSON 日志污染。处理：测试传 nil 或使用 `slog.New(slog.NewTextHandler(io.Discard, nil))`。
|
||
|
||
## 完成标准
|
||
|
||
完成后满足：
|
||
|
||
- `pkg/logger` 使用 `log/slog`。
|
||
- `cmd/server/main.go` 不再使用 `lg.Printf`。
|
||
- `api.NewRouter` 接受 logger 并安装 request logging middleware。
|
||
- workspace/process 生命周期有结构化日志。
|
||
- log 配置支持 YAML 和环境变量。
|
||
- 全局约束检查中无运行期旁路日志；只允许 logger 初始化失败前的兜底 `log.Fatalf`。
|
||
- server smoke test 通过。
|