数据库｜TiDB-Server API的高效应用指南

一、API介绍

1.Status

显示TiDB 连接数、版本和git_hash 信息

tidb-server_ip:status_port/status

{
"connections": 0,
"version": "5.7.25-TiDB-v6.1.1",
"git_hash": "5263a0abda61f102122735049fd0dfadc7b7f822"
}

2.Status

显示tidb所有的监控指标信息

tidb-server_ip:status_port/metrics

# HELP br_raw_backup_region_seconds Backup region latency distributions.
# TYPE br_raw_backup_region_seconds histogram
br_raw_backup_region_seconds_bucket{le="0.05"} 0
br_raw_backup_region_seconds_bucket{le="0.1"} 0
br_raw_backup_region_seconds_bucket{le="0.2"} 0
br_raw_backup_region_seconds_bucket{le="0.4"} 0
br_raw_backup_region_seconds_bucket{le="0.8"} 0
br_raw_backup_region_seconds_bucket{le="1.6"} 0
br_raw_backup_region_seconds_bucket{le="3.2"} 0
br_raw_backup_region_seconds_bucket{le="6.4"} 0

3.StatsDump

获取指定表的统计信息

直接访问会返回表不存在，原因是他的语法为/stats/dump/{db}/{table}

[schema:1146]Table '{db}.{table}'doesn't exist

e.g:tidb-server_ip:status_port/stats/dump/tpcc/item

{
"database_name": "tpcc",
"table_name": "item",
"columns": {
"i_data": {
"histogram": {
"ndv": 99072,
"buckets": [
{
"count": 390,
"lower_bound": "MDAxaHFvVW14YW9iUVAxSVRYWHlLMXc4TXJxwjA4RG1BaA==",
"upper_bound": "MEZWb0V6a2RiNmNuNFJoTmFZVkRqbHZ4b0hhUjN6WktuaFVFUkl6cHZlSUh1eGg=",
"repeats": 1,
"ndv": 0
},
......

4.StatsHistoryDump

获取指定表的历史统计信息

直接访问返回

[types:1292]Incorrect datetime value: '{snapshot}'

正确的语法为

/stats/dump/{db}/{table}/{yyyy-MM-dd HH:mm:ss}

/stats/dump/{db}/{table}/{yyyyMMddHHmmss}

e.g:tidb-server_ip:status_port/stats/dump/tpcc/item/2023-12-19 10:00:39

{
"database_name": "tpcc",
"table_name": "item",
"columns": {
"i_data": {
"histogram": {
"ndv": 99072,
"buckets": [
{
"count": 390,
"lower_bound": "MDAxaHFvVW14YW9iUVAxSVRYWHlLMXc4TXJxSjA4RG1BaA==",
"upper_bound": "MEZWb0V6a2RiNmNuNFJoTmFZVkRqbHZ4b0hhUjN6WktuaFVFUkl6cHZlSUh1eGg=",
"repeats": 1,
"ndv": 0
},
{
"count": 781,
"lower_bound": "MEZmRTV5VDdaZkNZMktTOTFCZ3FKTmhzZFdOTlZHNjhw",
"upper_bound": "MFVaTnc4UHdPOWlFMk8zbkdHZUdUbmZxcVNWVldqdFl5VE1lVmpXN2FWeG4=",
"repeats": 1,
"ndv": 0
},
......

5.PlanReplayerDump

保存和恢复集群现场信息

PLAN REPLAYER DUMP EXPLAIN [ANALYZE] sql-statement;

TiDB 根据 sql-statement 整理出以下集群现场信息：

TiDB 版本信息

TiDB 配置信息

TiDB Session 系统变量

TiDB 执行计划绑定信息（SQL Binding）

sql-statement 中所包含的表结构

sql-statement 中所包含表的统计信息

EXPLAIN [ANALYZE] sql-statement 的结果

PLAN REPLAYER 不会导出表中数据

tidb_last_plan_replayer_token 这个会话变量可以获取上一次 PLAN REPLAYER dump 执行的结果。（v6.5 以上版本有此变量）

MySQL [test]> plan replayer dump explain select * fromt1;
+-----------------------------------------------------------+
| File_token |
+-----------------------------------------------------------+
| replayer_xyUNbajB-Kx_rmD_Norcnw==_1702952402658503693.zip |
+-----------------------------------------------------------+
1row inset(0.06sec)

MySQL [test]> SELECT @@tidb_last_plan_replayer_token;
+-----------------------------------------------------------+
| @@tidb_last_plan_replayer_token |
+-----------------------------------------------------------+
| replayer_xyUNbajB-Kx_rmD_Norcnw==_1702952402658503693.zip |
+-----------------------------------------------------------+
1row inset(0.00sec)

ZIP 文件最多会在 TiDB 集群中保存一个小时，超时后 TiDB 会将其删除。

plan replayer dump explain 'tidbsqls.txt';

多条 SQL 语句可以写在文件中以 ; 进行分隔。

通过http下载文件

http://${tidb-server-ip}:${tidb-server-status-port}/plan_replayer/dump/${file_token}

将导出的文件导入的另一个集群，导入完毕后，该 TiDB 集群就载入了所需要的表结构、统计信息等其他影响构造 Plan 所需要的信息。

PLAN REPLAYER LOAD 'plan_replayer.zip';

6.Settings

tidb-server 的所有配置信息

tidb-server_ip:status_port/settings

7.BinlogRecover

恢复 Pump 后恢复 binlog 写入。

返回值：

超时，返回状态码：400，消息：timeout

如果正常返回，状态码：200

默认情况下，API 将在等待所有跳过的二进制日志事务提交后返回。如果此值大于 0，则表示需要等到它们提交完毕。

消息示例：false表示当前binlog不处于跳过状态，否则为跳过状态：表示当前处于跳过状态的事务数。

{
"Skipped": false,
"SkippedCommitterCounter": 0
}

8.Schema

获取集群所有databases的详细信息

tidb-server_ip:status_port/schema

[
{
"id": 1,
"db_name": {
"O": "test",
"L": "test"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
"state": 5,
"policy_ref_info": null
},
{
"id": 3,
"db_name": {
"O": "mysql",
"L": "mysql"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
"state": 5,
"policy_ref_info": null
},
......

tidb-server_ip:status_port/schema/{db}

查看指定database的详细信息，如该db下所有的table详细信息。

[
{
"id": 147,
"name": {
"O": "t2",
"L": "t2"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
"cols": [
{
"id": 1,
"name": {
"O": "id",
"L": "id"
},
"offset": 0,
"origin_default": null,
"origin_default_bit": null,
"default": null,
"default_bit": null,
"default_is_expr": false,
"generated_expr_string": "",
"generated_stored": false,
"dependences": null,
"type": {
"Tp": 3,
"Flag": 4099,
"Flen": 11,
"Decimal": 0,
"Charset": "binary",
"Collate": "binary",
"Elems": null,
"ElemsIsBinaryLit": null,
"Array": false
},
"state": 5,
"comment": "",
"hidden": false,
"change_state_info": null,
"version": 2
},
......

通过table_name 来获取table的详细信息

tidb-server_ip:status_port/schema/{db}/{table}

可以通过 tableID 获取 schema 信息（tableID 是 Table 在 TiDB 中的唯一标识符）

tidb-server_ip:status_port/schema?table_id={tableID}

{
"id": 147,
"name": {
"O": "t2",
"L": "t2"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
"cols": [
{
"id": 1,
"name": {
"O": "id",
"L": "id"
},

......

通过 tableID 获取db_info、table_info和tidb info schema version

tidb-server_ip:status_port/db-table/{tableID}

与上面的获取table的详细信息相比多了db_info和schema version信息。

{
"db_info": {
"id": 1,
"db_name": {
"O": "test",
"L": "test"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
"state": 5,
"policy_ref_info": null
},
......
......
"schema_version": 119
}

9.Schema Storage

获取集群所有table的信息

tidb-server_ip:status_port/schema_storage

[
{
"table_schema": "INFORMATION_SCHEMA",
"table_name": "CLIENT_ERRORS_SUMMARY_GLOBAL",
"table_rows": 0,
"avg_row_length": 0,
"data_length": 0,
"max_data_length": 0,
"index_length": 0,
"data_free": 0
},
......

也可以指定获取指定database或者table的信息

获取db下所有table的信息

tidb-server_ip:status_port/schema_storage/{db}

获取指定table的信息

tidb-server_ip:status_port/schema_storage/{db}/{table}

{ 
"table_schema": "test",
"table_name": "t1",
"table_rows": 4,
"avg_row_length": 8,
"data_length": 32,
"max_data_length": 0,
"index_length": 0,
"data_free": 0
}

10.DDL_History

获取所有 TiDB DDL 历史记录

tidb-server_ip:status_port/ddl/history

[
{
"id": 2,
"type": 1,
"schema_id": 1,
"table_id": 0,
"schema_name": "test",
"table_name": "",
"state": 6,
"warning": null,
"err": null,
"err_count": 0,
"row_count": 0,
"raw_args": null,
"schema_state": 5,
"snapshot_ver": 0,
"real_start_ts": 0,
"start_ts": 444336503938613250,
"dependency_id": 0,
"query": "CREATE DATABASE IF NOT EXISTS test",
"binlog": {
"SchemaVersion": 1,
"DBInfo": {
"id": 1,
"db_name": {
"O": "test",
"L": "test"
},
"charset": "utf8mb4",
"collate": "utf8mb4_bin",
"state": 5,
"policy_ref_info": null
},
"TableInfo": null,
"FinishedTS": 444336503965089800,
"MultipleTableInfos": null
},
"version": 1,
"reorg_meta": null,
"multi_schema_info": null,
"priority": 0,
"seq_num": 0,
"charset": "",
"collate": "",
"admin_operator": 0
},
......

11.DDL_Owner_Resign

辞去 ddl owner 的职务，让 tidb 开始新的 ddl owner 选举

curl -X POST http://{TiDBIP}:10080/ddl/owner/resign

注意：如果你请求的 TiDB 不是 ddl owner，则响应为This node is not a ddl owner, can't be resigned.

http://12.Info

tidb-server_ip:status_port/info

获取tidb-server的相关信息

{
"is_owner": true,
"max_procs": 4,
"gogc": 500,
"version": "5.7.25-TiDB-v7.1.0",
"git_hash": "635a4362235e8a3c0043542e62953e3c7bb2756",
"ddl_id": "39844a19-b9d7-4f39-b21a-9beb5ffec18",
"ip": "10.0.0.1",
"listening_port": 5000,
"status_port": 20080,
"lease": "45s",
"binlog_status": "On",
"start_timestamp": 1695089378,
"labels": {},
"server_id": 937142
}

13.InfoALL

tidb-server_ip:status_port/info/all

获取tidb集群所有tidb-server的信息

{
"servers_num": 1,
"owner_id": "9112417d-2609-404a-8a8b-c10b5cebfe2b",
"is_all_server_version_consistent": true,
"all_servers_info": {
"9112417d-2609-404a-8a8b-c10b5cebfe2b": {
"version": "5.7.25-TiDB-v6.5.2",
"git_hash": "29116c0256c52b224da2b34d712c1063d171c0ad",
"ddl_id": "9112417d-2609-404a-8a8b-c10b5cebfe2b",
"ip": "10.3.65.136",
"listening_port": 4900,
"status_port": 19080,
"lease": "45s",
"binlog_status": "On",
"start_timestamp": 1703554804,
"labels": {},
"server_id": 4042427
}
}
}

14.RegionsMeta

tidb-server_ip:status_port/regions/meta

获取所有region的元数据信息

[
{
"region_id": 10,
"leader": {
"id": 128,
"store_id": 2
},
"peers": [
{
"id": 11,
"store_id": 1
},
{
"id": 128,
"store_id": 2
},
{
"id": 178,
"store_id": 4
}
],
"region_epoch": {
"conf_ver": 5,
"version": 156
}
}
]

15.RegionHot

tidb-server_ip:status_port/regions/hot

获取热点region的表/索引信息

{
"read": [
{
"region_id": 180,
"region_metric": {
"flow_bytes": 38560,
"max_hot_degree": 2564,
"region_count": 0
},
"db_name": "mysql",
"table_name": "tidb_ddl_job",
"table_id": 281474976710654,
"index_name": "",
"index_id": 0
}
],
"write": []
}

16.Trace Viewer

tidb-server_ip:status_port/web/trace

以图形界面的方式显示执行sql的详细信息，参考 TRACE | PingCAP 文档中心使用。

这个我实验无法显示出图形信息 https://asktug.com/t/topic/1014681，尝试了6.1、6.5、7.1环境都无法显示出来。

17.Debug

tidb-server_ip:status_port/debug/pprof/

tidb debug信息，例如heap、goroutine、trace等常用信息。

Types of profiles available:
Count Profile
12038allocs
0block
0cmdline
249goroutine
12038heap
85mutex
0profile
12threadcreate
0trace
full goroutine stack dump
Profile Descriptions:

allocs:A sampling of allpast memory allocations
block: Stack traces that led toblocking onsynchronization primitives
cmdline: The commandlineinvocation of the current program
goroutine: Stack traces of allcurrent goroutines
heap: A sampling of memory allocations of live objects. You can specify the gc GET parameter torun GC before taking the heap sample.
mutex: Stack traces of holders of contended mutexes
profile: CPU profile. You can specify the duration in the seconds GET parameter. After you getthe profilefile, use the gotool pprof commandtoinvestigate the profile.
threadcreate: Stack traces that led tothe creation of newOS threads
trace: A trace of execution of the current program. You can specify the duration in the seconds GET parameter. After you getthe trace file, use the gotool trace commandtoinvestigate the trace.