weichen
2e2620009f
Why: Make independent version consumption work from ordinary clones while retaining historical commits and existing branch workspaces. Evidence: SELF Dev task receipts record 24 CI boundary cases, all workflow syntax checks, readonly private-source prefetch in clean exports, provider tests and package installation without acquisition scripts. Platform CI remains pending. Impact: Remove only replaced index links, preserve old physical checkouts, and update dependency guidance. Library consumers retain their immutable versions until an explicit dependency update. Refs: Agent-System-Dev feature/dependency-workspace; approved versioned-dependency r1, U3-U7 and R15.
3.8 KiB
Logging-System
跨系统共用的结构化日志库，以及可独立部署的采集服务。目标是把一次请求的运行日志和错误码对齐到同一个 trace_id 上，方便事后追溯。
本仓库是该模块的源码位置。Go 模块路径为 git-ssh.u1680832.nyat.app/weichen/Logging-System.git。只依赖标准库，不依赖错误码模块：只要错误实现了 ErrorCode() 和 ErrorFields()，错误日志会自动带上码和字段。
分层
| 包 | 职责 | 依赖边界 |
|---|---|---|
| logsys | 级别、条目、Logger、上下文追踪、全局默认日志器 | 只依赖标准库 |
| sink | console / 滚动文件 / 异步队列 / HTTP 批量 / 多路分发 | 只依赖 logsys |
| redact | 写前脱敏（JWT、sk-key、Bearer、api_key、password，可追加正则） | 只依赖标准库 |
| config | 默认值 ← JSON ← LOGSYS_* 环境变量 |
组装 logsys 与 sink |
| slogadapter | 与 log/slog 双向转发 |
只依赖 logsys |
| server | 采集服务，默认 :8092 |
组合根之一 |
| cli | logctl |
组合根之一 |
| conformance | 并发不丢、异步排空、脱敏、多路一致 | 只用公开 API |
同步与异步
每个出口自己保证并发安全。
| 模式 | 行为 |
|---|---|
| 同步 | 调用方 goroutine 在互斥锁内写完（console、file，或 async: false 的 HTTP） |
| 异步 | 有界队列加单写者。队列满时丢弃最新一条并计数，不阻塞业务 goroutine。Sync / Close 排空队列，关闭有超时 |
HTTP 出口默认异步攒批（条数或时间间隔）。文件可按大小滚动并保留 N 份历史。
模块级别可以比全局更细，例如全局 info、engine 为 debug、server 为 warn。出口还可以再设自己的最低级别。
配置
完整示例见 docs/example.json。
环境变量覆盖文件：LOGSYS_CONFIG、LOGSYS_LEVEL、LOGSYS_SERVICE、LOGSYS_REDACT（on/off）。
cfg, err := config.Load("log.json")
log, err := config.Build(cfg)
defer log.Close()
log.Module("engine").WithContext(ctx).Error("provider down", err, "step", id)
log.Error 的 err 若带有错误码，条目里会出现 code 和该错误的字段。追踪标识用 logsys.WithTrace 放进 context，或由调用方写入 X-Trace-Id。
采集 API
| 方法/路径 | 说明 |
|---|---|
GET /v1/health |
健康检查 |
POST /v1/logs |
正文 {"entries":[...]}。配置了 token 时要求 Authorization: Bearer 或 X-Log-Token |
GET /v1/logs |
trace_id、level（精确）、service、q、cursor、limit |
GET /v1/logs/tail |
SSE。cursor 之后先回放再实时推送；慢消费者丢帧 |
写入时再脱敏一次，避免客户端绕过进程内红线。
CLI
go build -o bin/logctl .
./bin/logctl serve --addr :8092 --data logs/collector.jsonl --token dev
./bin/logctl query --addr http://127.0.0.1:8092 --trace trace-abc-1 --token dev
./bin/logctl tail --addr http://127.0.0.1:8092 --token dev
开发
go vet ./...
go test -count=1 ./...
依赖本仓库
消费方使用模块 git-ssh.u1680832.nyat.app/weichen/Logging-System.git，由 Go 生成可获取的提交版本：
go get git-ssh.u1680832.nyat.app/weichen/Logging-System.git@<已审核提交>
GOWORK=off go test -mod=readonly ./...
go.mod 决定实际版本，go.sum 校验内容。私有获取通过 Dev 登记的进程级传输配置，不修改全局 Git 配置。源码联调用本地工作区覆盖，正式消费没有源码目录 replace；旧提交继续按其原固定组合构建。
远程：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Logging-System.git
与错误码系统的追溯闭环见 docs/integration.md。可运行示例：cd examples/trace && GOWORK=off go test -mod=readonly ./...（独立模块，远端版本消费）。