Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

tikv-control.md: update tikv-control.md for raft region #12056

Merged
merged 6 commits into from
Dec 5, 2022
Merged

tikv-control.md: update tikv-control.md for raft region #12056

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
05c2982
update tikv-control.md for raft region
HuSharp Nov 18, 2022
006e508
make ci happy
HuSharp Nov 18, 2022
f0bcf32
address comment
HuSharp Dec 5, 2022
ca38f71
unify tikv-ctl.md
HuSharp Dec 5, 2022
9513ad9
Apply suggestions from code review
Oreoxmt Dec 5, 2022
ce4b164
Apply suggestions from code review
Oreoxmt Dec 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
137 changes: 61 additions & 76 deletions tikv-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,7 @@ TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管

`tikv-ctl` 也集成在了 `tiup` 命令中。执行以下命令，即可调用 `tikv-ctl` 工具：

{{< copyable "shell-regular" >}}

```bash
```shell
tiup ctl:<cluster-version> tikv
```

Expand Down Expand Up @@ -121,8 +119,6 @@ tikv-ctl 提供以下两种运行模式：

除此之外，tikv-ctl 还有两个简单的命令 `--to-hex` 和 `--to-escaped`，用于对 key 的形式作简单的变换。一般使用 `escaped` 形式，示例如下：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --to-escaped 0xaaff
```
Expand All @@ -131,8 +127,6 @@ tikv-ctl --to-escaped 0xaaff
\252\377
```

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --to-hex "\252\377"
```
Expand All @@ -153,30 +147,67 @@ AAFF

`raft` 子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 **RegionLocalState**、**RaftLocalState** 和 **RegionApplyState** 三个结构体，及某一条 log 对应的 Entries。

你可以使用 `region` 和 `log` 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。其用法及输出内容如下所示：
可以使用 `region` 和 `log` 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。

对于 `region` 子命令：

- 要查看指定的 Region，可在命令中使用 `-r` 参数，多个 Region 以 `,` 分隔。也可以使用 `--all-regions` 参数来返回所有 Region（`-r` 与 `--all-regions` 不能同时使用）
- 要限制输出的 Region 的数量，可在命令中使用 `--limit` 参数（默认为 `16`）
- 要查询某个 key 范围中包含哪些 Region，可在命令中使用 `--start` 和 `--end` 参数（默认不限范围，采用 Hex 格式）

{{< copyable "shell-regular" >}}
需要输出 ID 为 `1239` 的 Region 时，用法及输出内容如下所示：

```shell
tikv-ctl --host 127.0.0.1:20160 raft region -r 2
tikv-ctl --host 127.0.0.1:20160 raft region -r 1239
```

```
region id: 2
region state key: \001\003\000\000\000\000\000\000\000\002\001
region state: Some(region {id: 2 region_epoch {conf_ver: 3 version: 1} peers {id: 3 store_id: 1} peers {id: 5 store_id: 4} peers {id: 7 store_id: 6}})
raft state key: \001\002\000\000\000\000\000\000\000\002\002
raft state: Some(hard_state {term: 307 vote: 5 commit: 314617} last_index: 314617)
apply state key: \001\002\000\000\000\000\000\000\000\002\003
apply state: Some(applied_index: 314617 truncated_state {index: 313474 term: 151})
"region id": 1239
"region state": {
id: 1239,
start_key: 7480000000000000FF4E5F728000000000FF1443770000000000FA,
end_key: 7480000000000000FF4E5F728000000000FF21C4420000000000FA,
region_epoch: {conf_ver: 1 version: 43},
peers: [ {id: 1240 store_id: 1 role: Voter} ]
}
"raft state": {
hard_state {term: 8 vote: 5 commit: 7}
last_index: 8)
}
"apply state": {
applied_index: 8 commit_index: 8 commit_term: 8
truncated_state {index: 5 term: 5}
}
```

需要查询某个 key 范围中包含哪些 Region 时，用法及输出内容如下所示：

- 当 key 范围包含在某个 Region 中时，将会输出该 Region 信息。
- 当 key 范围精准到某个 Region 的范围时，以上述 Region `1239` 为例：当给定的 key 范围为 Region `1239` 的范围时，由于 Region 范围为左闭右开区间，并且 Region `1009` 以 Region `1239` 的 `end_key` 作为 `start_key`，因此会同时输出 Region `1009` 和 Region `1239` 的信息。

```shell
tikv-ctl --host 127.0.0.1:20160 raft region --start 7480000000000000FF4E5F728000000000FF1443770000000000FA --end 7480000000000000FF4E5F728000000000FF21C4420000000000FA
```

```
"region state": {
id: 1009
start_key: 7480000000000000FF4E5F728000000000FF21C4420000000000FA,
end_key: 7480000000000000FF5000000000000000F8,
...
}
"region state": {
id: 1239
start_key: 7480000000000000FF4E5F728000000000FF06C6D60000000000FA,
end_key: 7480000000000000FF4E5F728000000000FF1443770000000000FA,
...
}
```

### 查看 Region 的大小

使用 `size` 命令可以查看 Region 的大小：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv size -r 2
```
Expand All @@ -192,8 +223,6 @@ cf lock region size: 27616

`scan` 命令的 `--from` 和 `--to` 参数接受两个 escaped 形式的 raw key，并用 `--show-cf` 参数指定只需要查看哪些列族。

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv scan --from 'zm' --limit 2 --show-cf lock,default,write
```
Expand All @@ -210,8 +239,6 @@ key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\00

与 `scan` 命令类似，`mvcc` 命令可以查看给定 key 的 MVCC：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv mvcc -k "zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371" --show-cf=lock,write,default
```
Expand All @@ -238,10 +265,8 @@ key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\00
- 要限制能够打印出的 key 的数量（默认为 `30`），可在命令中使用 `--limit` 参数
- 要指定扫描的 CF，可在命令中使用 `--cf` 参数（可选值为 `default`，`write`，`lock`）

{{< copyable "shell-regular" >}}

```bash
$ ./tikv-ctl --data-dir /var/lib/tikv raw-scan --from 'zt' --limit 2 --cf default
```shell
tikv-ctl --data-dir /var/lib/tikv raw-scan --from 'zt' --limit 2 --cf default
```

```
Expand All @@ -259,8 +284,6 @@ Total scanned keys: 2

为了记录 Region 的状态信息，TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 `region-properties` 运行 tikv-ctl 来查看这些 properties 信息。例如：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host localhost:20160 region-properties -r 2
```
Expand Down Expand Up @@ -293,8 +316,6 @@ middle_key_by_approximate_size:
- `skip` 表示 compact 不包括最下层文件。
- `force` 表示 compact 总是包括最下层文件。

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv compact -d kv
```
Expand All @@ -321,8 +342,6 @@ pd-ctl>> operator add remove-peer <region_id> <store_id>

然后再用 tikv-ctl 在那个 TiKV 实例上将 Region 的副本标记为 tombstone 以便跳过启动时对他的健康检查：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv tombstone -p 127.0.0.1:2379 -r <region_id>
```
Expand All @@ -333,8 +352,6 @@ success!

但是有些情况下，当不能方便地从 PD 上移除这个副本时，可以指定 tikv-ctl 的 `--force` 选项来强制设置它为 tombstone：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv tombstone -p 127.0.0.1:2379 -r <region_id>,<region_id> --force
```
Expand All @@ -352,8 +369,6 @@ success!

`consistency-check` 命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败，TiKV 自身会 panic。如果 `--host` 指定的 TiKV 不是这个 Region 的 Leader，则会报告错误。

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2
```
Expand All @@ -362,8 +377,6 @@ tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2
success!
```

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host 127.0.0.1:20161 consistency-check -r 2
```
Expand All @@ -386,8 +399,6 @@ DebugClient::check_region_consistency: RpcFailure(RpcStatus { status: Unknown, d

前面 `tombstone` 命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态，避免 TiKV 启动时对它们进行检查。在运行 `tombstone` 命令之前，可使用 `bad-regions` 命令找到出错的 Region，以便将多个工具组合起来进行自动化的处理。

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv bad-regions
```
Expand All @@ -402,16 +413,12 @@ all regions are healthy

- 本地查看部署在 `/path/to/tikv` 的 TiKV 上面 Region 2 的 properties 信息：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv/data region-properties -r 2
```

- 在线查看运行在 `127.0.0.1:20160` 的 TiKV 上面 Region 2 的 properties 信息：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host 127.0.0.1:20160 region-properties -r 2
```
Expand All @@ -425,8 +432,6 @@ all regions are healthy

设置 `shared block cache` 的大小：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host ip:port modify-tikv-config -n storage.block-cache.capacity -v 10GB
```
Expand All @@ -437,8 +442,6 @@ success

当禁用 `shared block cache` 时，为 `write` CF 设置 `block cache size`：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host ip:port modify-tikv-config -n rocksdb.writecf.block-cache-size -v 256MB
```
Expand All @@ -447,8 +450,6 @@ tikv-ctl --host ip:port modify-tikv-config -n rocksdb.writecf.block-cache-size -
success
```

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host ip:port modify-tikv-config -n raftdb.defaultcf.disable-auto-compactions -v true
```
Expand All @@ -457,8 +458,6 @@ tikv-ctl --host ip:port modify-tikv-config -n raftdb.defaultcf.disable-auto-comp
success
```

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host ip:port modify-tikv-config -n raftstore.sync-log -v false
```
Expand All @@ -469,8 +468,6 @@ success

如果 compaction 的流量控制导致待 compact 数据量 (compaction pending bytes) 堆积，可以禁用 `rate-limiter-auto-tuned` 配置项或调高 compaction 相关的流量阈值。示例如下：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host ip:port modify-tikv-config -n rocksdb.rate-limiter-auto-tuned -v false
```
Expand All @@ -479,8 +476,6 @@ tikv-ctl --host ip:port modify-tikv-config -n rocksdb.rate-limiter-auto-tuned -v
success
```

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --host ip:port modify-tikv-config -n rocksdb.rate-bytes-per-sec -v "1GB"
```
Expand All @@ -505,8 +500,6 @@ success
> - 如果使用 `--all-regions`，必须在剩余所有连入集群的 store 上执行此命令。需要保证这些健康的 store 都停掉服务后再进行恢复，否则期间 Region 副本之间的 peer 列表不一致会导致执行 `split-region` 或者 `remove-peer` 时报错进而引起其他元数据的不一致，最终引发 Region 不可用。
> - 一旦执行了 `remove-fail-stores`，不可再重新启动被移除的节点并将其加入集群，否则会导致元数据的不一致，最终引发 Region 不可用。

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv unsafe-recover remove-fail-stores -s 3 -r 1001,1002
```
Expand All @@ -515,8 +508,6 @@ tikv-ctl --data-dir /path/to/tikv unsafe-recover remove-fail-stores -s 3 -r 1001
success!
```

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv unsafe-recover remove-fail-stores -s 4,5 --all-regions
```
Expand All @@ -535,8 +526,6 @@ tikv-ctl --data-dir /path/to/tikv unsafe-recover remove-fail-stores -s 4,5 --all
- `-r` 选项可以通过 `region_id` 指定包含的 Region。
- `-p` 选项可以指定 PD 的 endpoints。

{{< copyable "shell-regular" >}}

```shell
tikv-ctl --data-dir /path/to/tikv recover-mvcc -r 1001,1002 -p 127.0.0.1:2379
```
Expand All @@ -559,16 +548,12 @@ success!

用 HEX 格式 dump 现有 RocksDB 数据：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl ldb --hex --db=/tmp/db dump
```

Dump 现有 RocksDB 的声明：

{{< copyable "shell-regular" >}}

```shell
tikv-ctl ldb --hex manifest_dump --path=/tmp/db/MANIFEST-000001
```
Expand All @@ -591,8 +576,8 @@ data-dir = "/path/to/tikv/data"

`--path` 选项可以指定数据文件的绝对或者相对路径。如果指定的文件是明文存储的，本命令有可能没有输出。如果不指定 `--path` 选项，本命令打印所有数据文件的加密信息。

```bash
$ tikv-ctl --config=./conf.toml encryption-meta dump-file --path=/path/to/tikv/data/db/CURRENT
```shell
tikv-ctl --config=./conf.toml encryption-meta dump-file --path=/path/to/tikv/data/db/CURRENT
/path/to/tikv/data/db/CURRENT: key_id: 9291156302549018620 iv: E3C2FDBF63FC03BFC28F265D7E78283F method: Aes128Ctr
```

Expand All @@ -615,16 +600,16 @@ region = "us-west-2"

本命令会输出一个警告，提示本命令会泄漏敏感数据。根据提示输入 "I consent" 即可。

```bash
$ ./tikv-ctl --config=./conf.toml encryption-meta dump-key
```shell
tikv-ctl --config=./conf.toml encryption-meta dump-key
This action will expose encryption key(s) as plaintext. Do not output the result in file on disk.
Type "I consent" to continue, anything else to exit: I consent
current key id: 9291156302549018620
9291156302549018620: key: 8B6B6B8F83D36BE2467ED55D72AE808B method: Aes128Ctr creation_time: 1592938357
```

```bash
$ ./tikv-ctl --config=./conf.toml encryption-meta dump-key --ids=9291156302549018620
```shell
tikv-ctl --config=./conf.toml encryption-meta dump-key --ids=9291156302549018620
This action will expose encryption key(s) as plaintext. Do not output the result in file on disk.
Type "I consent" to continue, anything else to exit: I consent
9291156302549018620: key: 8B6B6B8F83D36BE2467ED55D72AE808B method: Aes128Ctr creation_time: 1592938357
Expand All @@ -644,11 +629,11 @@ TiKV 中损坏的 SST 文件会导致 TiKV 进程崩溃。在 TiDB v6.1.0 之前
>
> 执行此命令前，请保证关闭当前运行的 TiKV 实例。

```bash
$ tikv-ctl bad-ssts --data-dir </path/to/tikv> --pd <endpoint>
```shell
tikv-ctl bad-ssts --data-dir </path/to/tikv> --pd <endpoint>
```

```bash
```shell
--------------------------------------------------------
corruption info:
data/tikv-21107/db/000014.sst: Corruption: Bad table magic number: expected 9863518390377041911, found 759105309091689679 in data/tikv-21107/db/000014.sst
Expand Down