update v2.1, v3.0 and v3.1

dev/glossary.md

@@ -22,7 +22,7 @@ An operator can be computed and generated by a [scheduler](#scheduler), or creat
 
 ### Operator step
 
-An Operator step is a step in the execution of an Operator. An operator normally contains multiple Operator steps.
+An operator step is a step in the execution of an operator. An operator normally contains multiple Operator steps.
 
 Currently, available steps generated by PD include:
 

dev/reference/best-practices/pd-scheduling.md

@@ -169,7 +169,7 @@ PD supports dynamically adding and removing schedulers directly through pd-ctl.
 
 ### Add/delete Operators manually
 
-PD also supports adding or removing Operators directly through pd-ctl. For example:
+PD also supports adding or removing operators directly through pd-ctl. For example:
 
 - `operator add add-peer 2 5`: Adds peers to Region 2 in Store 5
 - `operator add transfer-leader 2 5`: Migrates the leader of Region 2 to Store 5
@@ -205,11 +205,11 @@ If the scores of different stores are close, it means PD mistakenly believes tha
 
 If there is a big difference in the rating of different stores, you need to examine the operator-related metrics, with special focus on the generation and execution of operators. There are two main situations:
 
-- When Operators are generated normally but the scheduling process is slow, it is possible that:
+- When operators are generated normally but the scheduling process is slow, it is possible that:
 
     - The scheduling speed is limited by default for load balancing purpose. You can adjust `leader-schedule-limit` or `region-schedule-limit` to larger values without significantly impacting regular services. In addition, you can also properly ease the restrictions specified by `max-pending-peer-count` and `max-snapshot-count`.
     - Other scheduling tasks are running concurrently, which slows down the balancing. In this case, if the balancing takes precedence over other scheduling tasks, you can stop other tasks or limit their speeds. For example, if you take some nodes offline when balancing is in progress, both operations consume the quota of `region-schedule-limit`. In this case, you can limit the speed of scheduler to remove nodes, or simply set `disable-replace-offline-replica = true` to temporarily disable it.
-    - The scheduling process is too slow. You can check the **Operator Step duration** metric to confirm the cause. Generally, steps that do not involve sending and receiving snapshots (such as `TransferLeader`, `RemovePeer`, `PromoteLearner`) should be completed in milliseconds, while steps that involve snapshots (such as `AddLearner` and `AddPeer`) are expected to be completed in tens of seconds. If the duration is obviously too long, it could be caused by high pressure on TiKV or bottleneck in network, etc., which needs specific analysis.
+    - The scheduling process is too slow. You can check the **Operator step duration** metric to confirm the cause. Generally, steps that do not involve sending and receiving snapshots (such as `TransferLeader`, `RemovePeer`, `PromoteLearner`) should be completed in milliseconds, while steps that involve snapshots (such as `AddLearner` and `AddPeer`) are expected to be completed in tens of seconds. If the duration is obviously too long, it could be caused by high pressure on TiKV or bottleneck in network, etc., which needs specific analysis.
 
 - PD fails to generate the corresponding balancing scheduler. Possible reasons include:
 
@@ -248,7 +248,7 @@ Hot regions scheduling issues generally fall into the following categories:
 
 - The load of some nodes is significantly higher than that of other nodes from TiKV-related metrics, which becomes the bottleneck of the whole system. Currently, PD counts hotspots through traffic analysis only, so it is possible that PD fails to identify hotspots in certain scenarios. For example, when there are intensive point lookup requests for some regions, it might not be obvious to detect in traffic, but still the high QPS might lead to bottlenecks in key modules.
 
-    **Solutions**: Firstly, locate the table where hot regions are formed based on the specific business. Then add a `scatter-range-scheduler` scheduler to make all Regions of this table evenly distributed. TiDB also provides an interface in its HTTP API to simplify this operation. Refer to [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) for more details.
+    **Solutions**: Firstly, locate the table where hot regions are formed based on the specific business. Then add a `scatter-range-scheduler` scheduler to make all regions of this table evenly distributed. TiDB also provides an interface in its HTTP API to simplify this operation. Refer to [TiDB HTTP API](https://github.com/pingcap/tidb/blob/master/docs/tidb_http_api.md) for more details.
 
 ### Region merge is slow
 

v2.1/glossary.md

@@ -0,0 +1,67 @@
+---
+title: Glossary
+summary: Glossaries about TiDB.
+category: glossary
+---
+
+# Glossary
+
+## L
+
+### leader/follower/learner
+
+Leader/Follower/Learner each corresponds to a role in a Raft group of [peers](#regionpeerraft-group). The leader services all client requests and replicates data to the followers. If the group leader fails, one of the followers will be elected as the new leader. Learners are non-voting followers that only serves in the process of replica addition.
+
+## O
+
+### Operator
+
+An operator is a collection of actions that applies to a region for scheduling purposes. Operators perform scheduling tasks such as "migrate the leader of Region 2 to Store 5" and "migrate replicas of Region 2 to Store 1, 4, 5".
+
+An operator can be computed and generated by a [scheduler](#scheduler), or created by an external API.
+
+### Operator step
+
+An operator step is a step in the execution of an operator. An operator normally contains multiple Operator steps.
+
+Currently, available steps generated by PD include:
+
+- `TransferLeader`: Transfers leadership to a specified member
+- `AddPeer`: Adds peers to a specified store
+- `RemovePeer`: Removes a peer of a region
+- `AddLearner`: Adds learners to a specified store
+- `PromoteLearner`: Promotes a specified learner to a voting member
+- `SplitRegion`: Splits a specified region into two
+
+## P
+
+### pending/down
+
+"Pending" and "down" are two special states of a peer. Pending indicates that the Raft log of followers or learners is vastly different from that of leader. Followers in pending cannot be elected as leader. "Down" refers to a state that a peer ceases to respond to leader for a long time, which usually means the corresponding node is down or isolated from the network.
+
+## R
+
+### region/peer/Raft group
+
+Region is the minimal piece of data storage in TiKV, each representing a range of data (96 MiB by default). Each region has three replicas by default. A replica of a region is called a peer. Multiple peers of the same region replicate data via the Raft consensus algorithm, so peers are also members of a Raft instance. TiKV uses Multi-Raft to manage data. That is, for each region, there is a corresponding, isolated Raft group.
+
+### region split
+
+Regions are generated as data writes increase. The process of splitting is called region split.
+
+The mechanism of region split is to use one initial region to cover the entire key space, and generate new regions through splitting existing ones every time the size of the region or the number of keys has reached a threshold.
+
+## S
+
+### scheduler
+
+Schedulers are components in PD that generate scheduling tasks. Each scheduler in PD runs independently and serves different purposes. The commonly used schedulers are:
+
+- `balance-leader-scheduler`: Balances the distribution of leaders
+- `balance-region-scheduler`: Balances the distribution of peers
+- `hot-region-scheduler`: Balances the distribution of hot regions
+- `evict-leader-{store-id}`: Evicts all leaders of a node (often used for rolling upgrades)
+
+### Store
+
+A store refers to the storage node in the TiKV cluster (an instance of `tikv-server`). Each store has a corresponding TiKV instance.