docs(applog): 客户端运行日志批量上报→落文件→SLS 采集设计(spec) #187

2026-07-27T17:50:51+08:00

guke commented

2026-07-27 17:50:51 +08:00

No description provided.

guke added 13 commits 2026-07-27 17:50:52 +08:00

docs(applog): 客户端运行日志批量上报→落文件→SLS 采集设计(spec) ab12b2eab1

新增 POST /api/v1/applog/batch:批量接收客户端运行日志,逐条写独立滚动
文件 logs/app-client.log(propagate=False,不污染 app-server.log),供 Logtail
JSON 模式采进独立 logstore。每条按「白名单键(client_ts/level/trace_id/tag/
msg)+ data 兜底」封装以钉死 SLS 索引列;trace_id 提到顶层以跨层检索。
鉴权同 analytics、加条数/体积/msg 上限与 IP 限流、fire-and-forget 不 500。
滚动 20MB×10,单 worker 约束(RotatingFileHandler 多进程不安全)已标注。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(applog): 实现计划 + spec 对齐(白名单拆分落写入层/体积走依赖) fc21ab95cc

- 新增 plans/2026-07-19-client-applog-ingest.md:TDD 任务(writer→端点→env 文档),含完整代码。
- spec 对齐两处实现决策:①白名单+data 兜底在 client_log 写入层对 list[dict] 拆分
  (而非 Pydantic 校验器),使单条异常不整批 422;②body 上限走依赖查 Content-Length
  (body 校验前拦截),缺头由 nginx 兜底。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(applog): 客户端日志专用落盘 writer(白名单+data 兜底, propagate=False) bf4b08d567

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(applog): 落盘 writer 评审整改(drop 可观测 / 显式 data 优先 / logger 命名归一 / 补测) ab46dec102

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(applog): 修正 writer docstring 里过期的 logger 名(client→shagua.client_log) 267d65a473

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

feat(applog): POST /api/v1/applog/batch 批量上报端点(限流+体积上限+fire-and-forget) 2de1f537c0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

refactor(api): 提取 get_client_ip 到 deps(applog/analytics 复用) + applog 上限注释 74da3525a9

评审整改:消除 _client_ip 第三份副本(改到 deps.get_client_ip,路由层共用);
标注 APPLOG_MAX_BATCH 为导入期常量;body-limit 测试补 nginx 兜底说明。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(applog): .env.example 补充客户端日志上报可调 env(CLIENT_LOG_*/APPLOG_*) 5881dd4f05

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(applog): 给 SLS 索引字段 trace_id/tag/level 加长度上限(终审 M1 加固) a604f4d614

只有 msg 有字节截断,trace_id/tag/level(spec §8 的索引字段)此前不限长,
客户端可塞超大值撑爆 SLS 索引/抬成本。统一转 str 并截断(256/128/16),
data 内的值仍不限(留待后续脱敏 knob)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(api): 补 POST /api/v1/applog/batch 接口文档 + 索引登记(E3) 266b32dee4

新增 docs/api/other/applog-batch.md(仿 analytics-events 格式:入参/出参/错误码/说明),
README 索引「埋点&订单上报/客户端日志」组加 E3 行,并把该组鉴权注解补上 applog/batch 免登录。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fix(applog): 请求体上限默认 1MB→2MB(端点默认值 + .env.example + 接口文档同步) 6c0fc303e1

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(applog): spec/plan 请求体上限同步为 2MB(与端点默认一致) e2a485dfe6

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge branch 'main' of https://gitea.shaguabijia.com/WonderableAI/shaguabijia-app-server into feat/client-applog-ingest 52c530f0a1

# Conflicts:
#	.env.example
#	docs/api/README.md

guke merged commit f05dd1cf74 into main

2026-07-27 18:00:25 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: WonderableAI/shaguabijia-app-server#187

docs(applog): 客户端运行日志批量上报→落文件→SLS 采集 设计(spec) #187

docs(applog): 客户端运行日志批量上报→落文件→SLS 采集设计(spec) #187