From 07f4512c5306f48ca73a2e26c8bf87b4c35d0043 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Fri, 15 Dec 2023 15:39:47 +0800 Subject: [PATCH 01/13] update --- ticdc/ticdc-open-api-v2.md | 78 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index ced549a235d3..ccdaa296dfe3 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1024,3 +1024,81 @@ curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2 ``` 如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。 + +## 查询特定同步任务同步是否完成 + +该接口是一个同步接口，请求成功后会返回指定的同步任务(changefeed)的同步完成情况，包括是否同步完成，以及一些更详细的信息。 + +### 请求 URI + +`GET /api/v2/changefeed/{changefeed_id}/synced` + +### 参数说明 + +#### 路径参数 + +| 参数名 | 说明 | +|:----------------|:----------------------------| +| `changefeed_id` | 需要查询的同步任务 (changefeed) 的 ID | + +### 使用样例 + +以下请求会查询 ID 为 `test1` 的同步任务的同步完成状态。 + +```shell +curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced +``` + +示例1 + +```json +{ + "synced": true, + "sink_checkpoint_ts": "2023-11-30 15:14:11", + "puller_resolved_ts": "2023-11-30 15:14:09", + "last_synced_ts": "2023-11-30 15:08:35", + "now_ts": "2023-11-30 15:14:11", + "info": "Data syncing is finished" +} +``` + +以上返回的信息的说明如下： + +- `synced`：该同步任务是否已经彻底同步完成了，true 则表示一定完成了同步任务，false 则表示并不一定完成了同步任务，具体需要结合 "info" 字段描述以及其他字段进行判断。 +- `sink_checkpoint_ts`: sink 模块的 checkpoint-ts 值，时间为 PD 时间。 +- `puller_resolved_ts`: puller 模块的 resolved-ts 值，时间为 PD 时间。 +- `last_synced_ts`: ticdc 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 +- `now_ts`: 当前的 PD 时间 +- `info`: 一些帮助判断的信息，主要在 synced 为 false 时候使用。 + +示例2 + +```json +{ + "synced": false, + "sink_checkpoint_ts": "2023-11-30 15:26:31", + "puller_resolved_ts": "2023-11-30 15:26:23", + "last_synced_ts": "2023-11-30 15:24:30", + "now_ts": "2023-11-30 15:26:31", + "info": "The data syncing is not finished, please wait" +} + +{ + "synced":false, + "sink_checkpoint_ts":"2023-12-13 11:45:13", + "puller_resolved_ts":"2023-12-13 11:45:13", + "last_synced_ts":"2023-12-13 11:45:07", + "now_ts":"2023-12-13 11:47:24", + "info":"Please check whether pd is health and tikv region is all available. If pd is not health or tikv region is not available, the data syncing is finished. Otherwise the data syncing is not finished, please wait" +} + +{ + "error_msg": "[CDC:ErrPDEtcdAPIError]etcd api call error: context deadline exceeded", + "error_code": "CDC:ErrPDEtcdAPIError" +} +``` + +该示例展示的是并未严格的完成同步任务时返回的查询结果，我们可以结合 `synced` 和 `info` 字段确认数据目前同步的状态。 +因为该接口支持在上游集群发生灾害的时候进行查询判断，所以在部分情况下，需要用户根据 `info` 信息进行辅助判断。 + +另外当上游 PD 长时间故障后，API 查询会直接返回类似如上的错误，无法提供进一步的判断信息。 From 24d2f8ed9b6bd15a6e3f9503509e04224a1ac7b0 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Fri, 15 Dec 2023 16:53:13 +0800 Subject: [PATCH 02/13] fix --- ticdc/ticdc-open-api-v2.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index ccdaa296dfe3..158068f114f7 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1082,7 +1082,13 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced "now_ts": "2023-11-30 15:26:31", "info": "The data syncing is not finished, please wait" } +``` + +示例2 展示的是并未完成同步任务时返回的查询结果，我们可以结合 `synced` 和 `info` 字段确认数据目前还未完成同步，需要继续等待。 + +示例3 +```json { "synced":false, "sink_checkpoint_ts":"2023-12-13 11:45:13", @@ -1091,14 +1097,17 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced "now_ts":"2023-12-13 11:47:24", "info":"Please check whether pd is health and tikv region is all available. If pd is not health or tikv region is not available, the data syncing is finished. Otherwise the data syncing is not finished, please wait" } +``` +因为本接口支持在上游集群发生灾害的时候进行查询判断，因此在部分情况下，我们无法直接判定 TiCDC 目前数据同步是否完成，而需要用户根据 `info` 信息以及目前上游集群的状态进行判断。在这个示例中 `sink_checkpoint_ts` 和 `now_ts` 具有一些时间上的差距，但我们不知道上游集群的状态，所以不能判定是 TiCDC 还在追数据，所以 `checkpoint-ts` 落后, 还是 pd 或者 tikv 出现了故障导致了 `checkpoint-ts` 没有正常推进。因此我们需要用户根据集群状态来进行辅助判断。 + +示例4 + +```json { "error_msg": "[CDC:ErrPDEtcdAPIError]etcd api call error: context deadline exceeded", "error_code": "CDC:ErrPDEtcdAPIError" } ``` -该示例展示的是并未严格的完成同步任务时返回的查询结果，我们可以结合 `synced` 和 `info` 字段确认数据目前同步的状态。 -因为该接口支持在上游集群发生灾害的时候进行查询判断，所以在部分情况下，需要用户根据 `info` 信息进行辅助判断。 - -另外当上游 PD 长时间故障后，API 查询会直接返回类似如上的错误，无法提供进一步的判断信息。 +当上游集群的 PD 长时间故障后，API 查询会直接返回类似如上的错误，无法提供进一步的判断信息。而因为 PD 故障本身会影响 TiCDC 的数据推进，因此用户可以认为 TiCDC 已经尽可能完成数据同步。 \ No newline at end of file From 0adb571d41c9a935d44a47e2fd1ab18eee1eac55 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Mon, 18 Dec 2023 10:48:28 +0800 Subject: [PATCH 03/13] fix --- ticdc/ticdc-open-api-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 158068f114f7..de7899822992 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1095,7 +1095,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced "puller_resolved_ts":"2023-12-13 11:45:13", "last_synced_ts":"2023-12-13 11:45:07", "now_ts":"2023-12-13 11:47:24", - "info":"Please check whether pd is health and tikv region is all available. If pd is not health or tikv region is not available, the data syncing is finished. Otherwise the data syncing is not finished, please wait" + "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. Otherwise the data syncing is not finished, please wait" } ``` From abbc9c91c385032b82b46fec4bede599ee552883 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Mon, 18 Dec 2023 10:53:50 +0800 Subject: [PATCH 04/13] update --- ticdc/ticdc-open-api-v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index de7899822992..23d7b2dcffb7 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1094,8 +1094,8 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced "sink_checkpoint_ts":"2023-12-13 11:45:13", "puller_resolved_ts":"2023-12-13 11:45:13", "last_synced_ts":"2023-12-13 11:45:07", - "now_ts":"2023-12-13 11:47:24", - "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. Otherwise the data syncing is not finished, please wait" + "now_ts":"2023-12-13 11:50:24", + "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. Because in this case, the resolvedTs will not advance anymore, thus we only need to care whether last_synced_ts is more than 300 secs from the current time. Otherwise the data syncing is not finished, please wait" } ``` From b4b46940518eedb54b882fffeea9ba7312b4827d Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Mon, 18 Dec 2023 12:12:59 +0800 Subject: [PATCH 05/13] update info --- ticdc/ticdc-open-api-v2.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 23d7b2dcffb7..1256281a8621 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1054,10 +1054,10 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced ```json { "synced": true, - "sink_checkpoint_ts": "2023-11-30 15:14:11", - "puller_resolved_ts": "2023-11-30 15:14:09", - "last_synced_ts": "2023-11-30 15:08:35", - "now_ts": "2023-11-30 15:14:11", + "sink_checkpoint_ts": "2023-11-30 15:14:11.015", + "puller_resolved_ts": "2023-11-30 15:14:12.215", + "last_synced_ts": "2023-11-30 15:08:35.510", + "now_ts": "2023-11-30 15:14:11.511", "info": "Data syncing is finished" } ``` @@ -1076,10 +1076,10 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced ```json { "synced": false, - "sink_checkpoint_ts": "2023-11-30 15:26:31", - "puller_resolved_ts": "2023-11-30 15:26:23", - "last_synced_ts": "2023-11-30 15:24:30", - "now_ts": "2023-11-30 15:26:31", + "sink_checkpoint_ts": "2023-11-30 15:26:31.519", + "puller_resolved_ts": "2023-11-30 15:26:23.525", + "last_synced_ts": "2023-11-30 15:24:30.115", + "now_ts": "2023-11-30 15:26:31.511", "info": "The data syncing is not finished, please wait" } ``` @@ -1091,10 +1091,10 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced ```json { "synced":false, - "sink_checkpoint_ts":"2023-12-13 11:45:13", - "puller_resolved_ts":"2023-12-13 11:45:13", - "last_synced_ts":"2023-12-13 11:45:07", - "now_ts":"2023-12-13 11:50:24", + "sink_checkpoint_ts":"2023-12-13 11:45:13.515", + "puller_resolved_ts":"2023-12-13 11:45:13.525", + "last_synced_ts":"2023-12-13 11:45:07.575", + "now_ts":"2023-12-13 11:50:24.875", "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. Because in this case, the resolvedTs will not advance anymore, thus we only need to care whether last_synced_ts is more than 300 secs from the current time. Otherwise the data syncing is not finished, please wait" } ``` From a005e39f082986982cca1669185d21aa08bde900 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Tue, 19 Dec 2023 14:34:57 +0800 Subject: [PATCH 06/13] update --- ticdc/ticdc-open-api-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 1256281a8621..61aac1002105 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1095,7 +1095,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced "puller_resolved_ts":"2023-12-13 11:45:13.525", "last_synced_ts":"2023-12-13 11:45:07.575", "now_ts":"2023-12-13 11:50:24.875", - "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. Because in this case, the resolvedTs will not advance anymore, thus we only need to care whether last_synced_ts is more than 300 secs from the current time. Otherwise the data syncing is not finished, please wait" + "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. When pd is offline means that pd is not healthy. For tikv region, you can check the grafana info in 'TiKV-Details-Resolved-Ts-Max Leader Resolved TS gap'. If the gap is a large value, such as a few minutes, it means some regions in tikv are unavailable. Otherwise the data syncing is not finished, please wait" } ``` From 69b35d523c33069dbda9ea7e4b9091092a954e6b Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Tue, 19 Dec 2023 14:35:25 +0800 Subject: [PATCH 07/13] Update ticdc/ticdc-open-api-v2.md Co-authored-by: Flowyi --- ticdc/ticdc-open-api-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 61aac1002105..45fc0cd102b2 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1099,7 +1099,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced } ``` -因为本接口支持在上游集群发生灾害的时候进行查询判断，因此在部分情况下，我们无法直接判定 TiCDC 目前数据同步是否完成，而需要用户根据 `info` 信息以及目前上游集群的状态进行判断。在这个示例中 `sink_checkpoint_ts` 和 `now_ts` 具有一些时间上的差距，但我们不知道上游集群的状态，所以不能判定是 TiCDC 还在追数据，所以 `checkpoint-ts` 落后, 还是 pd 或者 tikv 出现了故障导致了 `checkpoint-ts` 没有正常推进。因此我们需要用户根据集群状态来进行辅助判断。 +因为本接口支持在上游集群发生灾害的时候进行查询判断，因此在部分情况下，我们无法直接判定 TiCDC 目前数据同步是否完成，而需要用户根据 `info` 信息以及目前上游集群的状态进行判断。在这个示例中 `sink_checkpoint_ts` 和 `now_ts` 具有一些时间上的差距，但我们不知道上游集群的状态，所以不能判定是 TiCDC 还在追数据导致 `checkpoint-ts` 落后, 还是 pd 或者 tikv 出现了故障导致了 `checkpoint-ts` 没有正常推进。因此我们需要用户根据集群状态来进行辅助判断。 示例4 From 74fc02d07cd9d1874bd9c4581d76d2ee76c4f7d0 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Mon, 25 Dec 2023 09:57:46 +0800 Subject: [PATCH 08/13] Apply suggestions from code review Co-authored-by: Grace Cai --- ticdc/ticdc-open-api-v2.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 45fc0cd102b2..f5fb74512ae1 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -1025,9 +1025,9 @@ curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2 如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。 -## 查询特定同步任务同步是否完成 +## 查询特定同步任务是否完成 -该接口是一个同步接口，请求成功后会返回指定的同步任务(changefeed)的同步完成情况，包括是否同步完成，以及一些更详细的信息。 +该接口是一个同步接口，请求成功后会返回指定同步任务 (changefeed) 的同步完成情况，包括是否同步完成，以及一些更详细的信息。 ### 请求 URI @@ -1049,7 +1049,7 @@ curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2 curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced ``` -示例1 +**示例 1：** ```json { @@ -1064,14 +1064,14 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced 以上返回的信息的说明如下： -- `synced`：该同步任务是否已经彻底同步完成了，true 则表示一定完成了同步任务，false 则表示并不一定完成了同步任务，具体需要结合 "info" 字段描述以及其他字段进行判断。 -- `sink_checkpoint_ts`: sink 模块的 checkpoint-ts 值，时间为 PD 时间。 -- `puller_resolved_ts`: puller 模块的 resolved-ts 值，时间为 PD 时间。 -- `last_synced_ts`: ticdc 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 +- `synced`：该同步任务是否已完成。`true` 表示已完成；`false` 表示不一定完成，具体状态需要结合 `info` 字段以及其他字段进行判断。 +- `sink_checkpoint_ts`：sink 模块的 checkpoint-ts 值，时间为 PD 时间。 +- `puller_resolved_ts`：puller 模块的 resolved-ts 值，时间为 PD 时间。 +- `last_synced_ts`：TiCDC 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 - `now_ts`: 当前的 PD 时间 -- `info`: 一些帮助判断的信息，主要在 synced 为 false 时候使用。 +- `info`: 一些帮助判断同步状态的信息，特别是在 `synced` 为 `false` 时可以为你提供参考。 -示例2 +**示例 2：** ```json { @@ -1084,9 +1084,9 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced } ``` -示例2 展示的是并未完成同步任务时返回的查询结果，我们可以结合 `synced` 和 `info` 字段确认数据目前还未完成同步，需要继续等待。 +此示例展示了当未完成同步任务时该接口返回的查询结果。你可以结合 `synced` 和 `info` 字段判断出数据目前还未完成同步，需要继续等待。 -示例3 +**示例 3：** ```json { @@ -1095,13 +1095,15 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced "puller_resolved_ts":"2023-12-13 11:45:13.525", "last_synced_ts":"2023-12-13 11:45:07.575", "now_ts":"2023-12-13 11:50:24.875", - "info":"Please check whether pd is healthy and tikv region is all available. If pd is not healthy or tikv region is not available, the data syncing is finished. When pd is offline means that pd is not healthy. For tikv region, you can check the grafana info in 'TiKV-Details-Resolved-Ts-Max Leader Resolved TS gap'. If the gap is a large value, such as a few minutes, it means some regions in tikv are unavailable. Otherwise the data syncing is not finished, please wait" + "info":"Please check whether PD is online and TiKV Regions are all available. If PD is offline or some TiKV regions are not available, it means that the data syncing process is complete. To check whether TiKV regions are all available, you can view 'TiKV-Details' > 'Resolved-Ts' > 'Max Leader Resolved TS gap' on Grafana. If the gap is large, such as a few minutes, it means that some regions in TiKV are unavailable. Otherwise, if the gap is small and PD is online, it means the data syncing is incomplete, so please wait" } ``` -因为本接口支持在上游集群发生灾害的时候进行查询判断，因此在部分情况下，我们无法直接判定 TiCDC 目前数据同步是否完成，而需要用户根据 `info` 信息以及目前上游集群的状态进行判断。在这个示例中 `sink_checkpoint_ts` 和 `now_ts` 具有一些时间上的差距，但我们不知道上游集群的状态，所以不能判定是 TiCDC 还在追数据导致 `checkpoint-ts` 落后, 还是 pd 或者 tikv 出现了故障导致了 `checkpoint-ts` 没有正常推进。因此我们需要用户根据集群状态来进行辅助判断。 +本接口支持在上游集群发生灾害时对同步状态进行查询判断。在部分情况下，你可能无法直接判定 TiCDC 目前的数据同步任务是否完成。此时，你可以查询该接口，并结合返回结果中的 `info` 字段以及目前上游集群的状态进行判断。 -示例4 +在此示例中，`sink_checkpoint_ts` 在时间上落后于 `now_ts`，这可能是因为 TiCDC 还在追数据导致的，也可能是由于 PD 或者 TiKV 出现了故障导致的。如果这是 TiCDC 还在追数据导致的，说明同步任务尚未完成。如果这是由于 PD 或者 TiKV 出现了故障导致的，说明同步任务已经完成。因此，你需要参考 `info` 中的信息对集群状态进行辅助判断。 + +**示例 4：** ```json { @@ -1110,4 +1112,4 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced } ``` -当上游集群的 PD 长时间故障后，API 查询会直接返回类似如上的错误，无法提供进一步的判断信息。而因为 PD 故障本身会影响 TiCDC 的数据推进，因此用户可以认为 TiCDC 已经尽可能完成数据同步。 \ No newline at end of file +当上游集群的 PD 长时间故障后，查询该 API 接口会返回类似如上的错误，无法提供进一步的判断信息。因为 PD 故障本身会影响 TiCDC 的数据同步，当遇到该错误时，你可以认为 TiCDC 已经尽可能完成数据同步，但下游集群仍然可能存在因 PD 故障导致的数据丢失。 \ No newline at end of file From cdd9d15864a0ff553be29987a20f4deff43fd953 Mon Sep 17 00:00:00 2001 From: hongyunyan <649330952@qq.com> Date: Mon, 25 Dec 2023 10:32:26 +0800 Subject: [PATCH 09/13] update --- ticdc/ticdc-open-api-v2.md | 180 ++++++++++++++++++------------------- 1 file changed, 90 insertions(+), 90 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index f5fb74512ae1..0fad77e948a8 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -808,6 +808,95 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeeds/test1 响应的 JSON 格式以及字段含义与[创建同步任务](#创建同步任务)中的响应参数相同，此处不再赘述。 +## 查询特定同步任务是否完成 + +该接口是一个同步接口，请求成功后会返回指定同步任务 (changefeed) 的同步完成情况，包括是否同步完成，以及一些更详细的信息。 + +### 请求 URI + +`GET /api/v2/changefeed/{changefeed_id}/synced` + +### 参数说明 + +#### 路径参数 + +| 参数名 | 说明 | +|:----------------|:----------------------------| +| `changefeed_id` | 需要查询的同步任务 (changefeed) 的 ID | + +### 使用样例 + +以下请求会查询 ID 为 `test1` 的同步任务的同步完成状态。 + +```shell +curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced +``` + +**示例 1：** + +```json +{ + "synced": true, + "sink_checkpoint_ts": "2023-11-30 15:14:11.015", + "puller_resolved_ts": "2023-11-30 15:14:12.215", + "last_synced_ts": "2023-11-30 15:08:35.510", + "now_ts": "2023-11-30 15:14:11.511", + "info": "Data syncing is finished" +} +``` + +以上返回的信息的说明如下： + +- `synced`：该同步任务是否已完成。`true` 表示已完成；`false` 表示不一定完成，具体状态需要结合 `info` 字段以及其他字段进行判断。 +- `sink_checkpoint_ts`：sink 模块的 checkpoint-ts 值，时间为 PD 时间。 +- `puller_resolved_ts`：puller 模块的 resolved-ts 值，时间为 PD 时间。 +- `last_synced_ts`：TiCDC 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 +- `now_ts`: 当前的 PD 时间 +- `info`: 一些帮助判断同步状态的信息，特别是在 `synced` 为 `false` 时可以为你提供参考。 + +**示例 2：** + +```json +{ + "synced": false, + "sink_checkpoint_ts": "2023-11-30 15:26:31.519", + "puller_resolved_ts": "2023-11-30 15:26:23.525", + "last_synced_ts": "2023-11-30 15:24:30.115", + "now_ts": "2023-11-30 15:26:31.511", + "info": "The data syncing is not finished, please wait" +} +``` + +此示例展示了当未完成同步任务时该接口返回的查询结果。你可以结合 `synced` 和 `info` 字段判断出数据目前还未完成同步，需要继续等待。 + +**示例 3：** + +```json +{ + "synced":false, + "sink_checkpoint_ts":"2023-12-13 11:45:13.515", + "puller_resolved_ts":"2023-12-13 11:45:13.525", + "last_synced_ts":"2023-12-13 11:45:07.575", + "now_ts":"2023-12-13 11:50:24.875", + "info":"Please check whether PD is online and TiKV Regions are all available. If PD is offline or some TiKV regions are not available, it means that the data syncing process is complete. To check whether TiKV regions are all available, you can view 'TiKV-Details' > 'Resolved-Ts' > 'Max Leader Resolved TS gap' on Grafana. If the gap is large, such as a few minutes, it means that some regions in TiKV are unavailable. Otherwise, if the gap is small and PD is online, it means the data syncing is incomplete, so please wait" +} +``` + +本接口支持在上游集群发生灾害时对同步状态进行查询判断。在部分情况下，你可能无法直接判定 TiCDC 目前的数据同步任务是否完成。此时，你可以查询该接口，并结合返回结果中的 `info` 字段以及目前上游集群的状态进行判断。 + +在此示例中，`sink_checkpoint_ts` 在时间上落后于 `now_ts`，这可能是因为 TiCDC 还在追数据导致的，也可能是由于 PD 或者 TiKV 出现了故障导致的。如果这是 TiCDC 还在追数据导致的，说明同步任务尚未完成。如果这是由于 PD 或者 TiKV 出现了故障导致的，说明同步任务已经完成。因此，你需要参考 `info` 中的信息对集群状态进行辅助判断。 + +**示例 4：** + +```json +{ + "error_msg": "[CDC:ErrPDEtcdAPIError]etcd api call error: context deadline exceeded", + "error_code": "CDC:ErrPDEtcdAPIError" +} +``` + +当上游集群的 PD 长时间故障后，查询该 API 接口会返回类似如上的错误，无法提供进一步的判断信息。因为 PD 故障本身会影响 TiCDC 的数据同步，当遇到该错误时，你可以认为 TiCDC 已经尽可能完成数据同步，但下游集群仍然可能存在因 PD 故障导致的数据丢失。 + ## 暂停同步任务 该接口暂停一个同步任务，请求成功会返回 `200 OK`。该返回结果表示服务器收到了执行命令指示，并不代表命令被成功执行。 @@ -1023,93 +1112,4 @@ curl -X POST http://127.0.0.1:8300/api/v2/owner/resign curl -X POST -H "'Content-type':'application/json'" http://127.0.0.1:8300/api/v2/log -d '{"log_level":"debug"}' ``` -如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。 - -## 查询特定同步任务是否完成 - -该接口是一个同步接口，请求成功后会返回指定同步任务 (changefeed) 的同步完成情况，包括是否同步完成，以及一些更详细的信息。 - -### 请求 URI - -`GET /api/v2/changefeed/{changefeed_id}/synced` - -### 参数说明 - -#### 路径参数 - -| 参数名 | 说明 | -|:----------------|:----------------------------| -| `changefeed_id` | 需要查询的同步任务 (changefeed) 的 ID | - -### 使用样例 - -以下请求会查询 ID 为 `test1` 的同步任务的同步完成状态。 - -```shell -curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced -``` - -**示例 1：** - -```json -{ - "synced": true, - "sink_checkpoint_ts": "2023-11-30 15:14:11.015", - "puller_resolved_ts": "2023-11-30 15:14:12.215", - "last_synced_ts": "2023-11-30 15:08:35.510", - "now_ts": "2023-11-30 15:14:11.511", - "info": "Data syncing is finished" -} -``` - -以上返回的信息的说明如下： - -- `synced`：该同步任务是否已完成。`true` 表示已完成；`false` 表示不一定完成，具体状态需要结合 `info` 字段以及其他字段进行判断。 -- `sink_checkpoint_ts`：sink 模块的 checkpoint-ts 值，时间为 PD 时间。 -- `puller_resolved_ts`：puller 模块的 resolved-ts 值，时间为 PD 时间。 -- `last_synced_ts`：TiCDC 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 -- `now_ts`: 当前的 PD 时间 -- `info`: 一些帮助判断同步状态的信息，特别是在 `synced` 为 `false` 时可以为你提供参考。 - -**示例 2：** - -```json -{ - "synced": false, - "sink_checkpoint_ts": "2023-11-30 15:26:31.519", - "puller_resolved_ts": "2023-11-30 15:26:23.525", - "last_synced_ts": "2023-11-30 15:24:30.115", - "now_ts": "2023-11-30 15:26:31.511", - "info": "The data syncing is not finished, please wait" -} -``` - -此示例展示了当未完成同步任务时该接口返回的查询结果。你可以结合 `synced` 和 `info` 字段判断出数据目前还未完成同步，需要继续等待。 - -**示例 3：** - -```json -{ - "synced":false, - "sink_checkpoint_ts":"2023-12-13 11:45:13.515", - "puller_resolved_ts":"2023-12-13 11:45:13.525", - "last_synced_ts":"2023-12-13 11:45:07.575", - "now_ts":"2023-12-13 11:50:24.875", - "info":"Please check whether PD is online and TiKV Regions are all available. If PD is offline or some TiKV regions are not available, it means that the data syncing process is complete. To check whether TiKV regions are all available, you can view 'TiKV-Details' > 'Resolved-Ts' > 'Max Leader Resolved TS gap' on Grafana. If the gap is large, such as a few minutes, it means that some regions in TiKV are unavailable. Otherwise, if the gap is small and PD is online, it means the data syncing is incomplete, so please wait" -} -``` - -本接口支持在上游集群发生灾害时对同步状态进行查询判断。在部分情况下，你可能无法直接判定 TiCDC 目前的数据同步任务是否完成。此时，你可以查询该接口，并结合返回结果中的 `info` 字段以及目前上游集群的状态进行判断。 - -在此示例中，`sink_checkpoint_ts` 在时间上落后于 `now_ts`，这可能是因为 TiCDC 还在追数据导致的，也可能是由于 PD 或者 TiKV 出现了故障导致的。如果这是 TiCDC 还在追数据导致的，说明同步任务尚未完成。如果这是由于 PD 或者 TiKV 出现了故障导致的，说明同步任务已经完成。因此，你需要参考 `info` 中的信息对集群状态进行辅助判断。 - -**示例 4：** - -```json -{ - "error_msg": "[CDC:ErrPDEtcdAPIError]etcd api call error: context deadline exceeded", - "error_code": "CDC:ErrPDEtcdAPIError" -} -``` - -当上游集群的 PD 长时间故障后，查询该 API 接口会返回类似如上的错误，无法提供进一步的判断信息。因为 PD 故障本身会影响 TiCDC 的数据同步，当遇到该错误时，你可以认为 TiCDC 已经尽可能完成数据同步，但下游集群仍然可能存在因 PD 故障导致的数据丢失。 \ No newline at end of file +如果请求成功，则返回 `200 OK`。如果请求失败，则返回错误信息和错误码。 \ No newline at end of file From 1fc3a8b7ece81a99c89b30eef2afcbff7f6c97a2 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 25 Dec 2023 10:40:31 +0800 Subject: [PATCH 10/13] fix format issues --- ticdc/ticdc-open-api-v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 0fad77e948a8..66bb82db896e 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -851,8 +851,8 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced - `sink_checkpoint_ts`：sink 模块的 checkpoint-ts 值，时间为 PD 时间。 - `puller_resolved_ts`：puller 模块的 resolved-ts 值，时间为 PD 时间。 - `last_synced_ts`：TiCDC 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 -- `now_ts`: 当前的 PD 时间 -- `info`: 一些帮助判断同步状态的信息，特别是在 `synced` 为 `false` 时可以为你提供参考。 +- `now_ts`：当前的 PD 时间 +- `info`：一些帮助判断同步状态的信息，特别是在 `synced` 为 `false` 时可以为你提供参考。 **示例 2：** From d7b9737cc63468e4326137919bfd9b9bdd11e7dc Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 26 Dec 2023 21:42:40 +0800 Subject: [PATCH 11/13] Apply suggestions from code review Co-authored-by: Aolin --- ticdc/ticdc-open-api-v2.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 66bb82db896e..50f2d8c1e096 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -832,7 +832,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeeds/test1 curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced ``` -**示例 1：** +**示例 1：同步已完成** ```json { @@ -851,10 +851,10 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced - `sink_checkpoint_ts`：sink 模块的 checkpoint-ts 值，时间为 PD 时间。 - `puller_resolved_ts`：puller 模块的 resolved-ts 值，时间为 PD 时间。 - `last_synced_ts`：TiCDC 处理的最新一条数据的 commit-ts 值，时间为 PD 时间。 -- `now_ts`：当前的 PD 时间 +- `now_ts`：当前的 PD 时间。 - `info`：一些帮助判断同步状态的信息，特别是在 `synced` 为 `false` 时可以为你提供参考。 -**示例 2：** +**示例 2：同步未完成** ```json { @@ -869,7 +869,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced 此示例展示了当未完成同步任务时该接口返回的查询结果。你可以结合 `synced` 和 `info` 字段判断出数据目前还未完成同步，需要继续等待。 -**示例 3：** +**示例 3：同步状态需要结合上游集群状态判断** ```json { @@ -884,9 +884,9 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced 本接口支持在上游集群发生灾害时对同步状态进行查询判断。在部分情况下，你可能无法直接判定 TiCDC 目前的数据同步任务是否完成。此时，你可以查询该接口，并结合返回结果中的 `info` 字段以及目前上游集群的状态进行判断。 -在此示例中，`sink_checkpoint_ts` 在时间上落后于 `now_ts`，这可能是因为 TiCDC 还在追数据导致的，也可能是由于 PD 或者 TiKV 出现了故障导致的。如果这是 TiCDC 还在追数据导致的，说明同步任务尚未完成。如果这是由于 PD 或者 TiKV 出现了故障导致的，说明同步任务已经完成。因此，你需要参考 `info` 中的信息对集群状态进行辅助判断。 +在此示例中，`sink_checkpoint_ts` 在时间上落后于 `now_ts`，这可能是因为 TiCDC 还在追数据，也可能是由于 PD 或者 TiKV 出现了故障。如果这是 TiCDC 还在追数据导致的，说明同步任务尚未完成。如果这是由于 PD 或者 TiKV 出现了故障导致的，说明同步任务已经完成。因此，你需要参考 `info` 中的信息对集群状态进行辅助判断。 -**示例 4：** +**示例 4：查询报错** ```json { @@ -895,7 +895,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced } ``` -当上游集群的 PD 长时间故障后，查询该 API 接口会返回类似如上的错误，无法提供进一步的判断信息。因为 PD 故障本身会影响 TiCDC 的数据同步，当遇到该错误时，你可以认为 TiCDC 已经尽可能完成数据同步，但下游集群仍然可能存在因 PD 故障导致的数据丢失。 +在上游集群的 PD 长时间故障后，查询该 API 接口时会返回类似如上的错误，无法提供进一步的判断信息。因为 PD 故障会直接影响 TiCDC 的数据同步，当遇到这类错误时，你可以认为 TiCDC 已经尽可能完成数据同步，但下游集群仍然可能存在因 PD 故障导致的数据丢失。 ## 暂停同步任务 From 05f5b8767664bc67bc9f28016f8de51f49c28188 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 26 Dec 2023 21:43:50 +0800 Subject: [PATCH 12/13] Update ticdc/ticdc-open-api-v2.md Co-authored-by: Aolin --- ticdc/ticdc-open-api-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index 50f2d8c1e096..d4e0124b0eea 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -882,7 +882,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced } ``` -本接口支持在上游集群发生灾害时对同步状态进行查询判断。在部分情况下，你可能无法直接判定 TiCDC 目前的数据同步任务是否完成。此时，你可以查询该接口，并结合返回结果中的 `info` 字段以及目前上游集群的状态进行判断。 +本接口支持在上游集群遇到灾害时对同步状态进行查询判断。在部分情况下，你可能无法直接判定 TiCDC 目前的数据同步任务是否完成。此时，你可以查询该接口，并结合返回结果中的 `info` 字段以及目前上游集群的状态进行判断。 在此示例中，`sink_checkpoint_ts` 在时间上落后于 `now_ts`，这可能是因为 TiCDC 还在追数据，也可能是由于 PD 或者 TiKV 出现了故障。如果这是 TiCDC 还在追数据导致的，说明同步任务尚未完成。如果这是由于 PD 或者 TiKV 出现了故障导致的，说明同步任务已经完成。因此，你需要参考 `info` 中的信息对集群状态进行辅助判断。 From b99e500f3124acad788b554f23939f3dc49cd6eb Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 27 Dec 2023 22:46:54 +0800 Subject: [PATCH 13/13] wording updates --- ticdc/ticdc-open-api-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ticdc/ticdc-open-api-v2.md b/ticdc/ticdc-open-api-v2.md index d4e0124b0eea..2b1b0ca84e00 100644 --- a/ticdc/ticdc-open-api-v2.md +++ b/ticdc/ticdc-open-api-v2.md @@ -869,7 +869,7 @@ curl -X GET http://127.0.0.1:8300/api/v2/changefeed/test1/synced 此示例展示了当未完成同步任务时该接口返回的查询结果。你可以结合 `synced` 和 `info` 字段判断出数据目前还未完成同步，需要继续等待。 -**示例 3：同步状态需要结合上游集群状态判断** +**示例 3：同步状态需要进一步判断** ```json {