tools: update ticdc common maintenance (#2909)

Co-authored-by: TomShawn <1135243111@qq.com>
Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>

TOC.md

@@ -351,6 +351,7 @@
       - [概述](/reference/tools/ticdc/overview.md)
       - [部署使用](/reference/tools/ticdc/deploy.md)
       - [集群和同步任务管理](/reference/tools/ticdc/manage.md)
+      - [常见问题和故障处理](/reference/tools/ticdc/troubleshoot.md)
       - [Sink URI 配置规则](/reference/tools/ticdc/sink.md)
       - [开放数据协议](/reference/tools/ticdc/open-protocol.md)
       - [Column 和 DDL 的类型码](/reference/tools/ticdc/column-ddl-type.md)

reference/tools/ticdc/deploy.md

@@ -19,6 +19,15 @@ cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_2.log --status-addr=127.
 cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_3.log --status-addr=127.0.0.1:8303
 ```
 
+对于 `cdc server` 命令中可用选项解释如下：
+
+- `gc-ttl`: TiCDC 在 PD 设置的服务级别 GC safepoint 的 TTL (Time To Live) 时长，单位为秒，默认值为 `86400`，即 24 小时。
+- `pd`: PD client 的 URL。
+- `status-addr`: TiCDC 服务的 HTTP API 查询地址和 Prometheus 查询地址。
+- `tz`: TiCDC 服务使用的时区。TiCDC 在内部转换 timestamp 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。
+- `log-file`: TiCDC 进程运行日志的地址，默认为 `cdc.log`。
+- `log-level`: TiCDC 进程运行时默认的日志级别，默认为 `info`。
+
 ## 第 2 步：创建同步任务
 
 假设需要将上游所有的库表（系统表除外）同步到下游的 MySQL，可以通过以下命令创建同步任务：
@@ -33,6 +42,7 @@ cdc cli changefeed create --pd=http://10.0.10.25:2379 --start-ts=415238226621235
 
 - `pd`: PD client 的 URL。
 - `start-ts`: 指定开始同步的 TSO，不指定或指定为 `0` 时将使用当前 TSO 作为同步的起始 TSO。
+- `target-ts`: 指定同步结束的 TSO，不指定默认会永久同步。
 - `sink-uri`: sink 地址，目前支持 `mysql`/`tidb` 和 `kafka`。关于 sink URI 的写法请参考 [sink URI 配置规则](/reference/tools/ticdc/sink.md)
 - `config`: 同步任务的配置。目前提供黑白名单配置和跳过特定 `commit-ts` 的事务。
 

reference/tools/ticdc/manage.md

@@ -255,14 +255,3 @@ curl -X POST -d "admin-job=3&cf-id=28c43ffc-2316-4f4f-a70b-d1a7c59ba79f" http://
 
 - `admin-job=3`，表示删除任务，接口请求后会结束所有同步 `processor`，并清理同步任务配置信息。同步状态保留，只提供查询，没有其他实际功能。
 - `cf-id=xxx` 为需要操作的 `changefeed` ID。
-
-## 异常管理
-
-本部分描述如何管理 TiCDC 同步数据中遇到的异常。
-
-### TiCDC 向下游同步语句出错
-
-TiCDC 向下游执行 DDL 或 DML 语句出错后会自动停止同步任务。
-
-- 如果是因为下游异常、网络抖动等情况，可以直接恢复任务重试；
-- 如果是因为下游不兼容的 SQL 问题，重试任务不会成功。此时可以通过同步配置的 `ignore-txn-commit-ts` 参数跳过指定 `commit-ts` 对应的事务，然后恢复同步任务。

reference/tools/ticdc/overview.md

@@ -41,9 +41,17 @@ TiCDC 的系统架构如下图所示：
 
 用户可以通过编写黑白名单过滤规则，来过滤或只同步某些数据库或某些表的所有变更数据。过滤规则类似于 MySQL `replication-rules-db` 或 `replication-rules-table`。
 
-## 使用限制
+## 同步限制
 
 将数据同步到 TiDB 或 MySQL，需要满足以下条件才能保证正确性：
 
 - 表必须要有主键或者唯一索引。
 - 如果表只存在唯一索引，至少有一个唯一索引的每一列在表结构中明确定义 `NOT NULL`。
+
+### 暂不支持的场景
+
+目前 TiCDC（4.0 发布版本）与部分 TiDB 特性存在冲突，在后续的 TiCDC 版本上会逐渐修复。当前版本需要做相应的兼容性处理。暂不支持的场景如下：
+
+- 暂不支持同步分区表。
+- 暂不支持 TiDB 4.0 [新的 Collation 框架](/reference/sql/characterset-and-collation.md#新框架下的-collation-支持)。如果开启该功能，需保证下游集群为 TiDB 并使用与上游相同的 collation，否则会出现 collation 导致的无法定位数据的问题。
+- 暂不支持 [TiKV Hibernate Region](https://github.com/tikv/tikv/blob/master/docs/reference/configuration/raftstore-config.md#hibernate-region)。TiCDC 会使 Region 无法进入静默状态。

reference/tools/ticdc/troubleshoot.md

@@ -0,0 +1,57 @@
+---
+title: 常见问题和故障处理
+category: reference
+---
+
+# 常见问题和故障处理
+
+本文档总结了在使用 TiCDC 过程中经常遇到的问题，给出合适的运维方法。本文档还总结了常见的运行故障，并给出相对应的解决方案。
+
+## 启动任务时如何选择 start-ts
+
+首先需要理解同步任务的 `start-ts` 对应于上游 TiDB 集群的一个 TSO，同步任务会从这个 TSO 开始请求数据。所以同步任务的 `start-ts` 需要满足以下两个条件：
+
+- `start-ts` 的值需要大于 TiDB 集群当前的 `tikv_gc_safe_point`，否则创建任务时会报错。
+- 启动任务时，需要保证下游已经具有 `start-ts` 之前的所有数据。对于同步到消息队列等场景，如果不需要保证上下游数据的一致，可根据业务场景放宽此要求。
+
+如果不指定 `start-ts` 或者指定 `start-ts=0`，在启动任务的时候会去 PD 获取一个当前 TSO，并从该 TSO 开始同步。
+
+## 启动任务时提示部分表不能同步
+
+在使用 `cdc cli changefeed create` 创建同步任务时会检查上游表是否符合[同步限制](/reference/tools/ticdc/overview.md#同步限制)。如果存在表不满足同步限制，会提示 `some tables are not eligible to replicate` 并列出这些不满足的表。用户选择 `Y` 或 `y` 则会继续创建同步任务，并且同步过程中自动忽略这些表的所有更新。用户选择其他输入，则不会创建同步任务。
+
+## 同步中断的处理方法
+
+目前已知可能发生的同步中断包括以下两类场景：
+
+- 下游持续异常，TiCDC 多次重试后仍然失败。
+
+    - 该场景下 TiCDC 会保存任务信息，由于 TiCDC 已经在 PD 中设置的 service GC safepoint，在 `gc-ttl` 的有效期内，同步任务 checkpoint 之后的数据不会被 TiKV GC 清理掉。
+
+    - 处理方法：用户可以在下游恢复正常后，通过 HTTP 接口恢复同步任务。
+
+- 因下游存在不兼容的 SQL 语句，导致同步不能继续。
+
+    - 该场景下 TiCDC 会保存任务信息，由于 TiCDC 已经在 PD 中设置的 service GC safepoint，在 `gc-ttl` 的有效期内，同步任务 checkpoint 之后的数据不会被 TiKV GC 清理掉。
+    - 处理方法：
+        1. 用户需先通过 `cdc cli changefeed query` 查询同步任务状态信息，记录 `checkpoint-ts` 值。
+        2. 使用新的任务配置文件，增加`ignore-txn-commit-ts` 参数跳过指定 `commit-ts` 对应的事务。
+        3. 通过 HTTP API 停止旧的同步任务，使用 `cdc cli changefeed create` ，指定新的任务配置文件，指定 `start-ts` 为刚才记录的 `checkpoint-ts`，启动新的同步任务恢复同步。
+
+## `gc-ttl` 和文件排序
+
+最新版本（v4.0.0-rc.1 之后）的 PD 支持外部服务设置服务级别 GC safepoint。任何一个服务可以注册更新自己服务的 GC safepoint。PD 会保证任何小于该 GC safepoint 的 KV 数据不会在 TiKV 中被 GC 清理掉。在 TiCDC 中启用了这一功能，用来保证 TiCDC 在不可用、或同步任务中断情况下，可以在 TiKV 内保留 TiCDC 需要消费的数据不被 GC 清理掉。
+
+启动 CDC server 时可以通过 `gc-ttl` 指定 GC safepoint 的 TTL，这个值的含义是当 TiCDC 服务全部挂掉后，由 TiCDC 在 PD 所设置的 GC safepoint 保存的最长时间，该值默认为 86400 秒。
+
+如果同步任务长时间中断，累积未消费的数据比较多，初始启动 TiCDC 可能会发生 OOM。这种情况下可以启用 TiCDC 提供的文件排序功能，该功能会使用文件系统文件进行排序。启用的方式是创建同步任务时在 `cdc cli` 内传入 `--sort-engine=file` 和 `--sort-dir=/path/to/sort_dir`，使用示例如下：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+cdc cli changefeed create --pd=http://10.0.10.25:2379 --start-ts=415238226621235200 --sink-uri="mysql://root:123456@127.0.0.1:3306/" --sort-engine="file" --sort-dir="/data/cdc/sort"
+```
+
+> **注意：**
+>
+> TiCDC（4.0 发布版本）还不支持动态修改文件排序和内存排序。