reference/tidb-binlog: add docs about relay log

dev/TOC.md

@@ -281,6 +281,7 @@
     - [监控告警](/dev/reference/tidb-binlog/monitor.md)
     - [增量恢复](/dev/reference/tidb-binlog/reparo.md)
     - [Kafka 自定义开发](/dev/reference/tidb-binlog/binlog-slave-client.md)
+    - [TiDB Binlog Relay Log](/dev/reference/tidb-binlog/relay-log.md)
     - [术语表](/dev/reference/tidb-binlog/glossary.md)
     + 故障诊断
       - [故障诊断](/dev/reference/tidb-binlog/troubleshoot/binlog.md)

dev/reference/tidb-binlog/deploy.md

@@ -539,6 +539,13 @@ Drainer="192.168.0.13"
 
         # replicate-do-db = ["~^b.*","s1"]
 
+        # [syncer.relay]
+        # 保存 relay log 的目录，空值表示不开启。
+        # 只有下游是 TiDB 或 MySQL 时该配置才生效。
+        # log-dir = ""
+        # 每个文件的大小上限
+        # max-file-size = 10485760
+
         # [[syncer.replicate-do-table]]
         # db-name ="test"
         # tbl-name = "log"

dev/reference/tidb-binlog/monitor.md

@@ -1,7 +1,7 @@
 ---
 title: TiDB Binlog 集群监控
 category: reference
-aliases: ['/docs-cn/dev/how-to/monitor/tidb-binlog/','/docs-cn/dev/reference/tools/tidb-binlog/monitor/']
+aliases: ['/docs-cn/dev/how-to/monitor/tidb-binlog-monitor/','/docs-cn/dev/reference/tools/tidb-binlog/monitor/','/docs-cn/dev/how-to/monitor/tidb-binlog/']
 ---
 
 # TiDB Binlog 集群监控

dev/reference/tidb-binlog/overview.md

@@ -42,6 +42,7 @@ TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl
 * TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。
 * Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。
 * Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。
+* Drainer 支持 [relay log](/dev/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。
 
 ## 注意事项
 
@@ -56,4 +57,4 @@ TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl
     - 如果 TiDB 版本 < 2.1.9，则 `db-type="pb"`。
     - 如果 TiDB 版本 > = 2.1.9，则 `db-type="file"` 或 `db-type="pb"`。
 
-* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/dev/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。
+* 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](/dev/reference/tools/sync-diff-inspector/overview.md) 进行数据校验。

dev/reference/tidb-binlog/relay-log.md

@@ -0,0 +1,55 @@
+---
+title: TiDB Binlog Relay Log
+category: reference
+aliases: ['/docs-cn/dev/reference/tools/tidb-binlog/relay-log/']
+---
+
+# TiDB Binlog Relay Log
+
+Drainer 同步 binlog 时会拆分上游的事务，并将拆分的事务并发同步到下游。在极端情况下，上游集群不可用并且 Drainer 异常退出后，下游集群（MySQL 或 TiDB）可能处于数据不一致的中间状态。在此场景下，Drainer 借助 relay log 可以确保将下游集群同步到一个一致的状态。
+
+## Drainer 同步时的一致性状态
+
+下游集群达到一致的状态是指：下游集群的数据等同于上游设置了 `tidb_snapshot = ts` 的快照。
+
+checkpoint 状态一致性是指：Drainer checkpoint 通过 `consistent` 保存了同步的一致性状态。Drainer 运行时 `consistent` 为 `false`，Drainer 正常退出后 `consistent` 更新为 `true`。
+
+查询下游 checkpoint 表的示例如下：
+
+```
+mysql> select  * from tidb_binlog.checkpoint;
++---------------------+----------------------------------------------------------------+
+| clusterID           | checkPoint                                                     |
++---------------------+----------------------------------------------------------------+
+| 6791641053252586769 | {"consistent":false,"commitTS":414529105591271429,"ts-map":{}} |
++---------------------+----------------------------------------------------------------+
+```
+
+## 工作原理
+
+Drainer 开启 relay log 后会先将 binlog event 写到磁盘上，然后再同步给下游集群。如果上游集群不可用，Drainer 可以通过读取 relay log 把下游集群恢复到一个一致的状态。
+
+> **注意：**
+>
+> 若同时丢失 relay log 数据，该方法将不可用，不过这是概率极小的事件。此外可以使用 NFS 等网络文件系统来保证 relay log 的数据安全。
+
+### Drainer 从 relay log 消费 binlog 的触发场景
+
+如果 Drainer 启动时无法连接到上游集群的 PD，并且探测到 checkpoint 的 `consistent = false`，此时会尝试读取 relay log，并将下游集群恢复到一致的状态。然后 Drainer 进程将 checkpoint 的 `status` 设置为 `0` 后主动退出。
+
+### Relay log 的清理（GC）机制
+
+Drainer 在运行时，如果确认已经将一个 relay log 文件的全部数据都成功同步到下游了，就会马上删除这个文件，所以 relay log 不会占用过多空间。一个 relay log 文件大小达到 10MB（默认）时就会做切分，数据开始写入新的 relay log 文件。
+
+## 配置
+
+在 Drainer 中添加以下配置来开启 relay log 功能：
+
+{{< copyable "" >}}
+
+```
+[syncer.relay]
+# 保存 relay log 的目录，空值表示不开启。
+# 只有下游是 TiDB 或 MySQL 时该配置才有生效。
+log-dir = "/dir/to/save/log"
+```

v3.0/TOC.md

@@ -278,6 +278,7 @@
     - [监控告警](/v3.0/reference/tidb-binlog/monitor.md)
     - [增量恢复](/v3.0/reference/tidb-binlog/reparo.md)
     - [Kafka 自定义开发](/v3.0/reference/tidb-binlog/binlog-slave-client.md)
+    - [TiDB Binlog Relay Log](/v3.0/reference/tidb-binlog/relay-log.md)
     - [术语表](/v3.0/reference/tidb-binlog/glossary.md)
     + 故障诊断
       - [故障诊断](/v3.0/reference/tidb-binlog/troubleshoot/binlog.md)

v3.0/reference/tidb-binlog/deploy.md

@@ -554,6 +554,13 @@ Drainer="192.168.0.13"
 
         # replicate-do-db = ["~^b.*","s1"]
 
+        # [syncer.relay]
+        # 保存 relay log 的目录，空值表示不开启。
+        # 只有下游是 TiDB 或 MySQL 时该配置才生效。
+        # log-dir = ""
+        # 每个文件的大小上限
+        # max-file-size = 10485760
+
         # [[syncer.replicate-do-table]]
         # db-name ="test"
         # tbl-name = "log"

v3.0/reference/tidb-binlog/monitor.md

@@ -1,7 +1,7 @@
 ---
 title: TiDB Binlog 集群监控
 category: reference
-aliases: ['/docs-cn/tools/binlog/monitor/','/docs-cn/v3.0/how-to/monitor/tidb-binlog/','/docs-cn/v3.0/reference/tools/tidb-binlog/monitor/']
+aliases: ['/docs-cn/v3.0/how-to/monitor/tidb-binlog-monitor/','/docs-cn/v3.0/reference/tools/tidb-binlog/monitor/','/docs-cn/v3.0/how-to/monitor/tidb-binlog/']
 ---
 
 # TiDB Binlog 集群监控

v3.0/reference/tidb-binlog/overview.md

@@ -42,6 +42,7 @@ TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl
 * TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。
 * Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。
 * Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。
+* Drainer 支持 [relay log](/v3.0/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。
 
 ## 注意事项
 

v3.0/reference/tidb-binlog/relay-log.md

@@ -0,0 +1,55 @@
+---
+title: TiDB Binlog Relay Log
+category: reference
+aliases: ['/docs-cn/v3.0/reference/tools/tidb-binlog/relay-log/']
+---
+
+# TiDB Binlog Relay Log
+
+Drainer 同步 binlog 时会拆分上游的事务，并将拆分的事务并发同步到下游。在极端情况下，上游集群不可用并且 Drainer 异常退出后，下游集群（MySQL 或 TiDB）可能处于数据不一致的中间状态。在此场景下，Drainer 借助 relay log 可以确保将下游集群同步到一个一致的状态。
+
+## Drainer 同步时的一致性状态
+
+下游集群达到一致的状态是指：下游集群的数据等同于上游设置了 `tidb_snapshot = ts` 的快照。
+
+checkpoint 状态一致性是指：Drainer checkpoint 通过 `consistent` 保存了同步的一致性状态。Drainer 运行时 `consistent` 为 `false`，Drainer 正常退出后 `consistent` 更新为 `true`。
+
+查询下游 checkpoint 表的示例如下：
+
+```
+mysql> select  * from tidb_binlog.checkpoint;
++---------------------+----------------------------------------------------------------+
+| clusterID           | checkPoint                                                     |
++---------------------+----------------------------------------------------------------+
+| 6791641053252586769 | {"consistent":false,"commitTS":414529105591271429,"ts-map":{}} |
++---------------------+----------------------------------------------------------------+
+```
+
+## 工作原理
+
+Drainer 开启 relay log 后会先将 binlog event 写到磁盘上，然后再同步给下游集群。如果上游集群不可用，Drainer 可以通过读取 relay log 把下游集群恢复到一个一致的状态。
+
+> **注意：**
+>
+> 若同时丢失 relay log 数据，该方法将不可用，不过这是概率极小的事件。此外可以使用 NFS 等网络文件系统来保证 relay log 的数据安全。
+
+### Drainer 从 relay log 消费 binlog 的触发场景
+
+如果 Drainer 启动时无法连接到上游集群的 PD，并且探测到 checkpoint 的 `consistent = false`，此时会尝试读取 relay log，并将下游集群恢复到一致的状态。然后 Drainer 进程将 checkpoint 的 `status` 设置为 `0` 后主动退出。
+
+### Relay log 的清理（GC）机制
+
+Drainer 在运行时，如果确认已经将一个 relay log 文件的全部数据都成功同步到下游了，就会马上删除这个文件，所以 relay log 不会占用过多空间。一个 relay log 文件大小达到 10MB（默认）时就会做切分，数据开始写入新的 relay log 文件。
+
+## 配置
+
+在 Drainer 中添加以下配置来开启 relay log 功能：
+
+{{< copyable "" >}}
+
+```
+[syncer.relay]
+# 保存 relay log 的目录，空值表示不开启。
+# 只有下游是 TiDB 或 MySQL 时该配置才有生效。
+log-dir = "/dir/to/save/log"
+```

v3.1/TOC.md

@@ -282,6 +282,7 @@
     - [监控告警](/v3.1/reference/tidb-binlog/monitor.md)
     - [增量恢复](/v3.1/reference/tidb-binlog/reparo.md)
     - [Kafka 自定义开发](/v3.1/reference/tidb-binlog/binlog-slave-client.md)
+    - [TiDB Binlog Relay Log](/v3.1/reference/tidb-binlog/relay-log.md)
     - [术语表](/v3.1/reference/tidb-binlog/glossary.md)
     + 故障诊断
       - [故障诊断](/v3.1/reference/tidb-binlog/troubleshoot/binlog.md)

v3.1/reference/tidb-binlog/deploy.md

@@ -537,6 +537,13 @@ Drainer="192.168.0.13"
 
         # replicate-do-db = ["~^b.*","s1"]
 
+        # [syncer.relay]
+        # 保存 relay log 的目录，空值表示不开启。
+        # 只有下游是 TiDB 或 MySQL 时该配置才生效。
+        # log-dir = ""
+        # 每个文件的大小上限
+        # max-file-size = 10485760
+
         # [[syncer.replicate-do-table]]
         # db-name ="test"
         # tbl-name = "log"

v3.1/reference/tidb-binlog/overview.md

@@ -41,6 +41,7 @@ TiDB Binlog 集群主要分为 Pump 和 Drainer 两个组件，以及 binlogctl
 * TiDB 通过内置的 Pump Client 将 Binlog 分发到各个 Pump。
 * Pump 负责存储 Binlog，并将 Binlog 按顺序提供给 Drainer。
 * Drainer 负责读取各个 Pump 的 Binlog，归并排序后发送到下游。
+* Drainer 支持 [relay log](/v3.1/reference/tidb-binlog/relay-log.md) 功能，通过 relay log 保证下游集群的一致性状态。
 
 ## 注意事项
 

v3.1/reference/tidb-binlog/relay-log.md

@@ -0,0 +1,55 @@
+---
+title: TiDB Binlog Relay Log
+category: reference
+aliases: ['/docs-cn/v3.1/reference/tools/tidb-binlog/relay-log/']
+---
+
+# TiDB Binlog Relay Log
+
+Drainer 同步 binlog 时会拆分上游的事务，并将拆分的事务并发同步到下游。在极端情况下，上游集群不可用并且 Drainer 异常退出后，下游集群（MySQL 或 TiDB）可能处于数据不一致的中间状态。在此场景下，Drainer 借助 relay log 可以确保将下游集群同步到一个一致的状态。
+
+## Drainer 同步时的一致性状态
+
+下游集群达到一致的状态是指：下游集群的数据等同于上游设置了 `tidb_snapshot = ts` 的快照。
+
+checkpoint 状态一致性是指：Drainer checkpoint 通过 `consistent` 保存了同步的一致性状态。Drainer 运行时 `consistent` 为 `false`，Drainer 正常退出后 `consistent` 更新为 `true`。
+
+查询下游 checkpoint 表的示例如下：
+
+```
+mysql> select  * from tidb_binlog.checkpoint;
++---------------------+----------------------------------------------------------------+
+| clusterID           | checkPoint                                                     |
++---------------------+----------------------------------------------------------------+
+| 6791641053252586769 | {"consistent":false,"commitTS":414529105591271429,"ts-map":{}} |
++---------------------+----------------------------------------------------------------+
+```
+
+## 工作原理
+
+Drainer 开启 relay log 后会先将 binlog event 写到磁盘上，然后再同步给下游集群。如果上游集群不可用，Drainer 可以通过读取 relay log 把下游集群恢复到一个一致的状态。
+
+> **注意：**
+>
+> 若同时丢失 relay log 数据，该方法将不可用，不过这是概率极小的事件。此外可以使用 NFS 等网络文件系统来保证 relay log 的数据安全。
+
+### Drainer 从 relay log 消费 binlog 的触发场景
+
+如果 Drainer 启动时无法连接到上游集群的 PD，并且探测到 checkpoint 的 `consistent = false`，此时会尝试读取 relay log，并将下游集群恢复到一致的状态。然后 Drainer 进程将 checkpoint 的 `status` 设置为 `0` 后主动退出。
+
+### Relay log 的清理（GC）机制
+
+Drainer 在运行时，如果确认已经将一个 relay log 文件的全部数据都成功同步到下游了，就会马上删除这个文件，所以 relay log 不会占用过多空间。一个 relay log 文件大小达到 10MB（默认）时就会做切分，数据开始写入新的 relay log 文件。
+
+## 配置
+
+在 Drainer 中添加以下配置来开启 relay log 功能：
+
+{{< copyable "" >}}
+
+```
+[syncer.relay]
+# 保存 relay log 的目录，空值表示不开启。
+# 只有下游是 TiDB 或 MySQL 时该配置才有生效。
+log-dir = "/dir/to/save/log"
+```