Files

T

hoteas 831a7f017a feat(log): Seq 会话追踪、控制台降噪与推送质量增强

请求日志自动带 sid/request_id，支持 LogBind；挂 Seq 后控制台仅 Warn+，Seq 仍全量；并修毫秒时间戳、@m、失败重试与停机 flush。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-23 05:26:44 +08:00

4.8 KiB

Raw Blame History

Seq 日志集成

HoTime 框架内置 Seq 日志推送支持。通过在 config.json 填写 seqUrl 即可激活。
目标：用 Seq 集中检索替代翻 logs/*.txt；本地 logFile 可并行保留。

配置项

在 config.json 中添加：

"seqUrl":    "http://127.0.0.1:5341",
"seqApiKey": ""

字段	默认值	说明
`seqUrl`	空（不激活）	Seq 服务地址，空值时功能静默不生效
`seqApiKey`	空	API Key，免费单用户版留空

instance 字段由框架自动拼接为 ip:port（如 192.168.1.10:8085），无需手动填写。

激活后每个 HTTP 请求会自动：

生成 request_id（12 位 hex），回写响应头 X-Request-Id
将 sessionId 前 12 位作为 sid 写入请求级日志（脱敏，避免把登录凭据写进 Seq）
业务日志、SQL 日志、访问日志均携带 sid / request_id
控制台自动降噪为 Warn+（Info/Debug/SQL/访问日志仍进 Seq 与文件，零额外配置）

会话追踪与 LogBind

框架在 handler 入口派生请求级 Logger，并浅拷贝 Db 将其 Log 指向同一 Logger，因此 SQL 日志自动带会话字段。字段会出现在同条日志的控制台/文件/Seq 出口上。

业务在 SetConnectListener 鉴权通过后绑定（xbc main.go）：

// app 鉴权通过后
context.LogBind("user_id", context.Session("user_id").ToCeilInt64())

// admin 鉴权通过后（或 session 已有 admin_id）
context.LogBind("admin_id", context.Session("admin_id").ToCeilInt64())

LogBind 后，本请求后续业务日志与 SQL 日志都会带上该字段。

不带会话字段的边界：

fmt.Println / stdout 捕获、panic、MySQL driver、定时任务等无请求上下文的日志
直接写 that.Application.Log 的旧代码（应改用 that.Logger 或 that.LogBind 后的请求级 Logger）

控制台降噪（配了 seqUrl）

出口	行为
控制台	仅 Warn / Error（含 `Display` 非 0 的 Warn）
Seq	按 `logLevel` 全量（Info/Debug/SQL/访问日志等）
本地文件	与原先一致，不受控制台过滤影响

未配置 seqUrl 时控制台仍按 logLevel 全打。

客户端 IP 与地域

零配置，优先级：

X-Real-IP（EdgeOne / 反代透传的真实 IP）
X-Forwarded-For 第一段
RemoteAddr

请求头有 EO-Client-IPCountry 时，访问日志追加 ip_country（两位国家码）；没有则不记。

架构原理

业务代码
  │  that.Logger.Info().Msg("...")  ← 请求级（含 sid/request_id）
  │  Db.Query → SQL 日志            ← 同一请求级 Logger
  │  fmt.Println("...")             ← 捕获后无 sid
  ↓
multiWriter（hotimev1.5/log/logger.go）
  ├─ Console（挂 Seq 后 Warn+）→ 终端
  ├─ FileWriter                 → 本地文件（按需，全量）
  └─ SeqWriter                  → Seq（全量）
        │  Write() 只做 channel <- bytes，O(1) 非阻塞
        ↓
     channel（容量 10000）
        ↓  后台 goroutine
     批量打包（100 条 或 500ms）
        ↓  HTTP POST（失败重试 1 次）
     Seq 服务（CLEF 格式）

优雅停机时调用 CloseSeq() 冲刷残留批次，避免停机前后日志丢失。

字段映射（zerolog → CLEF）

zerolog 字段	Seq CLEF 字段	说明
`time`	`@t`	毫秒精度 ISO 8601
`level`	`@l`	Debug/Information/Warning/Error/Fatal
`message` / `msg`	`@m`	消息正文（不用 `@mt`，避免 `{xxx}` 被当模板）
`caller`	`caller`	调用位置
`sid`	`sid`	sessionId 前 12 位
`request_id`	`request_id`	单次请求 id
`ip_country`	`ip_country`	有 `EO-Client-IPCountry` 时
其余自定义字段	原字段名	`LogBind` 追加的字段原样保留
—	`instance`	`ip:port`
—	`source`	stdout / stderr / panic 等

搜索语法速查

目标	查询语句
按会话追踪	`sid = 'abc123def456'`
按单次请求	`request_id = 'fedcba987654'`
关键词	直接输入，如 `支付失败`
日志级别	`@l = 'Error'`
特定实例	`instance = '192.168.1.10:8085'`
地域	`ip_country = 'CN'`
stdout	`source = 'stdout'`
panic	`source = 'panic'`
组合	`@l = 'Error' and sid = 'abc123def456'`

Seq 安装

Windows：https://datalust.co/download/seq
Docker：docker run -d --restart always --name seq -p 5341:80 -e ACCEPT_EULA=Y datalust/seq
访问 http://localhost:5341

4.8 KiB Raw Blame History Unescape Escape