Merge remote-tracking branch 'upstream/master' into configure-time-zo…

…ne-update-a-part

mysql-compatibility.md

@@ -48,7 +48,7 @@ aliases: ['/docs-cn/dev/mysql-compatibility/','/docs-cn/dev/reference/mysql-comp
 
 ### 自增 ID
 
-- TiDB 的自增列仅保证唯一，也能保证在单个 TiDB server 中自增，但不保证多个 TiDB server 中自增，不保证自动分配的值的连续性，建议不要将缺省值和自定义值混用，若混用可能会收 `Duplicated Error` 的错误信息。
+- TiDB 的自增列仅保证唯一，也能保证在单个 TiDB server 中自增，但不保证多个 TiDB server 中自增，不保证自动分配的值的连续性，建议不要将缺省值和自定义值混用，若混用可能会收到 `Duplicated Error` 的错误信息。
 
 - TiDB 可通过 `tidb_allow_remove_auto_inc` 系统变量开启或者关闭允许移除列的 `AUTO_INCREMENT` 属性。删除列属性的语法是：`ALTER TABLE MODIFY` 或 `ALTER TABLE CHANGE`。
 

scripts/verify-link-anchors.sh

@@ -7,7 +7,7 @@
 ROOT=$(unset CDPATH && cd $(dirname "${BASH_SOURCE[0]}")/.. && pwd)
 cd $ROOT
 
-npm install -g remark-cli remark-lint breeswish/remark-lint-pingcap-docs-anchor
+npm install -g remark-cli@9.0.0 remark-lint@8.0.0 breeswish/remark-lint-pingcap-docs-anchor
 
 echo "info: checking links anchors under $ROOT directory..."
 

statement-summary-tables.md

@@ -88,9 +88,9 @@ select * from employee where id in (...) and salary between ? and ?;
 
 ## `statements_summary_evicted`
 
-`statements_summary` 表的容量受 `tidb_stmt_summary_max_stmt_count` 配置控制，内部使用 LRU 算法，一旦接收到的 SQL 种类超过了 `tidb_stmt_summary_max_stmt_count`，表中最久未被命中的记录就会被驱逐出表。TiDB 引入了 `statements_summary_evicted` 表，该表记录了各个时段被驱逐的 `SQL` 的具体种数。
+`statements_summary` 表的容量受 `tidb_stmt_summary_max_stmt_count` 配置控制，内部使用 LRU 算法，一旦接收到的 SQL 种类超过了 `tidb_stmt_summary_max_stmt_count`，表中最久未被命中的记录就会被驱逐出表。TiDB 引入了 `statements_summary_evicted` 表，该表记录了各个时段被驱逐 SQL 语句的具体数量。
 
-只有当 `SQL` 被 `statement summary` 表驱逐的时候，`statements_summary_evicted` 表的内容才会更新。`statements_summary_evicted` 表仅记录发生驱逐的时间段。
+只有当 SQL 语句被 `statement summary` 表驱逐的时候，`statements_summary_evicted` 表的内容才会更新。`statements_summary_evicted` 表记录发生驱逐的时间段和被驱逐 SQL 的数量。
 
 ## statement summary 的 cluster 表
 
@@ -121,7 +121,7 @@ set global tidb_stmt_summary_refresh_interval = 1800;
 set global tidb_stmt_summary_history_size = 24;
 ```
 
-以上配置生效后，`statements_summary` 每 30 分钟清空一次。因为 24 * 30 分钟 = 12 小，，所以 `statements_summary_history` 保存最近 12 小时的历史数。`statements_summary_evicted` 保存最近 24 个发生了 evict 的时间段记录；`statements_summary_evicted` 则以 30 分钟为一个记录周期，表容量为 24 个时间段。
+以上配置生效后，`statements_summary` 每 30 分钟清空一次，所以 `statements_summary_history` 保存最近 12 小时的历史数。`statements_summary_evicted` 保存最近 24 个发生了 evict 的时间段记录；`statements_summary_evicted` 则以 30 分钟为一个记录周期，表容量为 24 个时间段。
 
 以上几个系统变量都有 global 和 session 两种作用域，它们的生效方式与其他系统变量不一样：
 
@@ -176,7 +176,7 @@ select * from information_schema.statements_summary_evicted;
 2 row in set (0.001 sec)
 ```
 
-由上可知，对最多 59 种 SQL 发生了 evict，也就是说最好将 statement summary 的容量增大至少 59 条记录。
+由上可知，对最多 59 种 SQL 发生了 evict，也就是说最少应将 statement summary 的容量增大至 59 条记录。
 
 ## 目前的限制
 

system-variables.md

@@ -84,32 +84,32 @@ mysql> SELECT * FROM t1;
 
 ### character_set_client
 
-- 作用域: SESSION | GLOBAL
-- 默认值: `utf8mb4`
+- 作用域：SESSION | GLOBAL
+- 默认值：`utf8mb4`
 - 这个变量表示从客户端发出的数据所用的字符集。有关更多 TiDB 支持的字符集和排序规则，参阅[字符集和排序规则](/character-set-and-collation.md)文档。如果需要更改字符集，建议使用 [`SET NAMES`](/sql-statements/sql-statement-set-names.md) 语句。
 
 ### character_set_connection
 
-- 作用域: SESSION | GLOBAL
-- 默认值: `utf8mb4`
+- 作用域：SESSION | GLOBAL
+- 默认值：`utf8mb4`
 - 若没有为字符串常量指定字符集，该变量表示这些字符串常量所使用的字符集。
 
 ### character_set_database
 
-- 作用域: SESSION | GLOBAL
-- 默认值: `utf8mb4`
+- 作用域：SESSION | GLOBAL
+- 默认值：`utf8mb4`
 - 该变量表示当前默认在用数据库的字符集，**不建议设置该变量**。选择新的默认数据库后，服务器会更改该变量的值。
 
 ### character_set_results
 
-- 作用域: SESSION | GLOBAL
-- 默认值: `utf8mb4`
+- 作用域：SESSION | GLOBAL
+- 默认值：`utf8mb4`
 - 该变量表示数据发送至客户端时所使用的字符集。
 
 ### character_set_server
 
-- 作用域: SESSION | GLOBAL
-- 默认值: `utf8mb4`
+- 作用域：SESSION | GLOBAL
+- 默认值：`utf8mb4`
 - 当 `CREATE SCHEMA` 中没有指定字符集时，该变量表示这些新建的表结构所使用的字符集。
 
 ### `cte_max_recursion_depth`

telemetry.md

@@ -24,6 +24,7 @@ TiDB、TiUP 及 TiDB Dashboard 默认会收集使用情况信息，并将这些
 - 集群的部署情况，包括各个组件所在的硬件信息（CPU、内存、磁盘）、组件版本号、操作系统版本号等
 - 系统的查询请求状态，例如查询请求次数、持续时长等
 - 系统组件的使用情况，例如 Async Commit 功能是否有被使用
+- 内建函数的使用情况，包括 SQL 查询中各种函数的使用频次，其中不包含函数参数的具体信息
 
 可以通过执行以下 SQL 语句查看 TiDB 收集的使用情况信息内容：
 

ticdc/manage-ticdc.md

@@ -850,4 +850,4 @@ cdc cli --pd="http://10.0.10.25:2379" changefeed query --changefeed-id=simple-re
 > + 如果服务器使用机械硬盘或其他有延迟或吞吐有瓶颈的存储设备，请谨慎开启 Unified Sorter。
 > + 请保证硬盘的空闲容量大于等于 500G。如果需要同步大量历史数据，请确保每个节点的空闲容量大于等于要追赶的同步数据。
 > + Unified Sorter 默认开启，如果您的服务器不符合以上条件，并希望关闭 Unified Sorter，请手动将 changefeed 的 `sort-engine` 设为 `memory`。
-> + 如需在已有的 changefeed 上开启 Unified Sorter，参见[同步任务中断，尝试再次启动后 TiCDC 发生 OOM，如何处理](/ticdc/troubleshoot-ticdc.md#同步任务中断尝试再次启动后-ticdc-发生-oom如何处理)回答中提供的方法。
+> + 如需在已有的 changefeed 上开启 Unified Sorter，参见[同步任务中断，尝试再次启动后 TiCDC 发生 OOM，如何处理](/ticdc/troubleshoot-ticdc.md#同步任务中断尝试再次启动后-ticdc-发生-oom应该如何处理)回答中提供的方法。

ticdc/troubleshoot-ticdc.md

@@ -24,14 +24,73 @@ aliases: ['/docs-cn/dev/ticdc/troubleshoot-ticdc/','/docs-cn/dev/reference/tools
 
 在使用 `cdc cli changefeed create` 创建同步任务时会检查上游表是否符合[同步限制](/ticdc/ticdc-overview.md#同步限制)。如果存在表不满足同步限制，会提示 `some tables are not eligible to replicate` 并列出这些不满足的表。用户选择 `Y` 或 `y` 则会继续创建同步任务，并且同步过程中自动忽略这些表的所有更新。用户选择其他输入，则不会创建同步任务。
 
-## 如何处理 TiCDC 同步任务的中断？
+## 如何查看 TiCDC 同步任务的状态？
+
+可以使用 `cdc cli` 查询同步任务的状态。例如：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+cdc cli changefeed list --pd=http://10.0.10.25:2379
+```
+
+上述命令输出如下：
+
+```json
+[{
+    "id": "4e24dde6-53c1-40b6-badf-63620e4940dc",
+    "summary": {
+      "state": "normal",
+      "tso": 417886179132964865,
+      "checkpoint": "2020-07-07 16:07:44.881",
+      "error": null
+    }
+}]
+```
+
+* `checkpoint`：即为 TiCDC 已经将该时间点前的数据同步到了下游。
+* `state` 为该同步任务的状态：
+    * `normal`：正常同步。
+    * `stopped`：停止同步（手动暂停或出错）。
+    * `removed`：已删除任务。
+
+> **注意：**
+>
+> 该功能在 TiCDC 4.0.3 版本引入。
+
+## TiCDC 同步任务出现中断
+
+### 如何判断 TiCDC 同步任务出现中断？
+
+- 通过 Grafana 检查同步任务的 `changefeed checkpoint`（注意选择正确的 `changefeed id`）监控项。如果该值不发生变化（也可以查看 `checkpoint lag` 是否不断增大），可能同步任务出现中断。
+- 通过 Grafana 检查 `exit error count` 监控项，该监控项大于 0 代表同步任务出现错误。
+- 通过 `cdc cli changefeed list` 和 `cdc cli changefeed query` 命令查看同步任务的状态信息。任务状态为 `stopped` 代表同步中断，`error` 项会包含具体的错误信息。任务出错后可以在 TiCDC server 日志中搜索 `error on running processor` 查看错误堆栈，帮助进一步排查问题。
+- 部分极端异常情况下 TiCDC 出现服务重启，可以在 TiCDC server 日志中搜索 `FATAL` 级别的日志排查问题。
+
+### 如何查看 TiCDC 同步任务是否被人为终止？
+
+可以使用 `cdc cli` 查询同步任务是否被人为终止。例如：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+cdc cli changefeed query --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f
+```
+
+上述命令的输出中 `admin-job-type` 标志这个同步的任务的状态：
+
+* `0`: 任务进行中，没有被人为停止。
+* `1`: 任务暂停，停止任务后所有同步 `processor` 会结束退出，同步任务的配置和同步状态都会保留，可以从 `checkpoint-ts` 恢复任务。
+* `2`: 任务恢复，同步任务从 `checkpoint-ts` 继续同步。
+* `3`: 任务已删除，接口请求后会结束所有同步 `processor`，并清理同步任务配置信息。同步状态保留，只提供查询，没有其他实际功能。
 
-目前已知可能发生的同步中断包括以下两类场景：
+### 如何处理 TiCDC 同步任务的中断？
+
+目前已知可能发生的同步中断包括以下场景：
 
 - 下游持续异常，TiCDC 多次重试后仍然失败。
 
     - 该场景下 TiCDC 会保存任务信息，由于 TiCDC 已经在 PD 中设置的 service GC safepoint，在 `gc-ttl` 的有效期内，同步任务 checkpoint 之后的数据不会被 TiKV GC 清理掉。
-
     - 处理方法：用户可以在下游恢复正常后，通过 HTTP 接口恢复同步任务。
 
 - 因下游存在不兼容的 SQL 语句，导致同步不能继续。
@@ -42,35 +101,46 @@ aliases: ['/docs-cn/dev/ticdc/troubleshoot-ticdc/','/docs-cn/dev/reference/tools
         2. 使用新的任务配置文件，增加`ignore-txn-start-ts` 参数跳过指定 `start-ts` 对应的事务。
         3. 通过 HTTP API 停止旧的同步任务，使用 `cdc cli changefeed create` ，指定新的任务配置文件，指定 `start-ts` 为刚才记录的 `checkpoint-ts`，启动新的同步任务恢复同步。
 
-## 如何判断 TiCDC 同步任务出现中断？
+- 在 v4.0.13 及之前的版本中 TiCDC 同步分区表存在问题，导致同步停止。
 
-- 通过 Grafana 检查同步任务的 `changefeed checkpoint`（注意选择正确的 `changefeed id`）监控项。如果该值不发生变化（也可以查看 `checkpoint lag` 是否不断增大），可能同步任务出现中断。
-- 通过 Grafana 检查 `exit error count` 监控项，该监控项大于 0 代表同步任务出现错误。
-- 通过 `cdc cli changefeed list` 和 `cdc cli changefeed query` 命令查看同步任务的状态信息。任务状态为 `stopped` 代表同步中断，`error` 项会包含具体的错误信息。任务出错后可以在 TiCDC server 日志中搜索 `error on running processor` 查看错误堆栈，帮助进一步排查问题。
-- 部分极端异常情况下 TiCDC 出现服务重启，可以在 TiCDC server 日志中搜索 `FATAL` 级别的日志排查问题。
+    - 该场景下 TiCDC 会保存任务信息，由于 TiCDC 已经在 PD 中设置的 service GC safepoint，在 `gc-ttl` 的有效期内，同步任务 checkpoint 之后的数据不会被 TiKV GC 清理掉。
+    - 处理方法：
+        1. 通过 `cdc cli changefeed pause -c <changefeed-id>` 暂停同步。
+        2. 等待约一分钟后，通过 `cdc cli changefeed resume -c <changefeed-id>` 恢复同步。
 
-## TiCDC 的 `gc-ttl` 是什么？
+### 同步任务中断，尝试再次启动后 TiCDC 发生 OOM，应该如何处理？
 
-从 TiDB v4.0.0-rc.1 版本起，PD 支持外部服务设置服务级别 GC safepoint。任何一个服务可以注册更新自己服务的 GC safepoint。PD 会保证任何晚于该 GC safepoint 的 KV 数据不会在 TiKV 中被 GC 清理掉。在 TiCDC 中启用了这一功能，用来保证 TiCDC 在不可用、或同步任务中断情况下，可以在 TiKV 内保留 TiCDC 需要消费的数据不被 GC 清理掉。
+升级 TiDB 集群和 TiCDC 集群到最新版本。该 OOM 问题在 **v4.0.14 及之后的 v4.0 版本，v5.0.2 及之后的 v5.0 版本，更新的版本**上已得到缓解。
 
-启动 TiCDC server 时可以通过 `gc-ttl` 指定 GC safepoint 的 TTL，这个值的含义是当 TiCDC 服务全部挂掉后，由 TiCDC 在 PD 所设置的 GC safepoint 保存的最长时间，该值默认为 86400 秒。
+在这些版本上，可以开启 Unified Sorter 排序功能，该功能会在系统内存不足时使用磁盘进行排序。启用的方式是创建同步任务时在 `cdc cli` 内传入 `--sort-engine=unified`，使用示例如下：
+
+{{< copyable "shell-regular" >}}
 
-## 同步任务中断，尝试再次启动后 TiCDC 发生 OOM，如何处理？
+```shell
+cdc cli changefeed update -c <changefeed-id> --sort-engine="unified" --pd=http://10.0.10.25:2379
+```
 
-如果同步任务长时间中断，累积未消费的数据比较多，再次启动 TiCDC 可能会发生 OOM。这种情况下可以启用 TiCDC 提供的实验特性 Unified Sorter 排序引擎，该功能会在系统内存不足时使用磁盘进行排序。启用的方式是创建同步任务时在 `cdc cli` 内传入 `--sort-engine=unified` 和 `--sort-dir=/path/to/sort_dir`，使用示例如下：
+如果无法升级到上述版本，需要在**之前的版本**上开启 Unified Sorter，可以在创建同步任务时在 `cdc cli` 内传入 `--sort-engine=unified` 和 `--sort-dir=/path/to/sort_dir`，使用示例如下：
 
 {{< copyable "shell-regular" >}}
 
 ```shell
-cdc cli changefeed update -c [changefeed-id] --sort-engine="unified" --sort-dir="/data/cdc/sort" --pd=http://10.0.10.25:2379
+cdc cli changefeed update -c <changefeed-id> --sort-engine="unified" --sort-dir="/data/cdc/sort" --pd=http://10.0.10.25:2379
 ```
 
 > **注意：**
 >
 > + TiCDC 从 4.0.9 版本起支持 Unified Sorter 排序引擎。
 > + TiCDC（4.0 发布版本）还不支持动态修改排序引擎。在修改排序引擎设置前，请务必确保 changefeed 已经停止 (stopped)。
+> + `sort-dir` 在不同版本之间有不同的行为，请参考 [`sort-dir` 及 `data-dir` 配置项的兼容性说明](/ticdc/ticdc-overview.md#sort-dir-及-data-dir-配置项的兼容性说明)，谨慎配置。
 > + 目前 Unified Sorter 排序引擎为实验特性，在数据表较多 (>= 100) 时可能出现性能问题，影响同步速度，故不建议在生产环境中使用。开启 Unified Sorter 前请保证各 TiCDC 节点机器上有足够硬盘空间。如果积攒的数据总量有可能超过 1 TB，则不建议使用 TiCDC 进行同步。
 
+## TiCDC 的 `gc-ttl` 是什么？
+
+从 TiDB v4.0.0-rc.1 版本起，PD 支持外部服务设置服务级别 GC safepoint。任何一个服务可以注册更新自己服务的 GC safepoint。PD 会保证任何晚于该 GC safepoint 的 KV 数据不会在 TiKV 中被 GC 清理掉。在 TiCDC 中启用了这一功能，用来保证 TiCDC 在不可用、或同步任务中断情况下，可以在 TiKV 内保留 TiCDC 需要消费的数据不被 GC 清理掉。
+
+启动 TiCDC server 时可以通过 `gc-ttl` 指定 GC safepoint 的 TTL，这个值的含义是当 TiCDC 服务全部挂掉后，由 TiCDC 在 PD 所设置的 GC safepoint 保存的最长时间，该值默认为 86400 秒。
+
 ## TiCDC GC safepoint 的完整行为是什么
 
 TiCDC 服务启动后，如果有任务开始同步，TiCDC owner 会根据所有同步任务最小的 checkpoint-ts 更新到 PD service GC safepoint，service GC safepoint 可以保证该时间点及之后的数据不被 GC 清理掉。如果 TiCDC 同步任务中断，该任务的 checkpoint-ts 不会再改变，PD 对应的 service GC safepoint 也不会再更新。TiCDC 为 service GC safepoint 设置的存活有效期为 24 小时，即 TiCDC 服务中断 24 小时内恢复能保证数据不因 GC 而丢失。
@@ -175,57 +245,6 @@ cdc cli changefeed create --pd=http://10.0.10.25:2379 --sink-uri="kafka://127.0.
 
 更多信息请参考[创建同步任务](/ticdc/manage-ticdc.md#创建同步任务)。
 
-## 如何查看 TiCDC 同步任务的状态？
-
-可以使用 `cdc cli` 查询同步任务的状态。例如：
-
-{{< copyable "shell-regular" >}}
-
-```shell
-cdc cli changefeed list --pd=http://10.0.10.25:2379
-```
-
-上述命令输出如下：
-
-```json
-[{
-    "id": "4e24dde6-53c1-40b6-badf-63620e4940dc",
-    "summary": {
-      "state": "normal",
-      "tso": 417886179132964865,
-      "checkpoint": "2020-07-07 16:07:44.881",
-      "error": null
-    }
-}]
-```
-
-* `checkpoint`：即为 TiCDC 已经将该时间点前的数据同步到了下游。
-* `state` 为该同步任务的状态：
-    * `normal`：正常同步。
-    * `stopped`：停止同步（手动暂停或出错）。
-    * `removed`：已删除任务。
-
-> **注意：**
->
-> 该功能在 TiCDC 4.0.3 版本引入。
-
-## 如何查看 TiCDC 同步任务是否被人为终止？
-
-可以使用 `cdc cli` 查询同步任务是否被人为终止。例如：
-
-{{< copyable "shell-regular" >}}
-
-```shell
-cdc cli changefeed query --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f
-```
-
-上述命令的输出中 `admin-job-type` 标志这个同步的任务的状态：
-
-* `0`: 任务进行中，没有被人为停止。
-* `1`: 任务暂停，停止任务后所有同步 `processor` 会结束退出，同步任务的配置和同步状态都会保留，可以从 `checkpoint-ts` 恢复任务。
-* `2`: 任务恢复，同步任务从 `checkpoint-ts` 继续同步。
-* `3`: 任务已删除，接口请求后会结束所有同步 `processor`，并清理同步任务配置信息。同步状态保留，只提供查询，没有其他实际功能。
-
 ## 为什么 TiCDC 到 Kafka 的同步任务延时越来越大？
 
 * 请参考[如何查看 TiCDC 同步任务的状态？](/ticdc/troubleshoot-ticdc.md#如何查看-ticdc-同步任务的状态)检查下同步任务的状态是否正常。