# logx

业务通过 `logx` 记录结构化日志，独立于 HTTP、队列和具体业务字段。普通 `context.Context` 继续由业务管理；框架不会约定或自动注入 userId、tenantId。

```go
logx.InfoContext(ctx, "order.created", "orderId", orderID)
logx.ErrorContext(ctx, "order.failed", "error", err)
// 可选：附上本次记录位置的当前 goroutine 堆栈。
logx.ErrorStackContext(ctx, "unexpected.failure", "error", err)
// 固定字段可使用子日志对象，无需重复传入。
logger := logx.With("component", "invoice")
logger.InfoContext(ctx, "invoice.saved", "invoiceId", invoiceID)
```

`Debug/Info/Warn/Error` 有包级和实例方法，也有带 Context 的方法。`requestId` 自动跟随 HTTP Context；接入 telemetry 后可带 `traceId`。不要在 Service 中改用 `context.Background()`，否则会丢失取消信号和关联字段。

## 实例时区

```yaml
server:
  log:
    timeZone: Asia/Shanghai
```

手写项目使用 `logx.New(logx.Config{TimeZone: "Asia/Shanghai"})`。配置名称采用 IANA 名称或 UTC；空字符串保持已有时间戳行为。无效名称在打开文件之前报 `timeZone` 的安全错误；统一加载后路径为 `server.log.timeZone`。

时区在创建 Logger 时解析，记录输出不重复加载；JSON/text、With/WithGroup 子日志和 Standard 适配器均继承该实例时区。不同 Logger 可同时使用不同地区，不修改全局 time.Local。仅转换记录时间戳，业务 `time.Time` 属性保留原时区；夏令时由时区数据处理。时区变更需要重建 Logger，现有热加载仍只支持级别。

使用 Go 标准库查找时区。极简镜像需提供时区数据，或执行 `go build -tags timetzdata .` 将标准库时区数据内置（增加约 450 KB）；也可由手写 main 导入 time/tzdata。logx 自身不强制内置数据，不引入第三方依赖。脱敏、日志级别和文件所有权语义保持不变。可运行例子：[developerTools](../examples/developerTools/README.md)。

## 文件轮转

```go
closeLog, err := logx.Setup(logx.Config{
    Service: "billing-api", Environment: "production",
    Level: "info", Format: "json", File: "./var/log/billing-api.log",
    Rotation: logx.RotationConfig{
        Enabled: true, MaxSizeMB: 100, MaxBackups: 10,
        MaxAgeDays: 7, Compress: true,
    },
    RedactKeys: []string{"bankAccount", "identityNumber"},
})
if err != nil { return err }
defer closeLog()
```

`omni.WithLogConfig(...)` 只保存日志配置，`omni.New()` 不会因此创建或关闭 Logger。手写入口需要像上例一样调用 `logx.Setup` 并负责关闭，或使用 `logx.New`、`logx.SetDefault` 和 `app.OnShutdown(logger.Close)` 显式装配。生成的 API 项目已在入口完成这些步骤。子日志共用输出、级别和关闭状态；独立 `logx.New` 返回的实例由创建者负责关闭。

轮转显式开启；三个数值为 0 时分别取 100 MiB、10 份、7 天。超过大小后轮转，旧文件按份数/年龄清理，可 gzip 压缩；保留天数不表示每天定时切割。压缩和历史清理由底层异步执行，不承诺 Close 等待压缩完成。轮转使用 [lumberjack v2](https://github.com/natefinch/lumberjack/tree/v2.2.1)，**一个日志文件只能由一个进程拥有**。容器通常直接用 stdout/stderr，让运行平台管理日志文件。

`rotation.enabled` 与自定义 Writer 不能同时使用；只设轮转但未提供 File 会报错。开启轮转时会创建父目录，并在初始化阶段检查文件可打开。自定义 Writer 的并发和生命周期由接入方负责。普通文件输出仍然是追加写入；未开启轮转不自动清理。

## 结构化脱敏

默认匹配 password、passwd、secret、clientSecret、token、accessToken、refreshToken、authorization、cookie、setCookie、apiKey、privateKey、signedUrl。匹配忽略大小写、下划线和连字符；`RedactKeys` 追加业务自行定义的键，不替换默认列表。

覆盖普通属性、With 属性、slog Group/LogValuer、嵌套字符串键 map、切片和导出 struct 字段。敏感值变为 `[REDACTED]`，不修改调用者的数据；循环/过深结构截断。嵌套字节数组隐藏为 `[BINARY]`，非字符串键 map 隐藏为 `[UNSUPPORTED MAP]`，不调用对象自定义 JSON 序列化方法。

**脱敏按字段名处理，不解析自由文本。** 把密码拼进 msg/error/URL 字符串，或使用不在列表中的字段名，仍可能泄露。签名链接、完整请求体和认证头不应写入日志。业务隐私字段自行放进 `RedactKeys`；日志中不会自动添加身份/租户约定。

## HTTP 异常与慢请求

```go
application := omni.New(
    omni.WithLogger(true),
    omni.WithSlowRequestThreshold(500*time.Millisecond),
)
```

`WithSlowRequestThreshold` 同时开启访问日志，0 禁用慢请求识别。也可以在配置文件的 server 下配 `enableLogger: true`、`slowRequestThreshold: "500ms"`。需要环境变量控制时，显式写 `slowRequestThreshold: "${SLOW_REQUEST_THRESHOLD:-500ms}"`；没有文件引用时不会读取同名环境变量。

每个请求记录一条 `http.request`：方法、路径、匹配路由、实际状态码、耗时、客户端 IP 和关联字段。正常请求 INFO，超过阈值 WARN（`slow: true`），5xx ERROR；返回的 error 会记录到结构化字段。计时覆盖 Handler 调用，不包含框架之外的代理排队，也不自动计入 Handler 返回后继续写入的自管流。

Recovery 自动记录单独的 ERROR `http.panic` 和当前堆栈，再走原有统一错误响应；如果响应已提交，不改写已发送状态。客户端不会收到日志堆栈。普通业务 error 默认不抓堆栈，需要时显式使用 `ErrorStackContext`，它记录调用位置，不回溯 error 最初创建位置。

运行时可通过 `logger.SetLevel("debug")` 调整级别；文件轮转和脱敏配置属于静态设置，变更后重建实例/重启。当前不包含日志采样、异步缓冲、日志平台导出或慢 SQL 记录。