PD Control User Guide
As a command line tool of PD, PD Control obtains the state information of the cluster and tunes the cluster.
Install PD Control
Use TiUP command
To use PD Control, execute the tiup ctl:v<CLUSTER_VERSION> pd -u http://<pd_ip>:<pd_port> [-i]
command.
Download the installation package
To obtain pd-ctl
of the latest version, download the TiDB server installation package. pd-ctl
is included in the ctl-{version}-linux-{arch}.tar.gz
package.
Installation package | OS | Architecture | SHA256 checksum |
---|---|---|---|
https://download.pingcap.org/tidb-community-server-{version}-linux-amd64.tar.gz (pd-ctl) | Linux | amd64 | https://download.pingcap.org/tidb-community-server-{version}-linux-amd64.tar.gz.sha256 |
https://download.pingcap.org/tidb-community-server-{version}-linux-arm64.tar.gz (pd-ctl) | Linux | arm64 | https://download.pingcap.org/tidb-community-server-{version}-linux-arm64.tar.gz.sha256 |
Compile from source code
- Go 1.21 or later is required because the Go modules are used.
- In the root directory of the PD project, use the
make
ormake pd-ctl
command to compile and generatebin/pd-ctl
.
Usage
Single-command mode:
tiup ctl:v<CLUSTER_VERSION> pd store -u http://127.0.0.1:2379
Interactive mode:
tiup ctl:v<CLUSTER_VERSION> pd -i -u http://127.0.0.1:2379
Use environment variables:
export PD_ADDR=http://127.0.0.1:2379
tiup ctl:v<CLUSTER_VERSION> pd
Use TLS to encrypt:
tiup ctl:v<CLUSTER_VERSION> pd -u https://127.0.0.1:2379 --cacert="path/to/ca" --cert="path/to/cert" --key="path/to/key"
Command line flags
--cacert
- Specifies the path to the certificate file of the trusted CA in PEM format
- Default: ""
--cert
- Specifies the path to the certificate of SSL in PEM format
- Default: ""
--detach
/ -d
- Uses the single command line mode (not entering readline)
- Default: true
--help
/ -h
- Outputs the help information
- Default: false
--interact
/ -i
- Uses the interactive mode (entering readline)
- Default: false
--key
- Specifies the path to the certificate key file of SSL in PEM format, which is the private key of the certificate specified by
--cert
- Default: ""
--pd
/ -u
- Specifies the PD address
- Default address:
http://127.0.0.1:2379
- Environment variable:
PD_ADDR
--version
/ -V
- Prints the version information and exit
- Default: false
Command
cluster
Use this command to view the basic information of the cluster.
Usage:
>> cluster // To show the cluster information
{
"id": 6493707687106161130,
"max_peer_count": 3
}
config [show | set <option> <value> | placement-rules]
Use this command to view or modify the configuration information.
Usage:
>> config show // Display the config information of the scheduling
{
"replication": {
"enable-placement-rules": "true",
"isolation-level": "",
"location-labels": "",
"max-replicas": 3,
"strictly-match-label": "false"
},
"schedule": {
"enable-cross-table-merge": "true",
"high-space-ratio": 0.7,
"hot-region-cache-hits-threshold": 3,
"hot-region-schedule-limit": 4,
"leader-schedule-limit": 4,
"leader-schedule-policy": "count",
"low-space-ratio": 0.8,
"max-merge-region-keys": 200000,
"max-merge-region-size": 20,
"max-pending-peer-count": 64,
"max-snapshot-count": 64,
"max-store-down-time": "30m0s",
"merge-schedule-limit": 8,
"patrol-region-interval": "10ms",
"region-schedule-limit": 2048,
"region-score-formula-version": "v2",
"replica-schedule-limit": 64,
"scheduler-max-waiting-operator": 5,
"split-merge-interval": "1h0m0s",
"tolerant-size-ratio": 0
}
}
>> config show all // Display all config information
>> config show replication // Display the config information of replication
{
"max-replicas": 3,
"location-labels": "",
"isolation-level": "",
"strictly-match-label": "false",
"enable-placement-rules": "true"
}
>> config show cluster-version // Display the current version of the cluster, which is the current minimum version of TiKV nodes in the cluster and does not correspond to the binary version.
"5.2.2"
max-snapshot-count
controls the maximum number of snapshots that a single store receives or sends out at the same time. The scheduler is restricted by this configuration to avoid taking up normal application resources. When you need to improve the speed of adding replicas or balancing, increase this value.config set max-snapshot-count 64 // Set the maximum number of snapshots to 64max-pending-peer-count
controls the maximum number of pending peers in a single store. The scheduler is restricted by this configuration to avoid producing a large number of Regions without the latest log in some nodes. When you need to improve the speed of adding replicas or balancing, increase this value. Setting it to 0 indicates no limit.config set max-pending-peer-count 64 // Set the maximum number of pending peers to 64max-merge-region-size
controls the upper limit on the size of Region Merge (the unit is MiB). WhenregionSize
exceeds the specified value, PD does not merge it with the adjacent Region. Setting it to 0 indicates disabling Region Merge.config set max-merge-region-size 16 // Set the upper limit on the size of Region Merge to 16 MiBmax-merge-region-keys
controls the upper limit on the key count of Region Merge. WhenregionKeyCount
exceeds the specified value, PD does not merge it with the adjacent Region.config set max-merge-region-keys 50000 // Set the upper limit on keyCount to 50000split-merge-interval
controls the interval between thesplit
andmerge
operations on a same Region. This means the newly split Region won't be merged within a period of time.config set split-merge-interval 24h // Set the interval between `split` and `merge` to one dayenable-one-way-merge
controls whether PD only allows a Region to merge with the next Region. When you set it tofalse
, PD allows a Region to merge with the adjacent two Regions.config set enable-one-way-merge true // Enables one-way merging.enable-cross-table-merge
is used to enable the merging of cross-table Regions. When you set it tofalse
, PD does not merge the Regions from different tables. This option only works when key type is "table".config set enable-cross-table-merge true // Enable cross table merge.key-type
specifies the key encoding type used for the cluster. The supported options are ["table", "raw", "txn"], and the default value is "table".If no TiDB instance exists in the cluster,
key-type
will be "raw" or "txn", and PD is allowed to merge Regions across tables regardless of theenable-cross-table-merge
setting.If any TiDB instance exists in the cluster,
key-type
should be "table". Whether PD can merge Regions across tables is determined byenable-cross-table-merge
. Ifkey-type
is "raw", placement rules do not work.config set key-type raw // Enable cross table merge.
region-score-formula-version
controls the version of the Region score formula. The value options arev1
andv2
. The version 2 of the formula helps to reduce redundant balance Region scheduling in some scenarios, such as taking TiKV nodes online or offline.config set region-score-formula-version v2patrol-region-interval
controls the execution frequency thatreplicaChecker
checks the health status of Regions. A shorter interval indicates a higher execution frequency. Generally, you do not need to adjust it.config set patrol-region-interval 10ms // Set the execution frequency of replicaChecker to 10msmax-store-down-time
controls the time that PD decides the disconnected store cannot be restored if exceeded. If PD does not receive heartbeats from a store within the specified period of time, PD adds replicas in other nodes.config set max-store-down-time 30m // Set the time within which PD receives no heartbeats and after which PD starts to add replicas to 30 minutesmax-store-preparing-time
controls the maximum waiting time for the store to go online. During the online stage of a store, PD can query the online progress of the store. When the specified time is exceeded, PD assumes that the store has been online and cannot query the online progress of the store again. But this does not prevent Regions from transferring to the new online store. In most scenarios, you do not need to adjust this parameter.The following command specifies that the maximum waiting time for the store to go online is 4 hours.
config set max-store-preparing-time 4hleader-schedule-limit
controls the number of tasks scheduling the leader at the same time. This value affects the speed of leader balance. A larger value means a higher speed and setting the value to 0 closes the scheduling. Usually the leader scheduling has a small load, and you can increase the value in need.config set leader-schedule-limit 4 // 4 tasks of leader scheduling at the same time at mostregion-schedule-limit
controls the number of tasks of scheduling Regions at the same time. This value avoids too many Region balance operators being created. The default value is2048
which is enough for all sizes of clusters, and setting the value to0
closes the scheduling. Usually, the Region scheduling speed is limited bystore-limit
, but it is recommended that you do not customize this value unless you know exactly what you are doing.config set region-schedule-limit 2 // 2 tasks of Region scheduling at the same time at mostreplica-schedule-limit
controls the number of tasks scheduling the replica at the same time. This value affects the scheduling speed when the node is down or removed. A larger value means a higher speed and setting the value to 0 closes the scheduling. Usually the replica scheduling has a large load, so do not set a too large value. Note that this configuration item is usually kept at the default value. If you want to change the value, you need to try a few values to see which one works best according to the real situation.config set replica-schedule-limit 4 // 4 tasks of replica scheduling at the same time at mostmerge-schedule-limit
controls the number of Region Merge scheduling tasks. Setting the value to 0 closes Region Merge. Usually the Merge scheduling has a large load, so do not set a too large value. Note that this configuration item is usually kept at the default value. If you want to change the value, you need to try a few values to see which one works best according to the real situation.config set merge-schedule-limit 16 // 16 tasks of Merge scheduling at the same time at mosthot-region-schedule-limit
controls the hot Region scheduling tasks that are running at the same time. Setting its value to0
means disabling the scheduling. It is not recommended to set a too large value. Otherwise, it might affect the system performance. Note that this configuration item is usually kept at the default value. If you want to change the value, you need to try a few values to see which one works best according to the real situation.config set hot-region-schedule-limit 4 // 4 tasks of hot Region scheduling at the same time at mosthot-region-cache-hits-threshold
is used to set the number of minutes required to identify a hot Region. PD can participate in the hotspot scheduling only after the Region is in the hotspot state for more than this number of minutes.tolerant-size-ratio
controls the size of the balance buffer area. When the score difference between the leader or Region of the two stores is less than specified multiple times of the Region size, it is considered in balance by PD.config set tolerant-size-ratio 20 // Set the size of the buffer area to about 20 times of the average Region Sizelow-space-ratio
controls the threshold value that is considered as insufficient store space. When the ratio of the space occupied by the node exceeds the specified value, PD tries to avoid migrating data to the corresponding node as much as possible. At the same time, PD mainly schedules the remaining space to avoid using up the disk space of the corresponding node.config set low-space-ratio 0.9 // Set the threshold value of insufficient space to 0.9high-space-ratio
controls the threshold value that is considered as sufficient store space. This configuration takes effect only whenregion-score-formula-version
is set tov1
. When the ratio of the space occupied by the node is less than the specified value, PD ignores the remaining space and mainly schedules the actual data volume.config set high-space-ratio 0.5 // Set the threshold value of sufficient space to 0.5cluster-version
is the version of the cluster, which is used to enable or disable some features and to deal with the compatibility issues. By default, it is the minimum version of all normally running TiKV nodes in the cluster. You can set it manually only when you need to roll it back to an earlier version.config set cluster-version 1.0.8 // Set the version of the cluster to 1.0.8replication-mode
controls the replication mode of Regions in the dual data center scenario. See Enable the DR Auto-Sync mode for details.leader-schedule-policy
is used to select the scheduling strategy for the leader. You can schedule the leader according tosize
orcount
.scheduler-max-waiting-operator
is used to control the number of waiting operators in each scheduler.enable-remove-down-replica
is used to enable the feature of automatically deleting DownReplica. When you set it tofalse
, PD does not automatically clean up the downtime replicas.enable-replace-offline-replica
is used to enable the feature of migrating OfflineReplica. When you set it tofalse
, PD does not migrate the offline replicas.enable-make-up-replica
is used to enable the feature of making up replicas. When you set it tofalse
, PD does not add replicas for Regions without sufficient replicas.enable-remove-extra-replica
is used to enable the feature of removing extra replicas. When you set it tofalse
, PD does not remove extra replicas for Regions with redundant replicas.enable-location-replacement
is used to enable the isolation level checking. When you set it tofalse
, PD does not increase the isolation level of a Region replica through scheduling.enable-debug-metrics
is used to enable the metrics for debugging. When you set it totrue
, PD enables some metrics such asbalance-tolerant-size
.enable-placement-rules
is used to enable placement rules, which is enabled by default in v5.0 and later versions.store-limit-mode
is used to control the mode of limiting the store speed. The optional modes areauto
andmanual
. Inauto
mode, the stores are automatically balanced according to the load (deprecated).store-limit-version
controls the version of the store limit formula. In v1 mode, you can manually modify thestore limit
to limit the scheduling speed of a single TiKV. The v2 mode is an experimental feature. In v2 mode, you do not need to manually set thestore limit
value, as PD dynamically adjusts it based on the capability of TiKV snapshots. For more details, refer to Principles of store limit v2.config set store-limit-version v2 // using store limit v2PD rounds the lowest digits of the flow number, which reduces the update of statistics caused by the changes of the Region flow information. This configuration item is used to specify the number of lowest digits to round for the Region flow information. For example, the flow
100512
will be rounded to101000
because the default value is3
. This configuration replacestrace-region-flow
.For example, set the value of
flow-round-by-digit
to4
:config set flow-round-by-digit 4
config placement-rules [disable | enable | load | save | show | rule-group]
For the usage of config placement-rules [disable | enable | load | save | show | rule-group]
, see Configure placement rules.
health
Use this command to view the health information of the cluster.
Usage:
>> health // Display the health information
[
{
"name": "pd",
"member_id": 13195394291058371180,
"client_urls": [
"http://127.0.0.1:2379"
......
],
"health": true
}
......
]
hot [read | write | store| history <start_time> <end_time> [<key> <value>]]
Use this command to view the hot spot information of the cluster.
Usage:
>> hot read // Display hot spot for the read operation
>> hot write // Display hot spot for the write operation
>> hot store // Display hot spot for all the read and write operations
>> hot history 1629294000000 1631980800000 // Display history hot spot for the specified period (milliseconds). 1629294000000 is the start time and 1631980800000 is the end time.
{
"history_hot_region": [
{
"update_time": 1630864801948,
"region_id": 103,
"peer_id": 1369002,
"store_id": 3,
"is_leader": true,
"is_learner": false,
"hot_region_type": "read",
"hot_degree": 152,
"flow_bytes": 0,
"key_rate": 0,
"query_rate": 305,
"start_key": "7480000000000000FF5300000000000000F8",
"end_key": "7480000000000000FF5600000000000000F8"
},
...
]
}
>> hot history 1629294000000 1631980800000 hot_region_type read region_id 1,2,3 store_id 1,2,3 peer_id 1,2,3 is_leader true is_learner true // Display history hotspot for the specified period with more conditions
{
"history_hot_region": [
{
"update_time": 1630864801948,
"region_id": 103,
"peer_id": 1369002,
"store_id": 3,
"is_leader": true,
"is_learner": false,
"hot_region_type": "read",
"hot_degree": 152,
"flow_bytes": 0,
"key_rate": 0,
"query_rate": 305,
"start_key": "7480000000000000FF5300000000000000F8",
"end_key": "7480000000000000FF5600000000000000F8"
},
...
]
}
label [store <name> <value>]
Use this command to view the label information of the cluster.
Usage:
>> label // Display all labels
>> label store zone cn // Display all stores including the "zone":"cn" label
member [delete | leader_priority | leader [show | resign | transfer <member_name>]]
Use this command to view the PD members, remove a specified member, or configure the priority of leader.
Usage:
>> member // Display the information of all members
{
"header": {......},
"members": [......],
"leader": {......},
"etcd_leader": {......},
}
>> member delete name pd2 // Delete "pd2"
Success!
>> member delete id 1319539429105371180 // Delete a node using id
Success!
>> member leader show // Display the leader information
{
"name": "pd",
"member_id": 13155432540099656863,
"peer_urls": [......],
"client_urls": [......]
}
>> member leader resign // Move leader away from the current member
......
>> member leader transfer pd3 // Migrate leader to a specified member
......
operator [check | show | add | remove]
Use this command to view and control the scheduling operation.
Usage:
>> operator show // Display all operators
>> operator show admin // Display all admin operators
>> operator show leader // Display all leader operators
>> operator show region // Display all Region operators
>> operator add add-peer 1 2 // Add a replica of Region 1 on store 2
>> operator add add-learner 1 2 // Add a learner replica of Region 1 on store 2
>> operator add remove-peer 1 2 // Remove a replica of Region 1 on store 2
>> operator add transfer-leader 1 2 // Schedule the leader of Region 1 to store 2
>> operator add transfer-region 1 2 3 4 // Schedule Region 1 to stores 2,3,4
>> operator add transfer-peer 1 2 3 // Schedule the replica of Region 1 on store 2 to store 3
>> operator add merge-region 1 2 // Merge Region 1 with Region 2
>> operator add split-region 1 --policy=approximate // Split Region 1 into two Regions in halves, based on approximately estimated value
>> operator add split-region 1 --policy=scan // Split Region 1 into two Regions in halves, based on accurate scan value
>> operator remove 1 // Remove the scheduling operation of Region 1
>> operator check 1 // Check the status of the operators related to Region 1
The splitting of Regions starts from the position as close as possible to the middle. You can locate this position using two strategies, namely "scan" and "approximate". The difference between them is that the former determines the middle key by scanning the Region, and the latter obtains the approximate position by checking the statistics recorded in the SST file. Generally, the former is more accurate, while the latter consumes less I/O and can be completed faster.
ping
Use this command to view the time that ping
PD takes.
Usage:
>> ping
time: 43.12698ms
region <region_id> [--jq="<query string>"]
Use this command to view the Region information. For a jq formatted output, see jq-formatted-json-output-usage.
Usage:
>> region // Display the information of all Regions
{
"count": 1,
"regions": [......]
}
>> region 2 // Display the information of the Region with the ID of 2
{
"id": 2,
"start_key": "7480000000000000FF1D00000000000000F8",
"end_key": "7480000000000000FF1F00000000000000F8",
"epoch": {
"conf_ver": 1,
"version": 15
},
"peers": [
{
"id": 40,
"store_id": 3
}
],
"leader": {
"id": 40,
"store_id": 3
},
"written_bytes": 0,
"read_bytes": 0,
"written_keys": 0,
"read_keys": 0,
"approximate_size": 1,
"approximate_keys": 0
}
region key [--format=raw|encode|hex] <key>
Use this command to query the Region that a specific key resides in. It supports the raw, encoding, and hex formats. And you need to use single quotes around the key when it is in the encoding format.
Hex format usage (default):
>> region key 7480000000000000FF1300000000000000F8
{
"region": {
"id": 2,
......
}
}
Raw format usage:
>> region key --format=raw abc
{
"region": {
"id": 2,
......
}
}
Encoding format usage:
>> region key --format=encode 't\200\000\000\000\000\000\000\377\035_r\200\000\000\000\000\377\017U\320\000\000\000\000\000\372'
{
"region": {
"id": 2,
......
}
}
region scan
Use this command to get all Regions.
Usage:
>> region scan
{
"count": 20,
"regions": [......],
}
region sibling <region_id>
Use this command to check the adjacent Regions of a specific Region.
Usage:
>> region sibling 2
{
"count": 2,
"regions": [......],
}
region keys [--format=raw|encode|hex] <start_key> <end_key> <limit>
Use this command to query all Regions in a given range [startkey, endkey)
. Ranges without endKey
s are supported.
The limit
parameter limits the number of keys. The default value of limit
is 16
, and the value of -1
means unlimited keys.
Usage:
>> region keys --format=raw a // Display all Regions that start from the key a with a default limit count of 16
{
"count": 16,
"regions": [......],
}
>> region keys --format=raw a z // Display all Regions in the range [a, z) with a default limit count of 16
{
"count": 16,
"regions": [......],
}
>> region keys --format=raw a z -1 // Display all Regions in the range [a, z) without a limit count
{
"count": ...,
"regions": [......],
}
>> region keys --format=raw a "" 20 // Display all Regions that start from the key a with a limit count of 20
{
"count": 20,
"regions": [......],
}
region store <store_id>
Use this command to list all Regions of a specific store.
Usage:
>> region store 2
{
"count": 10,
"regions": [......],
}
region topread [limit]
Use this command to list Regions with top read flow. The default value of the limit is 16.
Usage:
>> region topread
{
"count": 16,
"regions": [......],
}
region topwrite [limit]
Use this command to list Regions with top write flow. The default value of the limit is 16.
Usage:
>> region topwrite
{
"count": 16,
"regions": [......],
}
region topconfver [limit]
Use this command to list Regions with top conf version. The default value of the limit is 16.
Usage:
>> region topconfver
{
"count": 16,
"regions": [......],
}
region topversion [limit]
Use this command to list Regions with top version. The default value of the limit is 16.
Usage:
>> region topversion
{
"count": 16,
"regions": [......],
}
region topsize [limit]
Use this command to list Regions with top approximate size. The default value of the limit is 16.
Usage:
>> region topsize
{
"count": 16,
"regions": [......],
}
region check [miss-peer | extra-peer | down-peer | pending-peer | offline-peer | empty-region | hist-size | hist-keys] [--jq="<query string>"]
Use this command to check the Regions in abnormal conditions. For a jq formatted output, see jq formatted JSON output usage.
Description of various types:
- miss-peer: the Region without enough replicas
- extra-peer: the Region with extra replicas
- down-peer: the Region in which some replicas are Down
- pending-peer: the Region in which some replicas are Pending
Usage:
>> region check miss-peer
{
"count": 2,
"regions": [......],
}
resource-manager [command]
View the controller configuration of Resource Control
resource-manager config controller show
{
"degraded-mode-wait-duration": "0s",
"ltb-max-wait-duration": "30s",
"request-unit": { # Configurations of RU. Do not modify.
"read-base-cost": 0.125,
"read-per-batch-base-cost": 0.5,
"read-cost-per-byte": 0.0000152587890625,
"write-base-cost": 1,
"write-per-batch-base-cost": 1,
"write-cost-per-byte": 0.0009765625,
"read-cpu-ms-cost": 0.3333333333333333
},
"enable-controller-trace-log": "false"
}
ltb-max-wait-duration
: the maximum waiting time of Local Token Bucket (LTB). The default value is30s
, and the value range is[0, 24h]
. If the estimated Request Unit (RU) consumption of the SQL request exceeds the current accumulated RU of LTB, the request needs to wait for a certain period of time. If the estimated waiting time exceeds this maximum value, an error messageERROR 8252 (HY000) : Exceeded resource group quota limitation
is returned to the application in advance. Increasing this value can reduce the occurrence of encounteringERROR 8252
in cases of sudden concurrency increase, large transactions, and large queries.enable-controller-trace-log
: control whether to enable the controller diagnostic log.
Modify the controller configuration of Resource Control
To modify the ltb-max-wait-duration
configuration, use the following command:
pd-ctl resource-manager config controller set ltb-max-wait-duration 30m
scheduler [show | add | remove | pause | resume | config | describe]
Use this command to view and control the scheduling policy.
Usage:
>> scheduler show // Display all created schedulers
>> scheduler add grant-leader-scheduler 1 // Schedule all the leaders of the Regions on store 1 to store 1
>> scheduler add evict-leader-scheduler 1 // Move all the Region leaders on store 1 out
>> scheduler config evict-leader-scheduler // Display the stores in which the scheduler is located since v4.0.0
>> scheduler config evict-leader-scheduler add-store 2 // Add leader eviction scheduling for store 2
>> scheduler config evict-leader-scheduler delete-store 2 // Remove leader eviction scheduling for store 2
>> scheduler add shuffle-leader-scheduler // Randomly exchange the leader on different stores
>> scheduler add shuffle-region-scheduler // Randomly schedule the Regions on different stores
>> scheduler add evict-slow-store-scheduler // When there is one and only one slow store, evict all Region leaders of that store
>> scheduler remove grant-leader-scheduler-1 // Remove the corresponding scheduler, and `-1` corresponds to the store ID
>> scheduler pause balance-region-scheduler 10 // Pause the balance-region scheduler for 10 seconds
>> scheduler pause all 10 // Pause all schedulers for 10 seconds
>> scheduler resume balance-region-scheduler // Continue to run the balance-region scheduler
>> scheduler resume all // Continue to run all schedulers
>> scheduler config balance-hot-region-scheduler // Display the configuration of the balance-hot-region scheduler
>> scheduler describe balance-region-scheduler // Display the running state and related diagnostic information of the balance-region scheduler
scheduler describe balance-region-scheduler
Use this command to view the running state and related diagnostic information of the balance-region-scheduler
.
Since TiDB v6.3.0, PD provides the running state and brief diagnostic information for balance-region-scheduler
and balance-leader-scheduler
. Other schedulers and checkers are not supported yet. To enable this feature, you can modify the enable-diagnostic
configuration item using pd-ctl
.
The state of the scheduler can be one of the following:
disabled
: the scheduler is unavailable or removed.paused
: the scheduler is paused.scheduling
: the scheduler is generating scheduling operators.pending
: the scheduler cannot generate scheduling operators. For a scheduler in thepending
state, brief diagnostic information is returned. The brief information describes the state of stores and explains why these stores cannot be selected for scheduling.normal
: there is no need to generate scheduling operators.
scheduler config balance-leader-scheduler
Use this command to view and control the balance-leader-scheduler
policy.
Since TiDB v6.0.0, PD introduces the Batch
parameter for balance-leader-scheduler
to control the speed at which the balance-leader processes tasks. To use this parameter, you can modify the balance-leader batch
configuration item using pd-ctl.
Before v6.0.0, PD does not have this configuration item, which means balance-leader batch=1
. In v6.0.0 or later versions, the default value of balance-leader batch
is 4
. To set this configuration item to a value greater than 4
, you need to set a greater value for scheduler-max-waiting-operator
(whose default value is 5
) at the same time. You can get the expected acceleration effect only after modifying both configuration items.
scheduler config balance-leader-scheduler set batch 3 // Set the size of the operator that the balance-leader scheduler can execute in a batch to 3
scheduler config balance-hot-region-scheduler
Use this command to view and control the balance-hot-region-scheduler
policy.
Usage:
>> scheduler config balance-hot-region-scheduler // Display all configuration of the balance-hot-region scheduler
{
"min-hot-byte-rate": 100,
"min-hot-key-rate": 10,
"min-hot-query-rate": 10,
"max-zombie-rounds": 3,
"max-peer-number": 1000,
"byte-rate-rank-step-ratio": 0.05,
"key-rate-rank-step-ratio": 0.05,
"query-rate-rank-step-ratio": 0.05,
"count-rank-step-ratio": 0.01,
"great-dec-ratio": 0.95,
"minor-dec-ratio": 0.99,
"src-tolerance-ratio": 1.05,
"dst-tolerance-ratio": 1.05,
"read-priorities": [
"query",
"byte"
],
"write-leader-priorities": [
"key",
"byte"
],
"write-peer-priorities": [
"byte",
"key"
],
"strict-picking-store": "true",
"enable-for-tiflash": "true",
"rank-formula-version": "v2"
}
min-hot-byte-rate
means the smallest number of bytes to be counted, which is usually 100.scheduler config balance-hot-region-scheduler set min-hot-byte-rate 100min-hot-key-rate
means the smallest number of keys to be counted, which is usually 10.scheduler config balance-hot-region-scheduler set min-hot-key-rate 10min-hot-query-rate
means the smallest number of queries to be counted, which is usually 10.scheduler config balance-hot-region-scheduler set min-hot-query-rate 10max-zombie-rounds
means the maximum number of heartbeats with which an operator can be considered as the pending influence. If you set it to a larger value, more operators might be included in the pending influence. Usually, you do not need to adjust its value. Pending influence refers to the operator influence that is generated during scheduling but still has an effect.scheduler config balance-hot-region-scheduler set max-zombie-rounds 3max-peer-number
means the maximum number of peers to be solved, which prevents the scheduler from being too slow.scheduler config balance-hot-region-scheduler set max-peer-number 1000byte-rate-rank-step-ratio
,key-rate-rank-step-ratio
,query-rate-rank-step-ratio
, andcount-rank-step-ratio
respectively mean the step ranks of byte, key, query, and count. The rank-step-ratio decides the step when the rank is calculated.great-dec-ratio
andminor-dec-ratio
are used to determine thedec
rank. Usually, you do not need to modify these items.scheduler config balance-hot-region-scheduler set byte-rate-rank-step-ratio 0.05src-tolerance-ratio
anddst-tolerance-ratio
are configuration items for the expectation scheduler. The smaller thetolerance-ratio
, the easier it is for scheduling. When redundant scheduling occurs, you can appropriately increase this value.scheduler config balance-hot-region-scheduler set src-tolerance-ratio 1.1read-priorities
,write-leader-priorities
, andwrite-peer-priorities
control which dimension the scheduler prioritizes for hot Region scheduling. Two dimensions are supported for configuration.read-priorities
andwrite-leader-priorities
control which dimensions the scheduler prioritizes for scheduling hot Regions of the read and write-leader types. The dimension options arequery
,byte
, andkey
.write-peer-priorities
controls which dimensions the scheduler prioritizes for scheduling hot Regions of the write-peer type. The dimension options arebyte
andkey
.scheduler config balance-hot-region-scheduler set read-priorities query,byte
strict-picking-store
controls the search space of hot Region scheduling. Usually, it is enabled. This configuration item only affects the behavior whenrank-formula-version
isv1
. When it is enabled, hot Region scheduling ensures hot Region balance on the two configured dimensions. When it is disabled, hot Region scheduling only ensures the balance on the dimension with the first priority, which might reduce balance on other dimensions. Usually, you do not need to modify this configuration.scheduler config balance-hot-region-scheduler set strict-picking-store truerank-formula-version
controls which scheduler algorithm version is used in hot Region scheduling. Value options arev1
andv2
. The default value isv2
.- The
v1
algorithm is the scheduler strategy used in TiDB v6.3.0 and earlier versions. This algorithm mainly focuses on reducing load difference between stores and avoids introducing side effects in the other dimension. - The
v2
algorithm is an experimental scheduler strategy introduced in TiDB v6.3.0 and is in General Availability (GA) in TiDB v6.4.0. This algorithm mainly focuses on improving the rate of the equitability between stores and factors in few side effects. Compared with thev1
algorithm withstrict-picking-store
beingtrue
, thev2
algorithm pays more attention to the priority equalization of the first dimension. Compared with thev1
algorithm withstrict-picking-store
beingfalse
, thev2
algorithm considers the balance of the second dimension. - The
v1
algorithm withstrict-picking-store
beingtrue
is conservative and scheduling can only be generated when there is a store with a high load in both dimensions. In certain scenarios, it might be impossible to continue balancing due to dimensional conflicts. To achieve better balancing in the first dimension, it is necessary to set thestrict-picking-store
tofalse
. Thev2
algorithm can achieve better balancing in both dimensions and reduce invalid scheduling.
scheduler config balance-hot-region-scheduler set rank-formula-version v2- The
enable-for-tiflash
controls whether hot Region scheduling takes effect for TiFlash instances. Usually, it is enabled. When it is disabled, the hot Region scheduling between TiFlash instances is not performed.scheduler config balance-hot-region-scheduler set enable-for-tiflash true
scheduler config evict-leader-scheduler
Use this command to view and manage the configuration of the evict-leader-scheduler
.
When an
evict-leader-scheduler
already exists, use theadd-store
subcommand to add leader eviction scheduling for the specified store:scheduler config evict-leader-scheduler add-store 2 // Add leader eviction scheduling for store 2When an
evict-leader-scheduler
already exists, use thedelete-store
subcommand to remove leader eviction scheduling for the specified store:scheduler config evict-leader-scheduler delete-store 2 // Remove leader eviction scheduling for store 2If all store configurations of an
evict-leader-scheduler
are removed, the scheduler itself is automatically removed.
service-gc-safepoint
Use this command to query the current GC safepoint and service GC safepoint. The output is as follows:
{
"service_gc_safe_points": [
{
"service_id": "gc_worker",
"expired_at": 9223372036854775807,
"safe_point": 439923410637160448
}
],
"gc_safe_point": 0
}
store [delete | cancel-delete | label | weight | remove-tombstone | limit ] <store_id> [--jq="<query string>"]
For a jq formatted output, see jq-formatted-json-output-usage.
Get a store
To display the information of all stores, run the following command:
store
{
"count": 3,
"stores": [...]
}
To get the store with id of 1, run the following command:
store 1
......
Delete a store
To delete the store with id of 1, run the following command:
store delete 1
To cancel deleting Offline
state stores which are deleted using store delete
, run the store cancel-delete
command. After canceling, the store changes from Offline
to Up
. Note that the store cancel-delete
command cannot change a Tombstone
state store to the Up
state.
To cancel deleting the store with id of 1, run the following command:
store cancel-delete 1
To delete all stores in Tombstone
state, run the following command:
store remove-tombstone
Manage store labels
To manage the labels of a store, run the store label
command.
To set a label with the key being
"zone"
and value being"cn"
to the store with id of 1, run the following command:store label 1 zone=cnTo update the label of a store, for example, changing the value of the key
"zone"
from"cn"
to"us"
for the store with id of 1, run the following command:store label 1 zone=usTo rewrite all labels of a store with id of 1, use the
--rewrite
option. Note that this option overwrites all existing labels:store label 1 region=us-est-1 disk=ssd --rewriteTo delete the
"disk"
label for the store with id of 1, use the--delete
option:store label 1 disk --delete
Configure store weight
To set the leader weight to 5 and Region weight to 10 for the store with id of 1, run the following command:
store weight 1 5 10
Configure store scheduling speed
You can set the scheduling speed of stores by using store limit
. For more details about the principles and usage of store limit
, see store limit
.
>> store limit // Show the speed limit of adding-peer operations and the limit of removing-peer operations per minute in all stores
>> store limit add-peer // Show the speed limit of adding-peer operations per minute in all stores
>> store limit remove-peer // Show the limit of removing-peer operations per minute in all stores
>> store limit all 5 // Set the limit of adding-peer operations to 5 and the limit of removing-peer operations to 5 per minute for all stores
>> store limit 1 5 // Set the limit of adding-peer operations to 5 and the limit of removing-peer operations to 5 per minute for store 1
>> store limit all 5 add-peer // Set the limit of adding-peer operations to 5 per minute for all stores
>> store limit 1 5 add-peer // Set the limit of adding-peer operations to 5 per minute for store 1
>> store limit 1 5 remove-peer // Set the limit of removing-peer operations to 5 per minute for store 1
>> store limit all 5 remove-peer // Set the limit of removing-peer operations to 5 per minute for all stores
log [fatal | error | warn | info | debug]
Use this command to set the log level of the PD leader.
Usage:
log warn
tso
Use this command to parse the physical and logical time of TSO.
Usage:
>> tso 395181938313123110 // Parse TSO
system: 2017-10-09 05:50:59 +0800 CST
logic: 120102
unsafe remove-failed-stores [store-ids | show]
Use this command to perform lossy recovery operations when permanently damaged replicas cause data to be unavailable. See the following example. The details are described in Online Unsafe Recovery
Execute Online Unsafe Recovery to remove permanently damaged stores:
unsafe remove-failed-stores 101,102,103
Success!
Show the current or historical state of Online Unsafe Recovery:
unsafe remove-failed-stores show
[
"Collecting cluster info from all alive stores, 10/12.",
"Stores that have reports to PD: 1, 2, 3, ...",
"Stores that have not reported to PD: 11, 12",
]
Jq formatted JSON output usage
Simplify the output of store
>> store --jq=".stores[].store | { id, address, state_name}"
{"id":1,"address":"127.0.0.1:20161","state_name":"Up"}
{"id":30,"address":"127.0.0.1:20162","state_name":"Up"}
...
Query the remaining space of the node
>> store --jq=".stores[] | {id: .store.id, available: .status.available}"
{"id":1,"available":"10 GiB"}
{"id":30,"available":"10 GiB"}
...
Query all nodes whose status is not Up
store --jq='.stores[].store | select(.state_name!="Up") | { id, address, state_name}'
{"id":1,"address":"127.0.0.1:20161""state_name":"Offline"}
{"id":5,"address":"127.0.0.1:20162""state_name":"Offline"}
...
Query all TiFlash nodes
store --jq='.stores[].store | select(.labels | length>0 and contains([{"key":"engine","value":"tiflash"}])) | { id, address, state_name}'
{"id":1,"address":"127.0.0.1:20161""state_name":"Up"}
{"id":5,"address":"127.0.0.1:20162""state_name":"Up"}
...
Query the distribution status of the Region replicas
>> region --jq=".regions[] | {id: .id, peer_stores: [.peers[].store_id]}"
{"id":2,"peer_stores":[1,30,31]}
{"id":4,"peer_stores":[1,31,34]}
...
Filter Regions according to the number of replicas
For example, to filter out all Regions whose number of replicas is not 3:
>> region --jq=".regions[] | {id: .id, peer_stores: [.peers[].store_id] | select(length != 3)}"
{"id":12,"peer_stores":[30,32]}
{"id":2,"peer_stores":[1,30,31,32]}
Filter Regions according to the store ID of replicas
For example, to filter out all Regions that have a replica on store30:
>> region --jq=".regions[] | {id: .id, peer_stores: [.peers[].store_id] | select(any(.==30))}"
{"id":6,"peer_stores":[1,30,31]}
{"id":22,"peer_stores":[1,30,32]}
...
You can also find out all Regions that have a replica on store30 or store31 in the same way:
>> region --jq=".regions[] | {id: .id, peer_stores: [.peers[].store_id] | select(any(.==(30,31)))}"
{"id":16,"peer_stores":[1,30,34]}
{"id":28,"peer_stores":[1,30,32]}
{"id":12,"peer_stores":[30,32]}
...
Look for relevant Regions when restoring data
For example, when [store1, store30, store31] is unavailable at its downtime, you can find all Regions whose Down replicas are more than normal replicas:
>> region --jq=".regions[] | {id: .id, peer_stores: [.peers[].store_id] | select(length as $total | map(if .==(1,30,31) then . else empty end) | length>=$total-length) }"
{"id":2,"peer_stores":[1,30,31,32]}
{"id":12,"peer_stores":[30,32]}
{"id":14,"peer_stores":[1,30,32]}
...
Or when [store1, store30, store31] fails to start, you can find Regions where the data can be manually removed safely on store1. In this way, you can filter out all Regions that have a replica on store1 but don't have other DownPeers:
>> region --jq=".regions[] | {id: .id, peer_stores: [.peers[].store_id] | select(length>1 and any(.==1) and all(.!=(30,31)))}"
{"id":24,"peer_stores":[1,32,33]}
When [store30, store31] is down, find out all Regions that can be safely processed by creating the remove-peer
Operator, that is, Regions with one and only DownPeer:
>> region --jq=".regions[] | {id: .id, remove_peer: [.peers[].store_id] | select(length>1) | map(if .==(30,31) then . else empty end) | select(length==1)}"
{"id":12,"remove_peer":[30]}
{"id":4,"remove_peer":[31]}
{"id":22,"remove_peer":[30]}
...