TiDB-Server 常用 API的功能和用法

PingCAP 675 2023-12-27

访问 tidb-server_ip:status_port 将呈现出各种 TiDB 服务器的 API，其中包含许多实用功能。本文将介绍这些 API 的功能和用法。

image.png

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. Metrics

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

tidb-server_ip:status_port/metrics

# HELP br_raw_backup_region_seconds Backup region latency distributions.# TYPE br_raw_backup_region_seconds histogrambr_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 * from t1;
+-----------------------------------------------------------+
| File_token                                                |
+-----------------------------------------------------------+
| replayer_xyUNbajB-Kx_rmD_Norcnw==_1702952402658503693.zip |
+-----------------------------------------------------------+
1 row in set (0.06 sec)

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

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

image.png


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.


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



17.Debug

tidb-server_ip:status_port/debug/pprof/

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

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

allocs: A sampling of all past memory allocations
block: Stack traces that led to blocking on synchronization primitives
cmdline: The command line invocation of the current program
goroutine: Stack traces of all current goroutines
heap: A sampling of memory allocations of live objects. You can specify the gc GET parameter to run 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 get the profile file, use the go tool pprof command to investigate the profile.
threadcreate: Stack traces that led to the creation of new OS threads
trace: A trace of execution of the current program. You can specify the duration in the seconds GET parameter. After you get the trace file, use the go tool trace command to investigate the trace.


结尾

以上API在一些运维场景中仍然相当实用。通过在运维中灵活运用，可以使运维工作更加便捷，增强系统管理的灵活性。尤其是在运维开发的场景中熟练使用，有助于高效地进行开发工作。


作者介绍：Daniel-W, 来自神州数码钛合金战队，是一支致力于为企业提供分布式数据库TiDB整体解决方案的专业技术团队。团队成员拥有丰富的数据库从业背景，全部拥有TiDB高级资格证书，并活跃于TiDB开源社区，是官方认证合作伙伴。目前已为10+客户提供了专业的TiDB交付服务，涵盖金融、证券、物流、电力、政府、零售等重点行业。



版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。

标签：TiDB 数据库 分布式数据库
上一篇:异地灾容备份，数据安全的最佳选择
下一篇:39.3T集群升级：TiDB v3.1.0至v7.1.2迁移实践
相关文章