必须用db.WithContext(ctx)显式传入上下文，再于SQLHooks的BeforeQuery中提取trace_id并拼入SQL注释，同时分页的COUNT与主查需共用同一ctx以维持Span父子关系。
如何在 GORM 查询中注入 TraceID 并透传到 SQL 日志
必须让每条 SQL 执行都携带当前请求的 trace_id，否则链路就断了。GORM 本身不感知上下文，得靠 WithContext() 显式传入，并在钩子函数里提取、注入。
常见错误现象：db.Find(&u) 查不到 trace_id；日志里 SQL 行没有 trace 字段；Jaeger 中 DB Span 显示为孤立节点。
实操建议：
- 所有数据库操作前必须用
db.WithContext(ctx)，不能直接用全局DB实例 - 使用
SQLHooks时，在BeforeQuery钩子里调用ctx.Value("trace_id")获取 ID（或从opentracing.SpanFromContext(ctx)提取） - 把
trace_id作为注释拼进 SQL，例如/* trace_id=abc123 */ SELECT * FROM users WHERE id = ?，MySQL/PostgreSQL 都能识别并计入慢日志 - 别依赖 GORM 的
Session自动继承 context —— 它只对事务内操作生效，单条 Query 不保证
GORM 分页查询为何总和链路追踪“打架”
因为分页常伴随两次独立查询：一次 COUNT(*)，一次 LIMIT/OFFSET，而多数链路埋点方案默认按 *gorm.DB 实例绑定 Span，导致两个查询被当成两个无关联 Span 上报。
常见错误现象：Jaeger 里看到两个平行 DB Span，没父子关系；COUNT 耗时被单独统计，无法归因到分页请求；Trace 中缺失总数查询环节。
实操建议：
- 用同一个
ctx分别调用query.Count()和query.Limit().Offset().Find()，确保 Span 上下文一致 - 避免复用未带 context 的全局
DB，比如DB.Where(...).Count()会丢失 trace 上下文 - 如果用了
pagination.Paginate()这类封装，确认它内部是否调用WithContext()——joshbetz/paginationv1.4+ 已支持，但需手动传 ctx - 不要在
Count后再WithContext()—— Span 生命周期已结束，新 context 会启新 trace
游标分页 + 链路追踪的组合难点在哪
游标分页（如 WHERE id > ? ORDER BY id LIMIT 20）本身不依赖 OFFSET，性能好、数据稳，但和链路追踪配合时容易漏掉关键上下文。
常见错误现象：翻页请求的 trace_id 正确，但下一页的游标值（如上一页最后的 id）没被记录进 Span 的 tag；慢查询告警里查不到游标字段；审计日志无法还原翻页路径。
实操建议：
- 在
BeforeQuery钩子里解析 SQL，匹配WHERE.*?id > ?模式，把绑定参数中的游标值提取出来，写入 Span 的db.statement.cursortag - 游标字段必须有索引，否则即使 trace 完整，SQL 执行也会变慢 —— 追踪不能掩盖性能债
- 别把游标值硬编码进 SQL 字符串（如
WHERE id > 100），这会让 SQL 注释里的 trace_id 失效，且无法被 Prepared Statement 缓存 - 前端传来的游标值（如
cursor=abc123）需先校验格式和长度，非法值应直接拒掉，避免生成无效 Span 污染链路数据
为什么 COUNT 查询总是拖慢整个 trace
COUNT(*) 在大数据量表上可能比主查询还慢，尤其带复杂 JOIN 或 WHERE 条件时。一旦它卡住，整个 trace 的耗时就失真，下游服务等超时，监控误报。
常见错误现象：trace 总耗时 1.2s，其中 COUNT 占 1.1s；告警显示“DB 响应慢”，但实际业务查询很快；用户没点“下一页”，后台却已在跑全量 COUNT。
实操建议：
- 对
COUNT查询单独设 Span 名称，例如db.count.users，和主查询db.query.users区分，便于监控筛选 - 给
COUNT设置更短的 context timeout，比如主查询用 3s，COUNT 用 800ms，超时直接返回估算值或缓存值 - 避免在高频接口里强制同步查总数 —— 可改用 Redis 缓存总数（配合写操作更新），或前端接受“最多显示 XX 条”的模糊提示
- 别在事务里执行
COUNT—— 它会持有读锁，阻塞写操作，放大链路延迟
链路追踪不是加个中间件就完事，每个 SQL 的上下文、每个分页步骤的 Span 关系、每个 COUNT 的超时策略，都得在代码里显式控制。最容易被忽略的是：游标值没打标、COUNT 没降级、context 没贯穿两次查询 —— 这些地方一漏，整条 trace 就成了断线风筝。
