tikv: add the user's guide of stale read and safe ts (#15365) (#15411)

pingcap · Nov 9, 2023 · 35a75f2 · 35a75f2
1 parent e62ad3e
commit 35a75f2
Show file tree

Hide file tree

Showing 14 changed files with 307 additions and 5 deletions.
diff --git a/TOC.md b/TOC.md
@@ -222,6 +222,7 @@
     - [使用 Top SQL 定位系统资源消耗过多的查询](/dashboard/top-sql.md)
     - [通过日志定位消耗系统资源多的查询](/identify-expensive-queries.md)
     - [保存和恢复集群现场信息](/sql-plan-replayer.md)
+    - [理解 TiKV 中的 Stale Read 和 safe-ts](/troubleshoot-stale-read.md)
   - [获取支持](/support.md)
 - 性能调优
   - 优化手册

diff --git a/grafana-tidb-dashboard.md b/grafana-tidb-dashboard.md
@@ -108,11 +108,22 @@ summary: 了解 Grafana Dashboard 中展示的关键指标。
 
 ### KV Request
 
+下面的监控指标与发送给 TiKV 的请求相关。重试请求会被多次计数。
+
 - KV Request OPS：KV Request 根据 TiKV 显示执行次数
 - KV Request Duration 99 by store：根据 TiKV 显示 KV Request 执行时间
 - KV Request Duration 99 by type：根据类型显示 KV Request 的执行时间
-- Stale Read OPS：每秒执行的 Stale Read 的数量，根据结果分为 hit 和 miss 进行统计
-- Stale Read Traffic：Stale Read 消耗的流量，根据结果分为 hit 和 miss 进行统计
+- Stale Read Hit/Miss Ops
+    - **hit**：每秒成功执行 Stale Read 的请求数量
+    - **miss**：每秒尝试执行 Stale Read 但失败的请求数量
+- Stale Read Req Ops
+    - **cross-zone**：每秒尝试在远程可用区执行 Stale Read 的请求数量
+    - **local**：每秒尝试在本地可用区执行 Stale Read 的请求数量
+- Stale Read Req Traffic
+    - **cross-zone-in**：尝试在远程可用区执行 Stale Read 的请求的响应的传入流量
+    - **cross-zone-out**：尝试在远程可用区执行 Stale Read 的请求的响应的传出流量
+    - **local-in**：尝试在本地可用区执行 Stale Read 的请求的响应的传入流量
+    - **local-out**：尝试在本地可用区执行 Stale Read 的请求的响应的传出流量
 
 ### PD Client
 

diff --git a/grafana-tikv-dashboard.md b/grafana-tikv-dashboard.md
@@ -403,6 +403,20 @@ title: TiKV 监控指标详解
 - Total pessimistic locks memory size：内存悲观锁占用内存的总大小
 - In-memory pessimistic locking result：将悲观锁仅保存到内存的结果，其中 full 表示因为超过内存限制而无法将悲观锁保存至内存的次数
 
+### Resolved-TS
+
+- Resolved-TS worker CPU：resolved-ts worker 线程的 CPU 使用率
+- Advance-TS worker CPU：advance-ts worker 线程的 CPU 使用率
+- Scan lock worker CPU：scan lock worker 线程的 CPU 使用率
+- Max gap of resolved-ts：在当前 TiKV 中，所有活跃 Region 的 resolved-ts 与当前时间的最大差值
+- Max gap of safe-ts：在当前 TiKV 中，所有活跃 Region 的 safe-ts 与当前时间的最大差值
+- Min Resolved TS Region：resolved-ts 最小的 Region 的 ID
+- Min Safe TS Region：safe-ts 最小的 Region 的 ID
+- Check Leader Duration：处理 leader 请求所花费的时间的直方图，从发送请求到接收到 leader 的响应
+- Max gap of resolved-ts in Region leaders：在当前 TiKV 中，所有活跃 Region 的 resolved-ts 与当前时间的最大差值，只包含 Region leader
+- Min Leader Resolved TS Region：resolved-ts 最小的 Region 的 ID，只包含 Region leader
+- Lock heap size：resolved-ts 模块中用于跟踪锁的堆的大小
+
 ### Memory
 
 - Allocator Stats：内存分配器的统计信息

diff --git a/media/stale-read/example-ops.png b/media/stale-read/example-ops.png
diff --git a/media/stale-read/example-ts-gap.png b/media/stale-read/example-ts-gap.png
diff --git a/media/stale-read/metrics-hit-miss.png b/media/stale-read/metrics-hit-miss.png
diff --git a/media/stale-read/metrics-ops.png b/media/stale-read/metrics-ops.png
diff --git a/media/stale-read/traffic.png b/media/stale-read/traffic.png
diff --git a/releases/release-6.5.4.md b/releases/release-6.5.4.md
@@ -27,7 +27,7 @@ TiDB 版本：6.5.4
 + TiKV
 
     - 使用 gzip 压缩 `check_leader` 请求以减少流量 [#14553](https://github.com/tikv/tikv/issues/14553) @[you06](https://github.com/you06)
-    - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get_region_read_progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
+    - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get-region-read-progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
     - 在 TiKV 中暴露部分 RocksDB 配置，允许用户禁用 TTL 和定期数据整理等特性 [#14873](https://github.com/tikv/tikv/issues/14873) @[LykxSassinator](https://github.com/LykxSassinator)
     - 避免写 Titan manifest 文件时持有锁导致影响其他线程 [#15351](https://github.com/tikv/tikv/issues/15351) @[Connor1996](https://github.com/Connor1996)
 

diff --git a/releases/release-7.1.2.md b/releases/release-7.1.2.md
@@ -30,7 +30,7 @@ TiDB 版本：7.1.2
 
     - 优化数据整理检查机制，当触发 Region Split 时，如果没有可以分裂的 key，触发一次数据整理，以消除过多的 MVCC 版本 [#15282](https://github.com/tikv/tikv/issues/15282) @[SpadeA-Tang](https://github.com/SpadeA-Tang)
     - 消除 Router 对象中的 LRUCache，降低内存占用，防止 OOM [#15430](https://github.com/tikv/tikv/issues/15430) @[Connor1996](https://github.com/Connor1996)
-    - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get_region_read_progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
+    - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get-region-read-progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
     - 在 TiKV 中暴露部分 RocksDB 配置，允许用户禁用 TTL 和定期数据整理等特性 [#14873](https://github.com/tikv/tikv/issues/14873) @[LykxSassinator](https://github.com/LykxSassinator)
     - 新增 PD Client 连接重试过程中的 backoff 机制。异常错误重试期间，逐步增加重试时间间隔，减小 PD 压力 [#15428](https://github.com/tikv/tikv/issues/15428) @[nolouch](https://github.com/nolouch)
     - 避免写 Titan manifest 文件时持有锁导致影响其他线程 [#15351](https://github.com/tikv/tikv/issues/15351) @[Connor1996](https://github.com/Connor1996)

diff --git a/releases/release-7.3.0.md b/releases/release-7.3.0.md
@@ -230,7 +230,7 @@ v7.3.0 引入了以下主要功能。[功能详情](#功能详情)中列出的
 
 + TiKV
 
-    - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get_region_read_progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
+    - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get-region-read-progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
 
 + PD
 

diff --git a/stale-read.md b/stale-read.md
@@ -40,6 +40,8 @@ advance-ts-interval = "20s" # 默认为 20 秒，可适当调小该值以加快
 >
 > 调小该参数会增加 TiKV CPU 使用率和各节点之间的流量。
 
+关于 Resolved TS 的内部原理和诊断方法，请参阅[理解 TiKV 中的 Stale Read 和 safe-ts](/troubleshoot-stale-read.md)。
+
 ## 限制
 
 当对表的 Stale Read 查询下推到 TiFlash 时，如果该表在 Stale Read 所指定的读取时间戳之后执行过 DDL 操作，此查询将会报错。原因是 TiFlash 只支持从最新的表结构读取数据。

diff --git a/tikv-control.md b/tikv-control.md
@@ -666,3 +666,40 @@ corruption analysis has completed
 + 在 `sst meta` 输出部分，`14` 表示 SST 文件号，`552997` 表示文件大小，紧随其后的是最小和最大的序列号 (seq) 等其它元信息。
 + `overlap region` 部分为损坏 SST 文件所在 Region 的信息。该信息是从 PD 组件获取的。
 + `suggested operations` 部分为你清理损坏的 SST 文件提供建议操作。你可以参考这些建议的命令，清理文件，并重新启动该 TiKV 实例。
+
+### 获取一个 Region 的 `RegionReadProgress` 状态
+
+从 v6.5.4 和 v7.3.0 开始，TiKV 引入 `get-region-read-progress` 子命令，用于获取 resolver 和 `RegionReadProgress` 的最新状态。你需要指定一个 Region ID 和一个 TiKV，这可以从 Grafana（`Min Resolved TS Region` 和 `Min Safe TS Region`）或 `DataIsNotReady` 日志中获得。
+
+- `--log`（可选）：如果指定，TiKV 会在 `INFO` 日志级别下记录该 TiKV 中 Region 的 resolver 中最小的锁 `start_ts`。该选项有助于提前识别可能阻塞 resolved-ts 的锁。
+
+- `--min-start-ts`（可选）：如果指定，TiKV 会在日志中过滤掉 `start_ts` 小于该值的锁。你可以使用该选项指定一个感兴趣的事务，以便在日志中记录。默认值为 `0`，表示不过滤。
+
+下面是一个使用示例：
+
+```
+./tikv-ctl --host 127.0.0.1:20160 get-region-read-progress -r 14 --log --min-start-ts 0
+```
+
+输出结果如下：
+
+```
+Region read progress:
+    exist: true,
+    safe_ts: 0,
+    applied_index: 92,
+    pending front item (oldest) ts: 0,
+    pending front item (oldest) applied index: 0,
+    pending back item (latest) ts: 0,
+    pending back item (latest) applied index: 0,
+    paused: false,
+Resolver:
+    exist: true,
+    resolved_ts: 0,
+    tracked index: 92,
+    number of locks: 0,
+    number of transactions: 0,
+    stopped: false,
+```
+
+该子命令有助于诊断与 Stale Read 和 safe-ts 相关的问题。详情请参阅[理解 TiKV 中的 Stale Read 和 safe-ts](/troubleshoot-stale-read.md)。
-Original file line number
+Diff line change
@@ Expand Up @@
     + TiKV
-        - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get_region_read_progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
+        - 添加 `Max gap of safe-ts` 和 `Min safe ts region` 监控项以及 `tikv-ctl get-region-read-progress` 命令，用于更好地观测和诊断 resolved-ts 和 safe-ts 的状态 [#15082](https://github.com/tikv/tikv/issues/15082) @[ekexium](https://github.com/ekexium)
     + PD
@@ Expand Down @@