TiDB 集群问题导图

本篇文档总结了使用 TiDB 及其组件时的常见错误。遇到相关错误时，可以通过本文档的问题导图来排查错误原因并进行处理。

1. 服务不可用

1.1 客户端报 Region is Unavailable 错误

• 1.1.1 Region is Unavailable 一般是由于 Region 在一段时间不可用（可能会遇到 TiKV server is busy；或者发送给 TiKV 的请求由于 not leader 或者 epoch not match 等原因被打回；又或者请求 TiKV 超时等），TiDB 内部会进行 backoff 重试。backoff 的时间超过一定阈值（默认 20s）后就会报错给客户端。如果 backoff 在阈值内，客户端对该错误无感知。

• 1.1.2 多台 TiKV 同时内存不足 (OOM)，导致 Region OOM 期间内没有 Leader，见案例 case-991。

• 1.1.3 TiKV 报 TiKV server is busy 错误，超过 backoff 时间，参考 4.3 客户端报 server is busy 错误。TiKV server is busy 属于内部流控机制，后续可能不计入 backoff 时间。

• 1.1.4 多台 TiKV 启动不了，导致 Region 没有 Leader。单台物理主机部署多个 TiKV 实例，一个物理机挂掉，由于 label 配置错误导致 Region 没有 Leader，见案例 case-228。

• 1.1.5 follower apply 落后，成为 Leader 之后把收到的请求以 epoch not match 理由打回，见案例 case-958（TiKV 内部需要优化该机制）。

1.2 PD 异常导致服务不可用

查看本文档 5. PD 问题。

2. 延迟明显升高

2.1 延迟短暂升高

• 2.1.1 TiDB 执行计划不对导致延迟升高，请参考 3.3 执行计划不对。
• 2.1.2 PD 出现选举问题或者 OOM 问题，请参考 5.2 PD 选举问题和 5.3 PD OOM 问题。
• 2.1.3 某些 TiKV 大量掉 Leader，请参考 4.4 某些 TiKV 大量掉 Leader。
• 2.1.4 其他原因，请参考读写延迟增加。

2.2 Latency 持续升高

• 2.2.1 TiKV 单线程瓶颈

  • 单个 TiKV Region 过多，导致单个 gRPC 线程成为瓶颈（查看监控：Grafana -> TiKV-details -> Thread CPU/gRPC CPU Per Thread），v3.x 以上版本可以开启 Hibernate Region 特性解决该问题，见案例 case-612。

  • v3.0 之前版本 Raftstore 单线程或者 apply 单线程到达瓶颈（查看监控：Grafana -> TiKV-details -> Thread CPU/raft store CPU 和 Async apply CPU 超过 80%）。可以选择扩容 TiKV（v2.x 版本）实例，或者升级到多线程模型的 v3.x 版本。

• 2.2.2 CPU load 升高。

• 2.2.3 TiKV 写入慢，请参考 4.5 TiKV 写入慢。

• 2.2.4 TiDB 执行计划不对，请参考 3.3 执行计划不对。

• 2.2.5 其他原因，请参考读写延迟增加。

3. TiDB 问题

3.1 DDL

• 3.1.1 修改 decimal 字段长度时报错 "ERROR 1105 (HY000): unsupported modify decimal column precision"。TiDB 暂时不支持修改 decimal 字段长度。

• 3.1.2 TiDB DDL job 卡住不动/执行很慢（通过 admin show ddl jobs 可以查看 DDL 进度）：

  • 原因 1：与外部组件 (PD/TiKV) 的网络问题。

  • 原因 2：早期版本（v3.0.8 之前）TiDB 内部自身负载很重（高并发下可能产生了很多协程）。

  • 原因 3：早期版本（v2.1.15 & v3.0.0-rc1 之前）PD 实例删除 TiDB key 无效的问题，会导致每次 DDL 变更都需要等 2 个 lease（很慢）。

  • 其他未知原因，请上报 bug。

  • 解决方法：原因 1 需要检查与外部组件的网络问题；原因 2 和 3 已经修复，需要升级到高版本；其他原因，可选择以下兜底方案进行 DDL owner 迁移。

  • DDL owner 迁移方案：

    • 如果与该 TiDB 集群可以网络互通，执行重新进行 owner 选举命令：curl -X POST http://{TiDBIP}:10080/ddl/owner/resign

    • 如果与该 TiDB 集群不可以网络互通，需旁路下线，通过 tidb-ctl 工具，从 PD 集群的 etcd 中直接删除 DDL owner，之后也会重新选举：tidb-ctl etcd delowner [LeaseID] [flags] + ownerKey

• 3.1.3 TiDB 日志中报 information schema is changed 的错误：

  • 报错的详细原因以及解决办法参见触发 Information schema is changed 错误的原因。

  • 背景知识：schema version 的增长数量与每个 DDL 变更操作的 schema state 个数一致，例如 create table 操作会有 1 个版本变更，add column 操作会有 4 个版本变更（详情可以参考 online schema change），所以太多的 column 变更操作会导致 schema version 增长得很快。

• 3.1.4 TiDB 日志中报 information schema is out of date 的错误：

  • 原因 1：执行 DML 的 TiDB 被 graceful kill 后准备退出，且此 DML 对应的事务执行时间超过一个 DDL lease，在事务提交的时候会报此错。

  • 原因 2：TiDB 在执行 DML 时，有一段时间连不上 PD 和 TiKV，导致 TiDB 在一个 DDL Lease（默认 45s）内没有加载新的 schema，或者 TiDB 断开与 PD 之间带 keep alive 设置的连接。

  • 原因 3：TiKV 压力大或网络超时，通过监控 Grafana -> TiDB 和 TiKV 节点的负载情况来确认是否是该原因。

  • 解决方法：第 1 种原因，在 TiDB 启动时手动重试该 DML 即可；第 2 种原因，需要检查 TiDB 实例和 PD 及 TiKV 的网络波动情况；第 3 种原因，需要检查 TiKV 为什么繁忙，参考 4. TiKV 问题。

3.2 OOM 问题

• 3.2.1 现象

  • 客户端：客户端收到 TiDB server 报错 ERROR 2013 (HY000): Lost connection to MySQL server during query

  • 日志：

    • dmesg -T | grep tidb-server 结果中有事故发生附近时间点的 OOM-killer 的日志。

    • tidb.log 中可以 grep 到事故发生后附近时间的 "Welcome to TiDB" 的日志（即 TiDB server 发生重启）。

    • tidb_stderr.log 中能 grep 到 fatal error: "runtime: out of memory" 或 "cannot allocate memory"。

    • v2.1.8 及其之前的版本，tidb_stderr.log 中能 grep 到 fatal error: stack overflow。

  • 监控：TiDB server 实例所在机器可用内存迅速回升

• 3.2.2 定位造成 OOM 的 SQL（目前所有版本都无法完成精准定位，需要在发现 SQL 后再做进一步分析，确认 OOM 是否的确由该 SQL 造成）：

  • > = v3.0.0 的版本，可以在 tidb.log 中 grep "expensive_query"，该 log 会记录运行超时、或使用内存超过阈值的 SQL。

  • < v3.0.0 的版本，通过 grep "memory exceeds quota" 定位运行时内存超限的 SQL。

    注意

    单条 SQL 内存阈值的默认值为 1GB，可通过系统变量 tidb_mem_quota_query 进行设置。

• 3.2.3 缓解 OOM 问题

  • 通过开启 SWAP 的方式，可以缓解由于大查询使用内存过多而造成的 OOM 问题。但该方法由于存在 I/O 开销，会在内存空间不足时对大查询性能造成一定影响。性能回退程度受剩余内存量、读写盘速度影响。

• 3.2.4 OOM 常见原因

  • SQL 中包含 join，通过 explain 查看发现该 join 选用 HashJoin 算法且 inner 端的表很大。

  • 单条 UPDATE/DELETE 涉及的查询数据量太大，见案例 case-882。

  • SQL 中包含 Union 连接的多条子查询，见案例 case-1828。

更多 OOM 的排查方法，请参考 TiDB OOM 故障排查。

3.3 执行计划不对

• 3.3.1 现象

  • SQL 相比于之前的执行时间有较大程度变慢，执行计划突然发生改变。如果慢日志中输出了执行计划，可以直接对比执行计划。

  • SQL 执行时间相比于其他数据库（例如 MySQL）有较大差距。可以对比其他数据库执行计划，例如 Join Order 是否不同。

  • 慢日志中 SQL 执行时间 Scan Keys 数目较大。

• 3.3.2 排查执行计划问题

  • explain analyze {SQL} 在执行时间可以接受的情况下，对比 explain analyze 结果中 count 和 execution info 中 rows 的数目差距。如果在 TableScan/IndexScan 行上发现比较大的差距，很大可能是统计信息出问题；如果在其他行上发现较大差距，则也有可能是非统计信息问题。

  • select count(*) 在执行计划中包含 join 等情况下，explain analyze 可能耗时过长；此时可以通过对 TableScan/IndexScan 上的条件进行 select count(*)，并对比 explain 结果中的 row count 信息，确定是不是统计信息的问题。

• 3.3.3 缓解问题

  • v3.0 及以上版本可以使用 SQL Bind 功能固定执行计划。

  • 更新统计信息。在大致确定问题是由统计信息导致的情况下，先 dump 统计信息保留现场。如果是由于统计信息过期导致，例如 show stats_meta 中 modify count/row count 大于某个值（例如 0.3）或者表中存在时间列的索引情况下，可以先尝试 analyze table 恢复；如果配置了 auto analyze，可以查看系统变量 tidb_auto_analyze_ratio 是否过大（例如大于 0.3），以及当前时间是否在 tidb_auto_analyze_start_time 和 tidb_auto_analyze_end_time 范围内。

  • 其他情况，请上报 bug。

3.4 SQL 执行报错

• 3.4.1 客户端报 ERROR 1265(01000) Data Truncated 错误。原因是 TiDB 内在计算 Decimal 类型处理精度的时候，和 MySQL 不兼容。该错误已于 v3.0.10 中修复 (#14438)，具体原因如下：

  在 MySQL 内，如果两个大精度 Decimal 做除法运算，超出最大小数精度时(30)，会只保留 30 位且不报错。TiDB 在计算结果上，也是这样实现的，但是在内部表示 Decimal 的结构体内，有一个表示小数精度的字段，还是保留的真实精度。

  比如 (0.1^30) / 10，TiDB 和 MySQL 的结果都为 0，是正确的，因为精度最多 30；但是 TiDB 内表示精度的那个字段，还是 31；

  多次 Decimal 除法计算后，虽然结果正确，但是这个精度可能越来越大，最终超过 TiDB 内的另一个阈值 72，此时就会报 Data Truncated 的错误；Decimal 的乘法计算就不会有这个问题，因为绕过越界，会直接把精度设置为最大精度限制。

  解决方法：可以通过手动加 Cast(xx as decimal(a, b)) 来绕过这个问题，a 和 b 就是目标的精度。

3.5 慢查询问题

要定位慢查询，参阅慢查询日志。要处理慢查询，参阅分析慢查询。

3.6 热点问题

TiDB 作为分布式数据库，内建负载均衡机制，尽可能将业务负载均匀地分布到不同计算或存储节点上，更好地利用上整体系统资源。然而，机制不是万能的，在一些场景下仍会有部分业务负载不能被很好地分散，影响性能，形成单点的过高负载，也称为热点。

TiDB 提供了完整的方案用于排查、解决或规避这类热点。通过均衡负载热点，可以提升整体性能，包括提高 QPS 和降低延迟等。详情参见 TiDB 热点问题处理。

3.7 TiDB 磁盘 I/O 过高

当出现系统响应变慢的时候，如果已经排查了 CPU 的瓶颈、数据事务冲突的瓶颈后，问题仍存在，就需要从 I/O 来入手来辅助判断目前的系统瓶颈点。参考 TiDB 磁盘 I/O 过高的处理办法了解如何定位和处理 TiDB 存储 I/O 过高的问题。

3.8 锁冲突问题

TiDB 支持完整的分布式事务，自 v3.0 版本起，提供乐观事务与悲观事务两种事务模式。要了解如何排查锁相关的问题，以及如何处理乐观和悲观锁冲突的问题，请参考 TiDB 锁冲突问题处理。

3.9 数据索引一致性报错

当执行事务或执行 ADMIN CHECK [TABLE|INDEX] 命令时，TiDB 会对数据索引的一致性进行检查。如果检查发现 record key-value 和 index key-value 不一致，即存储行数据的键值对和存储其对应索引的键值对之间不一致（例如多索引或缺索引），TiDB 会报数据索引一致性错误，并在日志文件中打印相关错误日志。

要了解更多数据索引一致性报错信息以及如何绕过检查，请参考数据索引一致性报错。

4. TiKV 问题

4.1 TiKV panic 启动不了

• 4.1.1 sync-log = false，机器断电之后出现 unexpected raft log index: last_index X < applied_index Y 错误。符合预期，需通过 tikv-ctl 工具恢复 Region。

• 4.1.2 虚拟机部署 TiKV，kill 虚拟机或物理机断电，出现 entries[X, Y] is unavailable from storage 错误。符合预期，虚拟机的 fsync 不可靠，需通过 tikv-ctl 工具恢复 Region。

• 4.1.3 其他原因（非预期，需报 bug）。

4.2 TiKV OOM

• 4.2.1 block-cache 配置太大导致 OOM：

  • 在监控 Grafana -> TiKV-details 选中对应的 instance 后，查看 RocksDB 的 block cache size 监控来确认是否是该问题。

  • 同时，请检查 [storage.block-cache] capacity = # "1GB" 参数是否设置合理，默认情况下 TiKV 的 block-cache 设置为机器总内存的 45%；在 container 部署时，需要显式指定该参数，因为 TiKV 获取的是物理机的内存，可能会超出 container 的内存限制。

• 4.2.2 Coprocessor 收到大量大查询，返回的数据量太大，gRPC 的发送速度跟不上 Coprocessor 往外输出数据的速度，导致 OOM：

  • 可以通过检查监控：Grafana -> TiKV-details -> coprocessor overview 的 response size 是否超过 network outbound 流量来确认是否属于这种情况。

• 4.2.3 其他部分占用太多内存（非预期，需报 bug）。

4.3 客户端报 server is busy 错误

通过查看监控：Grafana -> TiKV -> errors 确认具体 busy 原因。server is busy 是 TiKV 自身的流控机制，TiKV 通过这种方式告知 tidb/ti-client 当前 TiKV 的压力过大，稍后再尝试。

• 4.3.1 TiKV RocksDB 出现 write stall。一个 TiKV 包含两个 RocksDB 实例，一个用于存储 Raft 日志，位于 data/raft。另一个用于存储真正的数据，位于 data/db。通过 grep "Stalling" RocksDB 日志查看 stall 的具体原因，RocksDB 日志是 LOG 开头的文件，LOG 为当前日志。

  • level0 sst 太多导致 stall，可以添加参数 [rocksdb] max-sub-compactions = 2（或者 3），加快 level0 sst 往下 compact 的速度。该参数的意思是将从 level0 到 level1 的 compaction 任务最多切成 max-sub-compactions 个子任务交给多线程并发执行，见案例 case-815。

  • pending compaction bytes 太多导致 stall，磁盘 I/O 能力在业务高峰跟不上写入，可以通过调大对应 Column Family (CF) 的 soft-pending-compaction-bytes-limit 和 hard-pending-compaction-bytes-limit 参数来缓解：

    • 如果 pending compaction bytes 达到该阈值，RocksDB 会放慢写入速度。默认值 64GB，[rocksdb.defaultcf] soft-pending-compaction-bytes-limit = "128GB"。

    • 如果 pending compaction bytes 达到该阈值，RocksDB 会 stop 写入，通常不太可能触发该情况，因为在达到 soft-pending-compaction-bytes-limit 的阈值之后会放慢写入速度。默认值 256GB，hard-pending-compaction-bytes-limit = "512GB"。

    • 如果磁盘 IO 能力持续跟不上写入，建议扩容。如果磁盘的吞吐达到了上限（例如 SATA SSD 的吞吐相对 NVME SSD 会低很多）导致 write stall，但是 CPU 资源又比较充足，可以尝试采用压缩率更高的压缩算法来缓解磁盘的压力，用 CPU 资源换磁盘资源。

    • 比如 default cf compaction 压力比较大，调整参数 [rocksdb.defaultcf] compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"] 改成 compression-per-level = ["no", "no", "zstd", "zstd", "zstd", "zstd", "zstd"]。

  • memtable 太多导致 stall。该问题一般发生在瞬间写入量比较大，并且 memtable flush 到磁盘的速度比较慢的情况下。如果磁盘写入速度不能改善，并且只有业务峰值会出现这种情况，可以通过调大对应 CF 的 max-write-buffer-number 来缓解：

    • 例如 [rocksdb.defaultcf] max-write-buffer-number = 8 （默认值 5），同时请求注意在高峰期可能会占用更多的内存，因为可能存在于内存中的 memtable 会更多。

• 4.3.2 scheduler too busy

  • 写入冲突严重，latch wait duration 比较高，查看监控：Grafana -> TiKV-details -> scheduler prewrite 或者 scheduler commit 的 latch wait duration。scheduler 写入任务堆积，导致超过了 [storage] scheduler-pending-write-threshold = "100MB" 设置的阈值。可通过查看 MVCC_CONFLICT_COUNTER 对应的 metric 来确认是否属于该情况。
  • 写入慢导致写入堆积，该 TiKV 正在写入的数据超过了 [storage] scheduler-pending-write-threshold = "100MB" 设置的阈值。请参考 4.5 TiKV 写入慢。

• 4.3.3 raftstore is busy，主要是消息的处理速度没有跟上接收消息的速度。短时间的 channel full 不会影响服务，长时间持续出现该错误可能会导致 Leader 切换走。

  • append log 遇到了 stall，参考 4.3.1 客户端报 server is busy 错误。
  • append log duration 比较高，导致处理消息不及时，可以参考 4.5 TiKV 写入慢分析为什么 append log duration 比较高。
  • 瞬间收到大量消息（查看 TiKV Raft messages 面板），Raftstore 没处理过来，通常情况下短时间的 channel full 不会影响服务。

• 4.3.4 TiKV Coprocessor 排队，任务堆积超过了 Coprocessor 线程数 * readpool.coprocessor.max-tasks-per-worker-[normal|low|high]。大量大查询导致 Coprocessor 出现了堆积情况，需要确认是否由于执行计划变化而导致了大量扫表操作，请参考 3.3 执行计划不对。

4.4 某些 TiKV 大量掉 Leader

• 4.4.1 TiKV 重启，导致重新选举。

  • TiKV panic 之后又被 systemd 重新拉起正常运行，可以通过查看 TiKV 的日志来确认是否有 panic，这种情况属于非预期，需报 bug。
  • 被第三者 stop/kill，被 systemd 重新拉起。查看 dmesg 和 TiKV log 确认原因。
  • TiKV 发生 OOM 导致重启了，参考 4.2 TiKV OOM 问题。
  • 动态调整 THP 导致 hung 住，见案例 case-500。

• 4.4.2 查看监控：Grafana -> TiKV-details -> errors 面板 server is busy，看到 TiKV RocksDB 出现 write stall 导致发生重新选举，请参考 4.3.1。

• 4.4.3 网络隔离导致重新选举。

4.5 TiKV 写入慢

• 4.5.1 通过查看 TiKV gRPC 的 prewrite/commit/raw-put（仅限 raw kv 集群）duration 确认确实是 TiKV 写入慢了。通常情况下可以按照 performance-map 来定位到底哪个阶段慢了，下面列出几种常见的情况。

• 4.5.2 scheduler CPU 繁忙（仅限 transaction kv）。prewrite/commit 的 scheduler command duration 比 scheduler latch wait duration + storage async write duration 更长，并且 scheduler worker CPU 比较高，例如超过 scheduler-worker-pool-size * 100% 的 80%，并且或者整个机器的 CPU 资源比较紧张。如果写入量很大，确认下是否 [storage] scheduler-worker-pool-size 配置得太小。其他情况，需报 bug。

• 4.5.3 Append log 慢。TiKV Grafana 的 Raft IO/append log duration 比较高，通常情况下是由于写盘慢了，可以检查 RocksDB - Raft 的 WAL Sync Duration max 值来确认，否则可能需要报 bug。

• 4.5.4 Raftstore 线程繁忙。TiKV Grafana 的 Raft Propose/propose wait duration 明显高于 append log duration。请查看以下情况：

  • [raftstore] store-pool-size 配置是否过小（该值建议在 [1,5] 之间，不建议太大）。
  • 机器的 CPU 是不是不够。

• 4.5.5 apply 慢了。TiKV Grafana 的 Raft IO/apply log duration 比较高，通常会伴随着 Raft Propose/apply wait duration 比较高。可能是以下原因引起的：

  • [raftstore] apply-pool-size 配置过小（建议在 [1, 5] 之间，不建议太大），Thread CPU/apply cpu 比较高；
  • 机器的 CPU 资源不够了；
  • Region 写入热点问题，单个 apply 线程 CPU 使用率比较高（通过修改 Grafana 表达式，加上 by (instance, name) 来看各个线程的 CPU 使用情况），暂时对于单个 Region 的热点写入没有很好的方式，最近在优化该场景；
  • 写 RocksDB 比较慢，RocksDB kv/max write duration 比较高（单个 Raft log 可能包含很多个 kv，写 RocksDB 的时候会把 128 个 kv 放在一个 write batch 写入到 RocksDB，所以一次 apply log 可能涉及到多次 RocksDB 的 write）；
  • 其他情况，需报 bug。

• 4.5.6 Raft commit log 慢了。

  • TiKV Grafana 的 Raft IO/commit log duration 比较高（4.x 版本的 Grafana 才有该 metric）。每个 Region 对应一个独立的 Raft group，Raft 本身是有流控机制的，类似 TCP 的滑动窗口机制，通过参数 [raftstore] raft-max-inflight-msgs = 256 来控制滑动窗口的大小，如果有热点写入并且 commit log duration 比较高可以适度调大该参数，比如 1024。

• 4.5.7 其他情况，请参考 Performance Map 上的写入路径来分析。

5. PD 问题

5.1 PD 调度问题

• 5.1.1 merge 问题：

  • 跨表空 Region 无法 merge，需要修改 TiKV 的 [coprocessor] split-region-on-table = false 参数来解决，4.x 版本该参数默认为 false，见案例 case-896。

  • Region merge 慢，可检查监控 Grafana -> PD -> operator 面板是否有 merge 的 operator 产生，可以适当调大 merge-schedule-limit 参数来加速 merge。

• 5.1.2 补副本/上下线问题：

  • TiKV 磁盘使用 80% 容量，PD 不会进行补副本操作，miss peer 数量上升，需要扩容 TiKV，见案例 case-801。

  • 下线 TiKV，有 Region 长时间迁移不走。v3.0.4 版本已经修复改问题，见 #5526 和案例 case-870。

• 5.1.3 Balance 问题：

  • Leader/Region count 分布不均，见案例 case-394, case-759。主要原因是 balance 是依赖 Region/leader 的 size 去调度的，所以可能会造成 count 数量的不均衡，v4.0 新增了一个参数 [leader-schedule-policy]，可以调整 Leader 的调度策略，根据 "count" 或者是 "size" 进行调度。

5.2 PD 选举问题

• 5.2.1 PD 发生 Leader 切换：

  • 磁盘问题，PD 所在的节点 I/O 被打满，排查是否有其他 I/O 高的组件与 PD 混部以及盘的健康情况，可通过监控 Grafana -> disk performance -> latency 和 load 等指标进行验证，必要时可以使用 fio 工具对盘进行检测，见案例 case-292。

  • 网络问题，PD 日志中有 lost the TCP streaming connection，排查 PD 之间网络是否有问题，可通过监控 Grafana -> PD -> etcd 的 round trip 来验证，见案例 case-177。

  • 系统 load 高，日志中能看到 server is likely overloaded，见案例 case-214。

• 5.2.2 PD 选不出 Leader 或者选举慢：

  • 选不出 Leader，PD 日志中有 lease is not expired，见 #10355。v3.0.x 版本和 v2.1.19 版本已修复该问题，见案例 case-875。

  • 选举慢，Region 加载时间长。从 PD 日志中 grep "regions cost"（例如日志中可能是 "load 460927 regions cost 11.77099s"），如果出现秒级，则说明较慢，v3.0 版本可开启 Region storage（设置 use-region-storage 为 true），该特性能极大缩短加载 Region 的时间，见案例 case-429。

• 5.2.3 TiDB 执行 SQL 时报 PD timeout：

  • PD 没 Leader 或者有切换，参考 5.2.1 PD 选举问题和 5.2.2 PD 选举问题。

  • 网络问题，排查网络相关情况。通过监控 Grafana -> blackbox_exporter -> ping latency 确定 TiDB 到 PD Leader 的网络是否正常。

  • PD panic，需报 bug。

  • PD OOM，参考 5.3 PD OOM 问题。

  • 其他原因，通过 curl http://127.0.0.1:2379/debug/pprof/goroutine?debug=2 抓 goroutine，报 bug。

• 5.2.4 其他问题

  • PD 报 FATAL 错误，日志中有 range failed to find revision pair，v3.0.8 已经修复该问题，见 #2040。详情参考案例 case-947。

  • 其他原因，需报 bug。

5.3 PD OOM

• 5.3.1 使用 /api/v1/regions 接口时 Region 数量过多，可能会导致 PD OOM，在 v3.0.8 版本中修复，见 #1986。

• 5.3.2 滚动升级的时候 PD OOM，gRPC 消息大小没限制，监控可看到 TCP InSegs 较大，在 v3.0.6 版本中修复，见 #1952。

5.4 Grafana 显示问题

• 5.4.1 监控 Grafana -> PD -> cluster -> role 显示 follower，Grafana 表达式问题，在 v3.0.8 版本修复。

6. 生态 Tools 问题

6.1 TiDB Binlog 问题

• 6.1.1 TiDB Binlog 是将 TiDB 的修改同步给下游 TiDB 或者 MySQL 的工具，见 TiDB Binlog on GitHub。

• 6.1.2 Pump/Drainer Status 中 Update Time 正常更新，日志中也没有异常，但下游没有数据写入。

  • TiDB 配置中没有开启 binlog，需要修改 TiDB 配置 [binlog]。

• 6.1.3 Drainer 中的 sarama 报 EOF 错误。

  • Drainer 使用的 Kafka 客户端版本和 Kafka 版本不匹配，需要修改配置 [syncer.to] kafka-version 来解决。

• 6.1.4 Drainer 写 Kafka 失败然后 panic，Kafka 报 Message was too large 错误。

  • binlog 数据太大，造成写 Kafka 的单条消息太大，需要修改 Kafka 的下列配置来解决：

    message.max.bytes=1073741824
    replica.fetch.max.bytes=1073741824
    fetch.message.max.bytes=1073741824
    

    见案例 case-789。

• 6.1.5 上下游数据不一致

  • 部分 TiDB 节点没有开启 binlog。v3.0.6 及之后的版本可以通过访问 http://127.0.0.1:10080/info/all 接口可以检查所有节点的 binlog 状态。之前的版本可以通过查看配置文件来确认是否开启了 binlog。

  • 部分 TiDB 节点进入 ignore binlog 状态。v3.0.6 及之后的版本可以通过访问 http://127.0.0.1:10080/info/all 接口可以检查所有节点的 binlog 状态。之前的版本需要看 TiDB 的日志中是否有 ignore binlog 关键字来确认是该问题。

  • 上下游 Timestamp 列的值不一致：

    • 时区问题，需要确保 Drainer 和上下游数据库时区一致，Drainer 通过 /etc/localtime 获取时区，不支持 TZ 环境变量，见案例 case-826。

    • TiDB 中 Timestamp 的默认值为 null，MySQL 5.7 中 Timestamp 默认值为当前时间（MySQL 8 无此问题），因此当上游写入 null 的 Timestamp 且下游是 MySQL 5.7 时，Timestamp 列数据不一致。在开启 binlog 前，在上游执行 set @@global.explicit_defaults_for_timestamp=on; 可解决此问题。

  • 其他情况需报 bug。

• 6.1.6 同步慢

  • 下游是 TiDB/MySQL，上游频繁进行 DDL 操作，见案例 case-1023。

  • 下游是 TiDB/MySQL，需要同步的表中存在没有主键且没有唯一索引的表，这种情况会导致 binlog 性能下降，建议加主键或唯一索引。

  • 下游输出到文件，检查目标磁盘/网络盘是否慢。

  • 其他情况需报 bug。

• 6.1.7 Pump 无法写 binlog，报 no space left on device 错误。

  • 本地磁盘空间不足，Pump 无法正常写 binlog 数据。需要清理磁盘空间，然后重启 Pump。

• 6.1.8 Pump 启动时报错 fail to notify all living drainer。

  • Pump 启动时需要通知所有 Online 状态的 Drainer，如果通知失败则会打印该错误日志。

  • 可以使用 binlogctl 工具查看所有 Drainer 的状态是否有异常，保证 Online 状态的 Drainer 都在正常工作。如果某个 Drainer 的状态和实际运行情况不一致，则使用 binlogctl 修改状态，然后再重启 Pump。见案例 fail-to-notify-all-living-drainer。

• 6.1.9 Drainer 报错 gen update sqls failed: table xxx: row data is corruption []。

  • 触发条件：上游做 Drop Column DDL 的时候同时在做这张表的 DML。已经在 v3.0.6 修复，见 case-820。

• 6.1.10 Drainer 同步卡住，进程活跃但 checkpoint 不更新。

  • 已知 bug 在 v3.0.4 修复，见案例 case-741。

• 6.1.11 任何组件 panic。

  • 需报 bug。

6.2 DM 问题

• 6.2.1 TiDB Data Migration (DM) 是能将 MySQL/MariaDB 的数据迁移到 TiDB 的迁移工具，详情见 DM 简介。

• 6.2.2 执行 query-status 或查看日志时出现 Access denied for user 'root'@'172.31.43.27' (using password: YES)。

  • 在所有 DM 配置文件中，数据库相关的密码都必须使用经 dmctl 加密后的密文（若数据库密码为空，则无需加密）。在 v1.0.6 及以后的版本可使用明文密码。

  • 在 DM 运行过程中，上下游数据库的用户必须具备相应的读写权限。在启动同步任务过程中，DM 会自动进行相应权限的检查。

  • 同一套 DM 集群，混合部署不同版本的 DM-worker/DM-master/dmctl，见案例 AskTUG-1049。

• 6.2.3 DM 同步任务中断并包含 driver: bad connection 错误。

  • 发生 driver: bad connection 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启等）且当前请求的数据暂时未能发送到 TiDB。

    • 1.0.0 GA 之前的版本，DM 发生该类型错误时，需要先使用 stop-task 命令停止任务后再使用 start-task 命令重启任务。

    • 1.0.0 GA 版本，增加对此类错误的自动重试机制，见 #265。

• 6.2.4 同步任务中断并包含 invalid connection 错误。

  • 发生 invalid connection 错误时，通常表示 DM 到下游 TiDB 的数据库连接出现了异常（如网络故障、TiDB 重启、TiKV busy 等）且当前请求已有部分数据发送到了 TiDB。由于 DM 中存在同步任务并发向下游复制数据的特性，因此在任务中断时可能同时包含多个错误（可通过 query-status 或 query-error 查询当前错误）：

    • 如果错误中仅包含 invalid connection 类型的错误，且当前处于增量复制阶段，则 DM 会自动进行重试。

    • 如果 DM 由于版本问题（v1.0.0-rc.1 后引入自动重试）等未自动进行重试或自动重试未能成功，则可尝试先使用 stop-task 停止任务，然后再使用 start-task 重启任务。

• 6.2.5 Relay 处理单元报错 event from * in * diff from passed-in event * 或同步任务中断并包含 get binlog error ERROR 1236 (HY000)、binlog checksum mismatch, data may be corrupted 等 binlog 获取或解析失败错误。

  • 在 DM 进行 relay log 拉取与增量同步过程中，如果遇到了上游超过 4 GB 的 binlog 文件，就可能出现这两个错误。原因是 DM 在写 relay log 时需要依据 binlog position 及文件大小对 event 进行验证，且需要保存同步的 binlog position 信息作为 checkpoint。但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4 GB 部分的 binlog position 的 offset 值会溢出，进而出现上面的错误。

    • 对于 relay 处理单元，可通过官网步骤进行手动处理。

    • 对于 binlog replication 处理单元，可通过官网步骤进行手动处理。

• 6.2.6 DM 同步中断，日志报错 ERROR 1236 (HY000) The slave is connecting using CHANGE MASTER TO MASTER_AUTO_POSITION = 1, but the master has purged binary logs containing GTIDs that the slave requires.。

  • 检查 master 的 binlog 是否被 purge。

  • 检查 relay.meta 中记录的位点信息。

    • relay.meta 中记录空的 GTID 信息，DM-worker 进程在退出时、以及定时 (30s) 会把内存中的 GTID 信息保存到 relay.meta 中，在没有获取到上游 GTID 信息的情况下，把空的 GTID 信息保存到了 relay.meta 中。见案例 case-772。

    • relay.meta 中记录的 binlog event 不完整触发 recover 流程后记录错误的 GTID 信息，该问题可能会在 1.0.2 之前的版本遇到，已在 1.0.2 版本修复。

• 6.2.7 DM 同步报错 Error 1366: incorrect utf8 value eda0bdedb29d(\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd)。

  • 该值 MySQL 8.0 和 TiDB 都不能写入成功，但是 MySQL 5.7 可以写入成功。可以开启 TiDB 动态参数 tidb_skip_utf8_check 参数，跳过数据格式检查。

6.3 TiDB Lightning 问题

• 6.3.1 TiDB Lightning 是快速的全量数据导入工具，见 TiDB Lightning on GitHub。

• 6.3.2 导入速度太慢。

  • region-concurrency 设定太高，线程间争用资源反而减低了效率。排查方法如下：

    • 从日志的开头搜寻 region-concurrency 能知道 TiDB Lightning 读到的参数是多少；
    • 如果 TiDB Lightning 与其他服务（如 TiKV Importer）共用一台服务器，必需手动将 region-concurrency 设为该服务器 CPU 数量的 75%；
    • 如果 CPU 设有限额（例如从 Kubernetes 指定的上限），TiDB Lightning 可能无法自动判断出来，此时亦需要手动调整 region-concurrency。

  • 表结构太复杂。每条索引都会额外增加 KV 对，如果有 N 条索引，实际导入的大小就差不多是 Mydumper 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 CREATE INDEX 加回去。

  • TiDB Lightning 版本太旧。尝试使用最新的版本，可能会有改善。

• 6.3.3 checksum failed: checksum mismatched remote vs local

  • 原因 1：这张表可能本身已有数据，影响最终结果。

  • 原因 2：如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。

  • 原因 3：如果数据源是由机器生成而不是从 Mydumper 备份的，需确保数据符合表的限制。例如：

    • 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。
    • 单一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。

  • 解决办法：参考官网步骤处理。

• 6.3.4 Checkpoint for … has invalid status:(错误码)

  • 原因：断点续传已启用。TiDB Lightning 或 TiKV Importer 之前发生了异常退出。为了防止数据意外损坏，TiDB Lightning 在错误解决以前不会启动。错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。

  • 解决办法：参考官网步骤处理。

• 6.3.5 ResourceTemporarilyUnavailable("Too many open engines …: 8")

  • 原因：并行打开的引擎文件 (engine files) 超出 tikv-importer 里的限制。这可能由配置错误引起。即使配置没问题，如果 tidb-lightning 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。

  • 解决办法：参考官网步骤处理。

• 6.3.6 cannot guess encoding for input file, please convert to UTF-8 manually

  • 原因：TiDB Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如在不同的环境运行过 ALTER TABLE，使表架构同时出现 UTF-8 和 GB-18030 的字符。

  • 解决办法：参考官网步骤处理。

• 6.3.7 [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 0 45 0 0}'

  • 原因：一个 timestamp 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏令时切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。

  • 解决办法：参考官网步骤处理。

7. 常见日志分析

7.1 TiDB

• 7.1.1 GC life time is shorter than transaction duration。事务执行时间太长，超过了 GC lifetime（默认为 10 分钟），可以通过修改系统变量 tidb_gc_life_time 来延长 life time，通常情况下不建议修改，因为延长时限可能导致大量老版本数据的堆积（如果有大量 UPDATE 和 DELETE 语句）。

• 7.1.2 txn takes too much time。事务太长时间（超过 590s）没有提交，准备提交的时候报该错误。可以通过调大 [tikv-client] max-txn-time-use = 590 参数，以及调大 GC life time 来绕过该问题（如果确实有这个需求）。通常情况下，建议看看业务是否真的需要执行这么长时间的事务。

• 7.1.3 coprocessor.go 报 request outdated。发往 TiKV 的 Coprocessor 请求在 TiKV 端排队时间超过了 60s，直接返回该错误。需要排查 TiKV Coprocessor 为什么排队这么严重。

• 7.1.4 region_cache.go 大量报 switch region peer to next due to send request fail 且 error 信息是 context deadline exceeded。请求 TiKV 超时触发 region cache 切换请求到其他节点，可以对日志中的 addr 字段继续 grep "<addr> cancelled"，根据 grep 结果：

  • send request is cancelled。请求发送阶段超时，可以排查监控 Grafana -> TiDB -> Batch Client/Pending Request Count by TiKV 是否大于 128，确定是否因发送远超 KV 处理能力导致发送堆积。如果 Pending Request 不多，需要排查日志确认是否因为对应 KV 有运维变更，导致短暂报出；否则非预期，需报 bug。

  • wait response is cancelled。请求发送到 TiKV 后超时未收到 TiKV 响应。需要排查对应地址 TiKV 的响应时间和对应 Region 在当时的 PD 和 KV 日志，确定为什么 KV 未及时响应。

• 7.1.5 distsql.go 报 inconsistent index。数据索引疑似发生不一致，首先对报错的信息中 index 所在表执行 admin check table <TableName> 命令，如果检查失败，则先通过以下命令禁用 GC，然后报 bug。

  SET GLOBAL tidb_gc_enable = 0;
  

7.2 TiKV

• 7.2.1 key is locked 读写冲突，读请求碰到还未提交的数据，需要等待其提交之后才能读。少量这个错误对业务无影响，大量出现这个错误说明业务读写冲突比较严重。

• 7.2.2 write conflict 乐观事务中的写写冲突，同时多个事务对相同的 key 进行修改，只有一个事务会成功，其他事务会自动重取 timestamp 然后进行重试，不影响业务。如果业务冲突很严重可能会导致重试多次之后事务失败，这种情况下建议使用悲观锁。报错以及解决方法详情，参考乐观事务模型下写写冲突问题排查。

• 7.2.3 TxnLockNotFound 事务提交太慢，过了 TTL (Time To Live) 时间之后被其他事务回滚了，该事务会自动重试，通常情况下对业务无感知。对于 0.25 MB 以内的小事务，TTL 默认时间为 3 秒。详情参见锁被清除 (LockNotFound) 错误。

• 7.2.4 PessimisticLockNotFound 类似 TxnLockNotFound，悲观事务提交太慢被其他事务回滚了。

• 7.2.5 stale_epoch 请求的 epoch 太旧了，TiDB 会更新路由之后再重新发送请求，业务无感知。epoch 在 Region 发生 split/merge 以及迁移副本的时候会变化。

• 7.2.6 peer is not leader 请求发到了非 Leader 的副本上，TiDB 会根据该错误更新本地路由（如果错误 response 里携带了最新 Leader 是哪个副本这一信息），并且重新发送请求到最新 Leader，一般情况下业务无感知。在 v3.0 后 TiDB 在原 Leader 请求失败时会尝试其他 peer，也会导致 TiKV 频繁出现 not leader 日志，可以通过查看 TiDB 对应 Region 的 switch region peer to next due to send request fail 日志，排查发送失败根本原因，参考 7.1.4 TiDB。另外也可能是由于其他原因导致一些 Region 一直没有 Leader，请参考 4.4 某些 TiKV 大量掉 Leader。