分页查询必须单独监控，因其性能拐点（如OFFSET越大越慢、COUNT+LIMIT双倍IO）与普通查询迥异，混入通用SQL指标会稀释95%分位延迟，无法识别毛刺；须新增query_kind="pagination"等独立标签归一化分类，并精准拦截GORM分页执行阶段上报耗时与空结果、计数偏差、慢COUNT等异常指标。
为什么分页查询必须单独监控，不能混在通用 SQL 指标里
分页查询（如 LIMIT/OFFSET 或 cursor-based）在业务中往往承担列表页、后台管理等高流量入口，其性能拐点与普通单行查询完全不同：OFFSET 越大越慢，深度分页易触发全表扫描；而 COUNT(*) + LIMIT 组合又常被误用，导致双倍 IO。如果只用泛化的 sql_type="select" 标签打到同一个 Histogram 里，95% 分位延迟会被普通查询“稀释”，根本看不出分页毛刺。
实操建议：
- 必须新增独立 label 维度，例如
query_kind="pagination"，和sql_type并列使用 - 对常见分页模式做归一化命名，避免高基数：把
SELECT * FROM users LIMIT 20 OFFSET 1000归为"user_list_offset"，把游标分页WHERE id > ? ORDER BY id LIMIT 20归为"user_list_cursor" - 在 GORM callback 中识别分页特征：检查
stmt.Statement.Settings["gorm:limit"]和stmt.Statement.Settings["gorm:offset"]是否非零，或解析stmt.SQL.String()是否含ORDER BY.*?LIMIT模式（注意仅用于归类，不提取原始 SQL）
GORM v2+ 中如何精准拦截分页 SQL 并打标上报
GORM 的 callbacks 机制不是按“SQL 类型”触发，而是按执行阶段（process、before_query、after_query）挂载函数。直接注册 callback.Process().After("gorm:after_query") 会导致事务内多语句重复计时——比如一个事务里查了两次分页，就会报两次耗时，但实际用户只感知一次页面加载。
正确做法是绑定到具体钩子点，并在回调中判断是否为最终结果返回：
- 用
callback.Query().Before("gorm:query").Register("pagination_timer_start", ...)记录开始时间 - 用
callback.Query().After("gorm:query").Register("pagination_timer_end", ...)取结束时间并上报，确保只对Find()、Scopes().Find()等真正返回结果的调用生效 - 上报时调用
paginationDuration.WithLabelValues(sqlType, tableName, queryKind).Observe(elapsed.Seconds())，其中paginationDuration是独立定义的prometheus.NewHistogramVec - 务必在
init()中调用prometheus.MustRegister(paginationDuration)，否则指标不会出现在/metrics
分页异常指标该统计什么，而不是只看 error != nil
分页失败不等于 SQL 执行出错。很多真实问题藏在“成功但低效”的场景里：空结果集却扫了百万行、COUNT 查询超时后 fallback 到估算值、游标越界未报错但返回乱序数据。只捕获 err != nil 会漏掉 90% 的分页健康问题。
推荐补充三类异常指标：
-
pagination_empty_result_total{table_name,query_kind}：非首次分页（offset > 0或游标非初始值）但结果为空，可能意味着数据被删或游标失效 -
pagination_count_mismatch_total{table_name}：显式调用Count()后再Limit().Find()，两者行数差值 > 5%，说明缓存不一致或中间有写入 -
pagination_slow_count_total{table_name}：单独对分页 COUNT 查询耗时 > 1s（需另建paginationCountDurationHistogram），这类查询往往是优化突破口
所有这些 Counter 都要带 query_kind 标签，和耗时 Histogram 对齐维度，才能在 Grafana 里联动下钻分析。
/metrics 里看不到分页指标？先查 registry 是否隔离
最常见原因是 GORM 插件或中间件内部新建了私有 prometheus.Registry，但没传给 promhttp.HandlerFor()。比如你用了某个封装好的 gorm_prometheus 包，它自己调用了 prometheus.NewRegistry() 并注册指标，而你的主服务仍用默认 promhttp.Handler() ——那分页指标就永远不出现。
验证方式：
- curl http://localhost:8080/metrics | grep pagination，无输出则大概率 registry 不一致
- 检查代码中是否出现
prometheus.NewRegistry()，如果有，必须确保promhttp.HandlerFor(registry, promhttp.HandlerOpts{})被用于路由注册 - 更稳妥的做法：所有指标统一注册到
prometheus.DefaultRegisterer，即全部用prometheus.MustRegister(...)，避免多 registry 管理混乱
分页监控真正的难点不在埋点，而在归一化逻辑是否覆盖所有分页写法（特别是自定义 Scopes、Joins 后的嵌套分页），以及异常指标是否能暴露“看似成功实则危险”的行为。这两点不解决，指标再全也只是好看的数据。
