Merge branch 'master' into lightning-glossary

dev/TOC.md

@@ -61,8 +61,11 @@
     - [Ansible 常见运维操作](/dev/how-to/maintain/ansible-operations.md)
     + 备份与恢复
       - [使用 Mydumper/Loader 进行备份与恢复](/dev/how-to/maintain/backup-and-restore/mydumper-loader.md)
-      - [使用 BR 进行备份与恢复](/dev/how-to/maintain/backup-and-restore/br.md)
-    - [定位慢查询](/dev/how-to/maintain/identify-slow-queries.md)
+      - [使用 BR 进行备份与恢复](/dev/reference/tools/br/br.md)
+      - [BR 备份与恢复最佳实践](/dev/reference/tools/br/br-best-practices.md)
+    + 定位异常查询
+      - [定位慢查询](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)
+      - [定位消耗系统资源多的查询](/dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md)
   + 扩容缩容
     - [使用 Ansible 扩容缩容](/dev/how-to/scale/with-ansible.md)
   + 升级
@@ -286,6 +289,7 @@
       - [常见错误修复](/dev/reference/tidb-binlog/troubleshoot/error-handling.md)
     - [FAQ](/dev/reference/tidb-binlog/faq.md)
   + 周边工具
+    - [工具使用指南](/dev/reference/tools/use-guide.md)
     - [Mydumper](/dev/reference/tools/mydumper.md)
     - [Loader](/dev/reference/tools/loader.md)
     - [Syncer](/dev/reference/tools/syncer.md)
@@ -345,6 +349,7 @@
       - [断点续传](/dev/reference/tools/tidb-lightning/checkpoints.md)
       - [表库过滤](/dev/reference/tools/tidb-lightning/table-filter.md)
       - [CSV 支持](/dev/reference/tools/tidb-lightning/csv.md)
+      - [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md)
       - [Web 界面](/dev/reference/tools/tidb-lightning/web.md)
       - [监控告警](/dev/reference/tools/tidb-lightning/monitor.md)
       - [故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md)
@@ -409,6 +414,8 @@
   - [改进文档](/dev/contribute.md#改进文档)
 + [TiDB 路线图](/dev/roadmap.md)
 + [版本发布历史](/dev/releases/rn.md)
+  + v4.0
+    - [4.0.0-beta](/dev/releases/4.0.0-beta.md)
   + v3.1
     - [3.1.0-beta.1](/dev/releases/3.1.0-beta.1.md)
     - [3.1.0-beta](/dev/releases/3.1.0-beta.md)

dev/faq/tidb-lightning.md

@@ -5,9 +5,15 @@ category: FAQ
 
 # TiDB Lightning 常见问题
 
+本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。
+
+>**注意：**
+>
+> 使用 TiDB Lightning 的过程中如遇错误，参考 [TiDB Lightning 故障诊断](/dev/how-to/troubleshoot/tidb-lightning.md)进行排查。
+
 ## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？
 
-最低版本要求是 2.0.9。
+TiDB Lightning 的版本应与集群相同。最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。
 
 ## TiDB Lightning 支持导入多个库吗？
 
@@ -23,17 +29,41 @@ TiDB Lightning 需要以下权限：
 * CREATE
 * DROP
 
-存储断点的数据库额外需要以下权限：
+如果选择 [TiDB-backend](/dev/reference/tools/tidb-lightning/tidb-backend.md) 模式，或目标数据库用于存储断点，则 TiBD Lightning 额外需要以下权限：
 
 * INSERT
 * DELETE
 
++Importer-backend 无需以上两个权限，因为数据直接被 Ingest 到 TiKV 中，所以绕过了 TiDB 的权限系统。只要 TiKV、TiKV Importer 和 TiDB Lightning 的端口在集群之外不可访问，就可以保证安全。
+
 如果 TiDB Lightning 配置项 `checksum = true`，则 TiDB Lightning 需要有下游 TiDB admin 用户权限。
 
 ## TiDB Lightning 在导数据过程中某个表报错了，会影响其他表吗？进程会马上退出吗？
 
 如果只是个别表报错，不会影响整体。报错的那个表会停止处理，继续处理其他的表。
 
+## 如何正确重启 TiDB Lightning？
+
+根据 `tikv-importer` 的状态，重启 TiDB Lightning 的基本顺序如下：
+
+如果 `tikv-importer` 仍在运行：
+
+1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。
+2. 执行修改操作（如修复数据源、更改设置、更换硬件等）。
+3. 如果上面的修改操作更改了任何表，你还需要[清除对应的断点](/dev/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-remove)。
+4. 重启 `tidb-lightning`。
+
+如果 `tikv-importer` 需要重启：
+
+1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。
+2. [结束 `tikv-importer` 进程](#如何正确结束-tikv-importer-进程)。
+3. 执行修改操作（如修复数据源、更改设置、更换硬件等）。
+4. 重启 `tikv-importer`。
+5. 重启 `tidb-lightning` 并等待，**直到程序因校验和错误（如果有的话）而失败**。
+    * 重启 `tikv-importer` 将清除所有仍在写入的引擎文件，但是 `tidb-lightning` 并不会感知到该操作。从 v3.0 开始，最简单的方法是让 `tidb-lightning` 继续，然后再重试。
+6. [清除失败的表及断点](/dev/how-to/troubleshoot/tidb-lightning.md#checkpoint-for--has-invalid-status错误码)。
+7. 再次重启 `tidb-lightning`。
+
 ## 如何校验导入的数据的正确性？
 
 TiDB Lightning 默认会对导入数据计算校验和 (checksum)，如果校验和不一致就会停止导入该表。可以在日志看到相关的信息。
@@ -57,13 +87,16 @@ ADMIN CHECKSUM TABLE `schema`.`table`;
 
 ## TiDB Lightning 支持哪些格式的数据源？
 
-到 v2.1.6 版本为止，只支持本地文档形式的数据源，支持 [Mydumper](/dev/reference/tools/mydumper.md) 或 [CSV](/dev/reference/tools/tidb-lightning/csv.md) 格式。
+TiDB Lightning 只支持两种格式的数据源：
+
+1. [Mydumper](/dev/reference/tools/mydumper.md) 生成的 SQL dump
+2. 储存在本地文件系统的 [CSV](/dev/reference/tools/tidb-lightning/csv.md) 文件
 
 ## 我已经在下游创建好库和表了，TiDB Lightning 可以忽略建库建表操作吗？
 
-可以。在配置文档中的 `[mydumper]` 将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。
+可以。在配置文档中的 `[mydumper]` 部分将 `no-schema` 设置为 `true` 即可。`no-schema=true` 会默认下游已经创建好所需的数据库和表，如果没有创建，会报错。
 
-## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL MOde) 来导入？
+## 有些不合法的数据，能否通过关掉严格 SQL 模式 (Strict SQL Mode) 来导入？
 
 可以。Lightning 默认的 [`sql_mode`](https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html) 为 `"STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"`。
 
@@ -76,23 +109,23 @@ sql-mode = ""
 ...
 ```
 
-## 可以起一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？
+## 可以启用一个 `tikv-importer`，同时有多个 `tidb-lightning` 进程导入数据吗？
 
 只要每个 Lightning 操作的表互不相同就可以。
 
-## 如何正确关闭 `tikv-importer` 进程？
+## 如何正确结束 `tikv-importer` 进程？
 
-根据您的部署方式，选择相应操作结束进程
+根据部署方式，选择相应操作结束进程
 
-- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh` 。
+- 使用 TiDB Ansible 部署：在 Importer 的服务器上运行 `scripts/stop_importer.sh`。
 
-- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 <kbd>Ctrl</kbd>+<kbd>C</kbd> 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程ID，然后通过 `kill «pid»` 结束进程。
+- 手动部署：如果 `tikv-importer` 正在前台运行，可直接按 <kbd>Ctrl</kbd>+<kbd>C</kbd> 退出。否则，可通过 `ps aux | grep tikv-importer` 获取进程 ID，然后通过 `kill «pid»` 结束进程。
 
-## 如何正确关闭 `tidb-lightning` 进程？
+## 如何正确结束 `tidb-lightning` 进程？
 
-根据您的部署方式，选择相应操作结束进程
+根据部署方式，选择相应操作结束进程
 
-- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh` 。
+- 使用 TiDB Ansible 部署：在 Lightning 的服务器上运行 `scripts/stop_lightning.sh`。
 
 - 手动部署：如果 `tidb-lightning` 正在前台运行，可直接按 <kbd>Ctrl</kbd>+<kbd>C</kbd> 退出。否则，可通过 `ps aux | grep tidb-lightning` 获取进程 ID，然后通过 `kill -2 «pid»` 结束进程。
 
@@ -104,7 +137,7 @@ sql-mode = ""
 [2018/08/10 07:29:08.310 +08:00] [INFO] [main.go:41] ["got signal to exit"] [signal=hangup]
 ```
 
-不推荐在命令行中直接使用 `nohup` 启动进程，推荐按照 [启动 tidb-lightning](/dev/reference/tools/tidb-lightning/deployment.md) 使用脚本启动。
+不推荐在命令行中直接使用 `nohup` 启动进程，推荐[使用脚本启动 `tidb-lightning`](/dev/reference/tools/tidb-lightning/deployment.md)。
 
 ## 为什么用过 TiDB Lightning 之后，TiDB 集群变得又慢又耗 CPU？
 
@@ -118,7 +151,16 @@ tidb-lightning-ctl --switch-mode=normal
 
 ## TiDB Lightning 可以使用千兆网卡吗？
 
-使用 TiDB Lightning 必须配置万兆网卡。**不能使用**千兆网卡，尤其是在部署 `tikv-importer` 的机器上。千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。
+使用 TiDB Lightning 建议配置万兆网卡。**不推荐**使用千兆网卡，尤其是在部署 `tikv-importer` 的机器上。
+
+千兆网卡的总带宽只有 120 MB/s，而且需要与整个 TiKV 集群共享。在使用 TiDB Lightning 导入时，极易用尽所有带宽，继而因 PD 无法联络集群使集群断连。为了避免这种情况，你可以在 [`tikv-importer` 的配置文件](/dev/reference/tools/tidb-lightning/config.md#tikv-importer-配置参数)中**限制上传速度**。
+
+```toml
+[import]
+# Importer 上传至 TiKV 的最大速度（字节/秒）。
+# 建议将该速度设为 100 MB/s 或更小。
+upload-speed-limit = "100MB"
+```
 
 ## 为什么 TiDB Lightning 需要在 TiKV 集群预留这么多空间？
 
@@ -129,4 +171,20 @@ tidb-lightning-ctl --switch-mode=normal
 
 ## TiDB Lightning 使用过程中是否可以重启 TiKV Importer？
 
-不能，Importer 会保存一些 Engine 的信息在内存中，Importer 重启后，Lightning 必须重启。
+不能，Importer 会在内存中存储一些引擎文件，Importer 重启后，`tidb-lightning` 会因连接失败而停止。此时，你需要[清除失败的断点](/dev/reference/tools/tidb-lightning/checkpoints.md#--checkpoint-error-destroy)，因为这些 Importer 特有的信息丢失了。你可以在之后[重启 Lightning](#如何正确重启-tidb-lightning)。
+
+## 如何清除所有与 TiDB Lightning 相关的中间数据？
+
+1. 删除断点文件。
+
+    {{< copyable "shell-regular" >}}
+
+    ```sh
+    tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-remove=all
+    ```
+
+    如果出于某些原因而无法运行该命令，你可以尝试手动删除 `/tmp/tidb_lightning_checkpoint.pb` 文件。
+
+2. 删除 `tikv-importer` 所在机器上的整个 “import” 文件目录。
+
+3. 如果需要的话，删除 TiDB 集群上创建的所有表和库。

dev/faq/tidb.md

@@ -269,7 +269,7 @@ TiDB 支持部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器
 
 2）如果出现了慢查询，可以从 Grafana 监控定位到出现慢查询的 tidb-server 以及时间点，然后在对应节点查找日志中记录的 SQL 信息。
 
-3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/dev/how-to/maintain/identify-slow-queries.md#admin-show-slow-命令)。
+3）除了日志，还可以通过 `admin show slow` 命令查看，详情可参考 [`admin show slow` 命令](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md#admin-show-slow-命令)。
 
 #### 2.2.5 首次部署 TiDB 集群时，没有配置 tikv 的 Label 信息，在后续如何添加配置 Label？
 
@@ -854,10 +854,6 @@ TiDB 读流量可以通过增加 TiDB server 进行扩展，总读容量无限
 
 导入数据的时候，可以分批插入，每批最好不要超过 1w 行。
 
-对于 insert 和 select，可以开启 `set @@session.tidb_batch_insert=1;` 隐藏参数，insert 会把大事务分批执行。这样不会因为事务太大而超时，但是可能会导致事务原子性的丢失，因此不建议在生产环境中使用。如果事务执行过程中报错，会导致只完成一部分事务的插入。所以建议只有在需要的时候，在 session 中使用，这样不会影响其他语句。事务完成以后，可以用 `set @@session.tidb_batch_insert=0` 关闭。
-
-对 delete 和 update 语句，可以使用 limit 加循环的方式进行操作。
-
 #### 4.3.5 TiDB 中删除数据后会立即释放空间吗？
 
 DELETE，TRUNCATE 和 DROP 都不会立即释放空间。对于 TRUNCATE 和 DROP 操作，在达到 TiDB 的 GC (garbage collection) 时间后（默认 10 分钟），TiDB 的 GC 机制会删除数据并释放空间。对于 DELETE 操作 TiDB 的 GC 机制会删除数据，但不会释放空间，而是当后续数据写入 RocksDB 且进行 compact 时对空间重新利用。

dev/how-to/maintain/identify-abnormal-queries/identify-aborted-queries.md

@@ -0,0 +1,52 @@
+---
+title: 定位消耗系统资源多的查询
+category: how-to
+---
+
+# 定位消耗系统资源多的查询
+
+TiDB 会将执行时间超过 [tidb_expensive_query_time_threshold](/dev/reference/configuration/tidb-server/tidb-specific-variables.md#tidb_expensive_query_time_threshold)（默认值为 60s），或使用内存超过 [mem-quota-query](/dev/reference/configuration/tidb-server/configuration-file.md#mem-quota-query)（默认值为 32 GB）的语句输出到 [tidb-server 日志文件](/dev/reference/configuration/tidb-server/configuration-file.md#logfile)（默认文件为：“tidb.log”）中，用于在语句执行结束前定位消耗系统资源多的查询语句（以下简称为 expensive query），帮助用户分析和解决语句执行的性能问题。
+
+注意，expensive query 日志和[慢查询日志](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md)的区别是，慢查询日志是在语句执行完后才打印，expensive query 日志可以将正在执行的语句的相关信息打印出来。当一条语句在执行过程中达到资源使用阈值时（执行时间/使用内存量），TiDB 会即时将这条语句的相关信息写入日志。
+
+## Expensive query 日志示例
+
+```sql
+[2020/02/05 15:32:25.096 +08:00] [WARN] [expensivequery.go:167] [expensive_query] [cost_time=60.008338935s] [wait_time=0s] [request_count=1] [total_keys=70] [process_keys=65] [num_cop_tasks=1] [process_avg_time=0s] [process_p90_time=0s] [process_max_time=0s] [process_max_addr=10.0.1.9:20160] [wait_avg_time=0.002s] [wait_p90_time=0.002s] [wait_max_time=0.002s] [wait_max_addr=10.0.1.9:20160] [stats=t:pseudo] [conn_id=60026] [user=root] [database=test] [table_ids="[122]"] [txn_start_ts=414420273735139329] [mem_max="1035 Bytes (1.0107421875 KB)"] [sql="insert into t select sleep(1) from t"]
+```
+
+## 字段含义说明
+
+基本字段：
+
+* `cost_time`：日志打印时语句已经花费的执行时间。
+* `stats`：语句涉及到的表或索引使用的统计信息版本。值为 pesudo 时表示无可用统计信息，需要对表或索引进行 analyze。
+* `table_ids`：语句涉及到的表的 ID。
+* `txn_start_ts`：事务的开始时间戳，也是事务的唯一 ID，可以用这个值在 TiDB 日志中查找事务相关的其他日志。
+* `sql`：SQL 语句。
+
+和内存使用相关的字段：
+
+* `mem_max`：日志打印时语句已经使用的内存空间。该项使用两种单位标识内存使用量，分别为 Bytes 以及易于阅读的自适应单位（比如 MB、GB 等）。
+
+和 SQL 执行的用户相关的字段：
+
+* `user`：执行语句的用户名。
+* `conn_id`：用户的连接 ID，可以用类似 `con:60026` 的关键字在 TiDB 日志中查找该连接相关的其他日志。
+* `database`：执行语句时使用的 database。
+
+和 TiKV Coprocessor Task 相关的字段：
+
+* `wait_time`：该语句在 TiKV 的等待时间之和，因为 TiKV 的 Coprocessor 线程数是有限的，当所有的 Coprocessor 线程都在工作的时候，请求会排队；当队列中有某些请求耗时很长的时候，后面的请求的等待时间都会增加。
+* `request_count`：该语句发送的 Coprocessor 请求的数量。
+* `total_keys`：Coprocessor 扫过的 key 的数量。
+* `processed_keys`：Coprocessor 处理的 key 的数量。与 total_keys 相比，processed_keys 不包含 MVCC 的旧版本。如果 processed_keys 和 total_keys 相差很大，说明旧版本比较多。
+* `num_cop_tasks`：该语句发送的 Coprocessor 请求的数量。
+* `process_avg_time`：Coprocessor 执行 task 的平均执行时间。
+* `process_p90_time`：Coprocessor 执行 task 的 P90 分位执行时间。
+* `process_max_time`：Coprocessor 执行 task 的最长执行时间。
+* `process_max_addr`：task 执行时间最长的 Coprocessor 所在地址。
+* `wait_avg_time`：Coprocessor 上 task 的等待时间。
+* `wait_p90_time`：Coprocessor 上 task 的 P90 分位等待时间。
+* `wait_max_time`：Coprocessor 上 task 的最长等待时间。
+* `wait_max_addr`：task 等待时间最长的 Coprocessor 所在地址。

dev/how-to/maintain/identify-slow-queries.md → dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md

@@ -1,7 +1,7 @@
 ---
 title: 慢查询日志
 category: how-to
-aliases: ['/docs-cn/sql/slow-query/']
+aliases: ['/docs-cn/sql/slow-query/','/docs-cn/dev/how-to/maintain/identify-slow-queries/']
 ---
 
 # 慢查询日志

dev/how-to/troubleshoot/cluster-setup.md

@@ -132,7 +132,7 @@ tidb-server 无法启动的常见情况包括：
 
 ## 数据库访问超时，系统负载高
 
-首先检查 [SLOW-QUERY](/dev/how-to/maintain/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息：
+首先检查 [SLOW-QUERY](/dev/how-to/maintain/identify-abnormal-queries/identify-slow-queries.md) 日志，判断是否是因为某条 SQL 语句导致。如果未能解决，请提供如下信息：
 
 + 部署的拓扑结构
     - tidb-server/pd-server/tikv-server 部署了几个实例