pingcap · TomShawn · Apr 15, 2020 · Apr 15, 2020
diff --git a/reference/system-databases/cluster-config.md b/reference/system-databases/cluster-config.md
@@ -27,7 +27,7 @@ desc cluster_config;
 
 字段解释：
 
-* `TYPE`：节点的类型，可取值为 `tidb`，`pd` 或 `tikv`。
+* `TYPE`：节点的类型，可取值为 `tidb`，`pd` 和 `tikv`。
 * `INSTANCE`：节点的服务地址。
 * `KEY`：配置项名。
 * `VALUE`：配置项值。

diff --git a/reference/system-databases/cluster-hardware.md b/reference/system-databases/cluster-hardware.md
@@ -1,6 +1,6 @@
 ---
 title: CLUSTER_HARDWARE
-summary: 了解 TiDB 集群配置表 `CLUSTER_HARDWARE`。
+summary: 了解 TiDB 集群硬件表 `CLUSTER_HARDWARE`。
 category: reference
 ---
 
@@ -29,15 +29,15 @@ desc cluster_hardware;
 
 字段解释：
 
-* `TYPE`：对应节点信息表 `information_schema.cluster_info` 中的 `TYPE` 字段，可取值为 `tidb`，`pd` 或 `tikv`。
-* `INSTANCE`：对应于节点信息表 `information_schema.cluster_info` 中的 `STATUS_ADDRESS` 字段。
+* `TYPE`：对应节点信息表 [`information_schema.cluster_info`](/reference/system-databases/cluster-info.md) 中的 `TYPE` 字段，可取值为 `tidb`，`pd` 和 `tikv`。
+* `INSTANCE`：对应于节点信息表 `information_schema.cluster_info` 中的 `INSTANCE` 字段。
 * `DEVICE_TYPE`：硬件类型。目前可以查询的硬件类型有 `cpu`、`memory`、`disk` 和 `net`。
 * `DEVICE_NAME`：硬件名。对于不同的 `DEVICE_TYPE`，`DEVICE_NAME` 的取值不同。
     * `cpu`：硬件名为 cpu。
     * `memory`：硬件名为 memory。
     * `disk`：磁盘名。
     * `net`：网卡名。
-* `NAME`：硬件不同的信息名，比如 cpu 有 `cpu-logical-cores` ， `cpu-physical-cores` 两个信息名，表示逻辑核心数量和物理核心数量。
+* `NAME`：硬件不同的信息名，比如 cpu 有 `cpu-logical-cores` 和 `cpu-physical-cores` 两个信息名，表示逻辑核心数量和物理核心数量。
 * `VALUE`：对应硬件信息的值。例如磁盘容量和 CPU 核数。
 
 查询集群 CPU 信息的示例如下：

diff --git a/reference/system-databases/cluster-info.md b/reference/system-databases/cluster-info.md
@@ -1,6 +1,6 @@
 ---
 title: CLUSTER_INFO
-summary: 了解 TiDB 集群配置表 `CLUSTER_INFO`。
+summary: 了解 TiDB 集群拓扑表 `CLUSTER_INFO`。
 category: reference
 ---
 
@@ -31,9 +31,9 @@ desc cluster_info;
 
 字段解释：
 
-* `TYPE`：节点类型，目前节点的可取值为 `tidb`，`pd` 或 `tikv`。
+* `TYPE`：节点类型，目前节点的可取值为 `tidb`，`pd` 和 `tikv`。
 * `INSTANCE`：实例地址，为 `IP:PORT` 格式的字符串。
-* `STATUS_ADDRESS`：HTTP API 的服务地址。部分 `tikv-ctl`、`pd-ctl` 或 `tidb-ctl` 命令会使用到 HTTP API 和该地址。用户也可以通过该地址获取一些额外的集群信息，详情可参考 HTTP API 官方文档。
+* `STATUS_ADDRESS`：HTTP API 的服务地址。部分 `tikv-ctl`、`pd-ctl` 或 `tidb-ctl` 命令会使用到 HTTP API 和该地址。用户也可以通过该地址获取一些额外的集群信息，详情可参考 [HTTP API 文档](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md)。
 * `VERSION`：对应节点的语义版本号。TiDB 版本为了兼容 MySQL 的版本号，以 `${mysql-version}-${tidb-version}` 的格式展示版本号。
 * `GIT_HASH`：编译节点版本时的 Git Commit Hash，用于识别两个节点是否是绝对一致的版本。
 * `START_TIME`：对应节点的启动时间。

diff --git a/reference/system-databases/cluster-load.md b/reference/system-databases/cluster-load.md
@@ -1,6 +1,6 @@
 ---
 title: CLUSTER_LOAD
-summary: 了解 TiDB 集群配置表 `CLUSTER_LOAD`。
+summary: 了解 TiDB 集群负载表 `CLUSTER_LOAD`。
 category: reference
 ---
 
@@ -29,16 +29,16 @@ desc cluster_load;
 
 字段解释：
 
-* `TYPE`：对应于节点信息表 `information_schema.cluster_info` 中的 `TYPE` 字段，可取值为 `tidb`，`pd` 或 `tikv`。
+* `TYPE`：对应于节点信息表 [`information_schema.cluster_info`](/reference/system-databases/cluster-info.md) 中的 `TYPE` 字段，可取值为 `tidb`，`pd` 和 `tikv`。
 * `INSTANCE`：对应于节点信息表 `information_schema.cluster_info` 中的 `STATUS_ADDRESS` 字段。
 * `DEVICE_TYPE`：硬件类型，目前可以查询的硬件类型有 `cpu`、`memory`、`disk` 和 `net`。
 * `DEVICE_NAME`：硬件名。对于不同的 `DEVICE_TYPE`，`DEVICE_NAME` 取值不同。
     * `cpu`：硬件名为 cpu。
     * `disk`：磁盘名。
     * `net`：网卡名。
     * `memory`：硬件名为 memory。
-* `NAME`：不同的负载类型。例如 cpu 有 `load1`/`load5`/`load15` 三个负载类型，分别表示 cpu 在 `1min`/`5min`/`15min` 内的平均负载。
-* `VALUE`：硬件负载的值，例如 cpu 在 `1min`/`5min`/`15min` 内的平均负载。
+* `NAME`：不同的负载类型。例如 cpu 有 `load1`/`load5`/`load15` 三个负载类型，分别表示 cpu 在 1min/5min/15min 内的平均负载。
+* `VALUE`：硬件负载的值，例如 cpu 在 1min/5min/15min 内的平均负载。
 
 查询集群当前的 CPU 负载信息示例如下：
 

diff --git a/reference/system-databases/cluster-log.md b/reference/system-databases/cluster-log.md
@@ -1,6 +1,6 @@
 ---
 title: CLUSTER_LOG
-summary: 了解 TiDB 集群配置表 `CLUSTER_LOG`。
+summary: 了解 TiDB 集群日志表 `CLUSTER_LOG`。
 category: reference
 ---
 
@@ -32,7 +32,7 @@ desc cluster_log;
 字段解释：
 
 * `TIME`：日志打印时间。
-* `TYPE`：节点的类型，可取值为 `tidb`，`pd` 或 `tikv`。
+* `TYPE`：节点的类型，可取值为 `tidb`，`pd` 和 `tikv`。
 * `INSTANCE`：节点的服务地址。
 * `LEVEL`：日志级别。
 * `MESSAGE`：日志内容。
@@ -68,6 +68,6 @@ select * from `CLUSTER_LOG` where message like '%ddl%' and message like '%job%58
 
 上面查询结果表示：
 
-1. 用户将 DDL JOB ID 为 58 的请求发给 `172.16.5.40:4008` TiDB 节点。
-2. `172.16.5.40:4009` TiDB 节点处理这个 DDL 请求，说明此时 `172.16.5.40:4009` 节点是 DDL owner。
-3. DDL JOB ID 为 58 的请求处理完成。
++ 用户将 DDL JOB ID 为 `58` 的请求发给 `172.16.5.40:4008` TiDB 节点。
++ `172.16.5.40:4009` TiDB 节点处理这个 DDL 请求，说明此时 `172.16.5.40:4009` 节点是 DDL owner。
++ DDL JOB ID 为 58 的请求处理完成。
diff --git a/reference/system-databases/cluster-systeminfo.md b/reference/system-databases/cluster-systeminfo.md
@@ -1,6 +1,6 @@
 ---
 title: CLUSTER_SYSTEMINFO
-summary: 了解 TiDB 集群配置表 `CLUSTER_SYSTEMINFO`。
+summary: 了解 TiDB 集群负载表 `CLUSTER_SYSTEMINFO`。
 category: reference
 ---
 
@@ -30,8 +30,8 @@ desc cluster_systeminfo;
 
 字段解释：
 
-* `TYPE`：对应于节点信息表 `information_schema.cluster_info` 中的 `TYPE` 字段，可取值为 `tidb`，`pd` 或 `tikv`。
-* `INSTANCE`：对应于节点信息表 `information_schema.cluster_info` 中的 `INSTANCE` 字段。
+* `TYPE`：对应于节点信息表 [`information_schema.cluster_info`](/reference/system-databases/cluster-info.md) 中的 `TYPE` 字段，可取值为 `tidb`，`pd` 和 `tikv`。
+* `INSTANCE`：对应于节点信息表 [`information_schema.cluster_info`](/reference/system-databases/information-schema.md) 中的 `INSTANCE` 字段。
 * `SYSTEM_TYPE`：系统类型，目前可以查询的系统类型有 `system`。
 * `SYSTEM_NAME`：目前可以查询的 `SYSTEM_NAME` 为 `sysctl`。
 * `NAME`：`sysctl` 对应的配置名。
@@ -51,4 +51,4 @@ select * from CLUSTER_SYSTEMINFO where name like '%kernel.osrelease%'
 | pd   | 172.16.5.40:20379 | system      | sysctl      | kernel.osrelease | 3.10.0-862.14.4.el7.x86_64 |
 | tikv | 172.16.5.40:21150 | system      | sysctl      | kernel.osrelease | 3.10.0-862.14.4.el7.x86_64 |
 +------+-------------------+-------------+-------------+------------------+----------------------------+
-```
+```
diff --git a/reference/system-databases/inspection-result.md b/reference/system-databases/inspection-result.md
@@ -1,6 +1,6 @@
 ---
 title: INSPECTION_RESULT
-summary: 了解 TiDB 集群配置表 `INSPECTION_RESULT`。
+summary: 了解 TiDB 系统表 `INSPECTION_RESULT`。
 category: reference
 ---
 
@@ -15,7 +15,7 @@ TiDB 内置了一些诊断规则，用于检测系统中的故障以及隐患。
 {{< copyable "sql" >}}
 
 ```sql
-mysql> desc inspection_result;
+desc inspection_result;
 ```
 
 ```
@@ -43,7 +43,7 @@ mysql> desc inspection_result;
     * `critical-error`：系统各个模块定义了严重的错误，如果某一个严重错误在对应时间段内超过阈值，会生成 `warning` 诊断结果。
     * `threshold-check`：诊断系统会对大量指标进行阈值判断，如果超过阈值会生成对应的诊断信息。
 * `ITEM`：每一个规则会对不同的项进行诊断，该字段表示对应规则下面的具体诊断项。
-* `TYPE`：诊断的实例类型，可取值为 `tidb`，`pd` 或 `tikv`。
+* `TYPE`：诊断的实例类型，可取值为 `tidb`，`pd` 和 `tikv`。
 * `INSTANCE`：诊断的具体实例地址。
 * `VALUE`：针对这个诊断项得到的值。
 * `REFERENCE`：针对这个诊断项的参考值（阈值）。如果 `VALUE` 和阈值相差较大，就会产生对应的诊断信息。
@@ -101,9 +101,9 @@ DETAILS   | max duration of 172.16.5.40:20151 tikv rocksdb-write-duration was to
 
 上述诊断结果发现了以下几个问题：
 
-* 第一行表示 TiDB 的 log.slow-threshold 配置值为 0 ， 可能会影响性能。
+* 第一行表示 TiDB 的 `log.slow-threshold` 配置值为 `0`，可能会影响性能。
 * 第二行表示集群中有 2 个不同的 TiDB 版本
-* 第三、四行表示 TiKV 的写入延迟太大，期望时间是不超过 0.1s, 但实际值远超预期。 
+* 第三、四行表示 TiKV 的写入延迟太大，期望时间是不超过 0.1s, 但实际值远超预期。
 
 诊断集群在时间段 "2020-03-26 00:03:00", "2020-03-26 00:08:00" 的问题。指定时间范围需要使用 `/*+ time_range() */` 的 SQL Hint，参考下面的查询示例：
 
@@ -137,7 +137,7 @@ DETAILS   | max duration of 172.16.5.40:10089 tidb get-token-duration is too slo
 上面的诊断结果发现了以下问题：
 
 * 第一行表示 172.16.5.40:4009 TiDB 节点在 `2020/03/26 00:05:45.670` 发生了重启。
-* 第二行表示 172.16.5.40:10089 TiDB 节点的最大的 get-token-duration 时间为 0.234s, 期望时间是小于 0.001s。 
+* 第二行表示 172.16.5.40:10089 TiDB 节点的最大的 `get-token-duration` 时间为 0.234s, 期望时间是小于 0.001s。
 
 也可以指定条件，比如只查询 `critical` 严重级别的诊断结果：
 
@@ -179,9 +179,9 @@ select * from inspection_rules where type='inspection';
 +-----------------+------------+---------+
 ```
 
-### config 诊断规则
+### `config` 诊断规则
 
-config 诊断规则通过查询 `CLUSTER_CONFIG` 系统表，执行以下 2 个诊断规则：
+`config` 诊断规则通过查询 `CLUSTER_CONFIG` 系统表，执行以下两个诊断规则：
 
 * 检测相同组件的配置值是否一致，并非所有配置项都会有一致性检查，下面是一致性检查的白名单：
 
@@ -196,7 +196,7 @@ config 诊断规则通过查询 `CLUSTER_CONFIG` 系统表，执行以下 2 个
     log.file.filename
     log.slow-query-file
 
-    // PD 配置一致性检查白名单 
+    // PD 配置一致性检查白名单
     advertise-client-urls
     advertise-peer-urls
     client-urls
@@ -218,14 +218,14 @@ config 诊断规则通过查询 `CLUSTER_CONFIG` 系统表，执行以下 2 个
 
 * 检测以下配置项的值是否符合预期。
 
-|  组件  | 配置项 | 预期值 |
-|  ----  | ----  |  ----  |
-| TiDB | log.slow-threshold | 大于 0 |
-| TiKV | raftstore.sync-log | true |
+    |  组件  | 配置项 | 预期值 |
+    |  :----  | :----  |  :----  |
+    | TiDB | log.slow-threshold | 大于 0 |
+    | TiKV | raftstore.sync-log | true |
 
 ### version 诊断规则
 
-version 诊断规则通过查询 `CLUSTER_INFO` 系统表，检测相同组件的版本 hash 是否一致。示例如下：
+`version` 诊断规则通过查询 `CLUSTER_INFO` 系统表，检测相同组件的版本 hash 是否一致。示例如下：
 
 {{< copyable "sql" >}}
 
@@ -245,32 +245,32 @@ SEVERITY  | critical
 DETAILS   | the cluster has 2 different tidb versions, execute the sql to see more detail: select * from information_schema.cluster_info where type='tidb'
 ```
 
-### critical-error 诊断规则
+### `critical-error` 诊断规则
 
-critical-error 诊断规则执行以下 2 个诊断规则：
+`critical-error` 诊断规则执行以下两个诊断规则：
 
-* 通过查询 metrics_schema 数据库中相关的监控系统表，检测集群是否有出现以下比较严重的错误：
+* 通过查询 [metrics schema](/reference/system-databases/metrics-schema.md) 数据库中相关的监控系统表，检测集群是否有出现以下比较严重的错误：
 
-|  组件  | 错误名字 | 相关监控表 | 错误说明 |
-|  ----  | ----  |  ----  |  ----  |
-| TiDB | panic-count | tidb_panic_count_total_count | TiDB 出现 panic 错误 |
-| TiDB | binlog-error | tidb_binlog_error_total_count | TiDB 写 binlog 时出现的错误 |
-| TiKV | critical-error | tikv_critical_error_total_coun | TiKV 的 critical error |
-| TiKV | scheduler-is-busy       | tikv_scheduler_is_busy_total_count | TiKV 的 scheduler 太忙，该使 TiKV 临时不可用 |
-| TiKV | coprocessor-is-busy | tikv_coprocessor_is_busy_total_count | TiKV 的 coprocessor 太忙 |
-| TiKV | channel-is-full | tikv_channel_full_total_count | TiKV 出现 channel full 的错误 |
-| TiKV | tikv_engine_write_stall | tikv_engine_write_stall | TiKV 出现写入 stall 的错误 |
+    |  组件  | 错误名字 | 相关监控表 | 错误说明 |
+    |  ----  | ----  |  ----  |  ----  |
+    | TiDB | panic-count | tidb_panic_count_total_count | TiDB 出现 panic 错误 |
+    | TiDB | binlog-error | tidb_binlog_error_total_count | TiDB 写 binlog 时出现的错误 |
+    | TiKV | critical-error | tikv_critical_error_total_coun | TiKV 的 critical error |
+    | TiKV | scheduler-is-busy       | tikv_scheduler_is_busy_total_count | TiKV 的 scheduler 太忙，该使 TiKV 临时不可用 |
+    | TiKV | coprocessor-is-busy | tikv_coprocessor_is_busy_total_count | TiKV 的 coprocessor 太忙 |
+    | TiKV | channel-is-full | tikv_channel_full_total_count | TiKV 出现 channel full 的错误 |
+    | TiKV | tikv_engine_write_stall | tikv_engine_write_stall | TiKV 出现写入 stall 的错误 |
 
-* 通过查询 metrics_schema.up 监控表和 `CLUSTER_LOG` 系统表，检查是否有组件发生重启。
+* 通过查询 `metrics_schema.up` 监控表和 `CLUSTER_LOG` 系统表，检查是否有组件发生重启。
 
-### threshold-check 诊断规则
+### `threshold-check` 诊断规则
 
-threshold-check 诊断规则通过查询 metrics_schema 数据库中相关的监控系统表，检测集群中以下指标是否超出阈值：
+`threshold-check` 诊断规则通过查询 [metrics schema](/reference/system-databases/metrics-schema.md) 数据库中相关的监控系统表，检测集群中以下指标是否超出阈值：
 
 |  组件  | 监控指标 | 相关监控表 | 预期值 |  说明  |
-|  ----  | ----  |  ----  |  ----  |  ----  |
+|  :----  | :----  |  :----  |  :----  |  :----  |
 | TiDB | tso-duration              | pd_tso_wait_duration                | 小于 50 ms  |  获取事务 TSO 时间戳的耗时 |
-| TiDB | get-token-duration        | tidb_get_token_duration             | 小于 1 ms   |  查询获取 token 的耗时, 相关的 TiDB 配置参数是 token-limit  |
+| TiDB | get-token-duration        | tidb_get_token_duration             | 小于 1 ms   |  查询获取 token 的耗时，相关的 TiDB 配置参数是 token-limit  |
 | TiDB | load-schema-duration      | tidb_load_schema_duration           | 小于 1 s    |  TiDB 更新获取表元信息的耗时 |
 | TiKV | scheduler-cmd-duration    | tikv_scheduler_command_duration     | 小于 0.1 s  |  TiKV 执行 KV cmd 请求的耗时 |
 | TiKV | handle-snapshot-duration  | tikv_handle_snapshot_duration       | 小于 30 s   |  TiKV 处理 snapshot 的耗时 |
@@ -284,10 +284,10 @@ threshold-check 诊断规则通过查询 metrics_schema 数据库中相关的监
 | TiKV | filter-block-cache-hit | tikv_block_filter_cache_hit | 大于 0.95 | TiKV 中 filter block 缓存的命中率 |
 | TiKV | data-block-cache-hit | tikv_block_data_cache_hit | 大于 0.80 | TiKV 中 data block 缓存的命中率 |
 | TiKV | leader-score-balance | pd_scheduler_store_status  | 小于 0.05 | 检测各个 TiKV 节点的 leader score 是否均衡，期望节点间的差异小于 5% |
-| TiKV | region-score-balance | pd_scheduler_store_status  | 小于 0.05 | 检测各个 TiKV 节点的 region score 是否均衡，期望节点间的差异小于 5% |
+| TiKV | region-score-balance | pd_scheduler_store_status  | 小于 0.05 | 检测各个 TiKV 节点的 Region score 是否均衡，期望节点间的差异小于 5% |
 | TiKV | store-available-balance | pd_scheduler_store_status  | 小于 0.2 | 检测各个 TiKV 节点的存储可用空间大小是否均衡，期望节点间的差异小于 20% |
-| TiKV | region-count | pd_scheduler_store_status  | 小于 20000 | 检测各个 TiKV 节点的 region 数量，期望单个节点的 region 数量小于 20000 |
-| PD | region-health | pd_region_health | 小于 100  | 检测集群中处于调度中间状态的 region 数量，期望总数小于 100 |
+| TiKV | region-count | pd_scheduler_store_status  | 小于 20000 | 检测各个 TiKV 节点的 Region 数量，期望单个节点的 Region 数量小于 20000 |
+| PD | region-health | pd_region_health | 小于 100  | 检测集群中处于调度中间状态的 Region 数量，期望总数小于 100 |
 
 另外还会检测 TiKV 节点的以下 thread cpu usage 是否过高:
 
@@ -303,6 +303,4 @@ threshold-check 诊断规则通过查询 metrics_schema 数据库中相关的监
 * storage-readpool-low-cpu
 * split-check-cpu
 
-## 最后
-
-TiDB 内置的诊断规则还在不断的完善改进中，如果你也想到了一些诊断规则，非常欢迎给 TiDB 提 PR 或 ISSUE。
+TiDB 内置的诊断规则还在不断的完善改进中，如果你也想到了一些诊断规则，非常欢迎在 [tidb repository](https://github.com/pingcap/tidb) 下提 PR 或 Issue。