From bfefc827ef45533ce1eefcfb70d544c8257a2591 Mon Sep 17 00:00:00 2001 From: amyangfei Date: Wed, 29 Apr 2020 19:36:49 +0800 Subject: [PATCH] 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 | 1 + reference/tools/ticdc/deploy.md | 10 +++++ reference/tools/ticdc/manage.md | 11 ------ reference/tools/ticdc/overview.md | 10 ++++- reference/tools/ticdc/troubleshoot.md | 57 +++++++++++++++++++++++++++ 5 files changed, 77 insertions(+), 12 deletions(-) create mode 100644 reference/tools/ticdc/troubleshoot.md diff --git a/TOC.md b/TOC.md index 7e657b1ca07a..6e7a67ec7763 100644 --- a/TOC.md +++ b/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) diff --git a/reference/tools/ticdc/deploy.md b/reference/tools/ticdc/deploy.md index 58133688e36e..badfdcf1e1e4 100644 --- a/reference/tools/ticdc/deploy.md +++ b/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` 的事务。 diff --git a/reference/tools/ticdc/manage.md b/reference/tools/ticdc/manage.md index a897a7643996..fa46dae972d7 100644 --- a/reference/tools/ticdc/manage.md +++ b/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` 对应的事务，然后恢复同步任务。 diff --git a/reference/tools/ticdc/overview.md b/reference/tools/ticdc/overview.md index 4dc62a5d5b09..583923e16df4 100644 --- a/reference/tools/ticdc/overview.md +++ b/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 无法进入静默状态。 diff --git a/reference/tools/ticdc/troubleshoot.md b/reference/tools/ticdc/troubleshoot.md new file mode 100644 index 000000000000..253ea90c8ede --- /dev/null +++ b/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 发布版本）还不支持动态修改文件排序和内存排序。