Skip to content

Commit 0e84de7

Browse files
OreoxmtOreoxmt
committed
clinic: support collection of SQL query plan related information
Signed-off-by: Aolin <[email protected]>
1 parent 0ee7cb2 commit 0e84de7

File tree

3 files changed

+121
-0
lines changed

3 files changed

+121
-0
lines changed

‎TOC.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,7 @@
380380
- [Overview](/clinic/clinic-introduction.md)
381381
- [Quick Start](/clinic/quick-start-with-clinic.md)
382382
- [Troubleshoot Clusters Using PingCAP Clinic](/clinic/clinic-user-guide-for-tiup.md)
383+
- [Collect SQL Query Plan Related Information](/clinic/clinic-collect-sql-query-plan.md)
383384
- [PingCAP Clinic Diagnostic Data](/clinic/clinic-data-instruction-for-tiup.md)
384385
- [TiDB Operator](/tidb-operator-overview.md)
385386
- [Dumpling](/dumpling-overview.md)

‎clinic/clinic-collect-sql-query-plan.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: Collect SQL Query Plan Related Information Using PingCAP Clinic Diag
3+
summary: Learn how to use PingCAP Clinic Diag to collect SQL query plan related information on clusters deployed using TiUP.
4+
---
5+
6+
# Collect SQL Query Plan Related Information Using PingCAP Clinic Diag
7+
8+
Starting from TiDB v5.3.0, the [`PLAN REPLAYER`](/sql-plan-replayer.md) is introduced to import and export SQL query plan related information using a single command, and simplifies troubleshooting hints-related issues. Clinic Diag client (Diag) integrates the `PLAN REPLAYER` feature. You can use Diag to collect SQL query plan related information conveniently.
9+
10+
## Description
11+
12+
For clusters higher than TiDB v4.0, Diag collects the information of a TiDB cluster for troubleshooting and exports as a ZIP-formatted file. You can upload the collected data to PingCAP Clinic conveniently and ask for technical support. The data collected using Diag is slightly different from what collected using the `PLAN REPLAYER` command. For the detailed information, see [output](#output).
13+
14+
> **Warning:**
15+
>
16+
> - This is an experimental feature, and it is not recommended to use it in production.
17+
> - This feature **does not support** clusters deployed using TiDB Operator.
18+
19+
## Usage
20+
21+
### Install Diag
22+
23+
- You can use the following TiUP command to install Diag. The latest version is installed by default:
24+
25+
```bash
26+
tiup install diag
27+
```
28+
29+
- If you have installed Diag, make sure that the version is >= **0.7.3**.
30+
31+
To check the version of Diag, you can use the following command:
32+
33+
```bash
34+
tiup diag --version
35+
```
36+
37+
If the version is older than **0.7.3**, you can use the following command to upgrade to the latest version:
38+
39+
```bash
40+
tiup update diag
41+
```
42+
43+
### Collect data
44+
45+
To collect data, you can use the following `diag collect` command:
46+
47+
```bash
48+
diag collect <cluster-name> --profile=tidb-plan-replayer --explain-sql=<statement-filepath>
49+
```
50+
51+
> **Note:**
52+
>
53+
> - To collect data using the `diag` command, you need to provide a `sql-statement` file which contains the SQL statements to be collected.
54+
> - The `statement-filepath` is the path to the `sql-statement` file.
55+
> - `PLAN REPLAYER` does **not** export data in the tables.
56+
> - When collecting data, only `EXPLAIN` is executed, and the SQL statements are not executed. Therefore, it has little performance impact on the database.
57+
58+
The following is an example of the `sql-statement` file:
59+
60+
```sql
61+
SELECT * FROM information_schema.slow_query;SELECT * FROM information_schema.statements_summary
62+
```
63+
64+
The description of the `sql-statement` file is as follows:
65+
66+
- To analyze multiple SQL statements, you can use the `;` to separate them.
67+
- Make sure that the database is specified in the `sql-statement` file, for the reason that `diag` executes statements with a new session.
68+
69+
#### Output
70+
71+
The output of the collection is as follows:
72+
73+
| Number | Item | Diag collector | Output file |
74+
| :--- | :--- | :--- | :--- |
75+
| 1 | TiDB configuration | `config` | `tidb.toml` |
76+
| 2 | TiDB session variables | `db_vars` | `global_variables.csv`, `mysql.tidb.csv` |
77+
| 3 | TiDB SQL bindings | `sql_bind` | `sql_bind/global_bind.csv` |
78+
| 4 | The table schema in `sql-statement` | `statistics` | `statistics/<db.table>.schema` |
79+
| 5 | The statistics of the table in `sql-statement` | `statistics` | `statistics/<db.table>.json` |
80+
| 6 | The result of `EXPLAIN [ANALYZE] sql-statement` | `explain` | `explain/sql0` |
81+
| 7 | <ul><li>TiDB logs</li><li> TiUP logs of cluster operations</li></ul> | <ul><li>`log`</li><li>`-R=tidb`</li></ul> | `tidb.log`, `tidb_slow_query.log`, `tidb_stdeer.log`, `cluster_audit/$auditfilename` |
82+
| 8 | The cluster information collected by default<ul><li>Basic information of the cluster</li><li>The collection result of Diag</li></ul> | default | `cluster.json`, `meta.yaml`, `$collectid_diag_audit.log` |
83+
84+
### Custom data collection
85+
86+
You can create a customized configuration file to collect part of data in the preceding [output](#output) table. The following takes `tidb-plan-replayer.toml` as an example:
87+
88+
```toml
89+
name = "tidb-plan-replayer"
90+
version = "0.0.1"
91+
maintainers = [
92+
"pingcap"
93+
]
94+
95+
# list of data types to collect
96+
collectors = [
97+
"log",
98+
"config",
99+
"db_vars",
100+
"sql_bind",
101+
"statistics",
102+
"explain"
103+
]
104+
105+
# list of component roles to collect
106+
roles = [
107+
"tidb"
108+
]
109+
```
110+
111+
To collect custom data, specify the path to configuration file using the `--profile` option:
112+
113+
```bash
114+
diag collect <cluster-name> --profile=<profile-filepath> --explain-sql=<statement-filepath>
115+
```
116+
117+
### Import the data into a TiDB cluster
118+
119+
The `plan_replayer.zip` in the collection result can be directly imported into the TiDB cluster using the `PLAN REPLAYER LOAD` statement. For more information, see [Use `PLAN REPLAYER` to import cluster information](/sql-plan-replayer.md#use-plan-replayer-to-import-cluster-information)

‎clinic/clinic-introduction.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ First, Diag gets cluster topology information from the deployment tool TiUP (tiu
7777
- Use PingCAP Clinic in an on-premise environment
7878
- [Quick Start with PingCAP Clinic](/clinic/quick-start-with-clinic.md)
7979
- [Troubleshoot Clusters using PingCAP Clinic](/clinic/clinic-user-guide-for-tiup.md)
80+
- [Collect SQL Query Plan Related Information](/clinic/clinic-collect-sql-query-plan.md)
8081
- [PingCAP Clinic Diagnostic Data](/clinic/clinic-data-instruction-for-tiup.md)
8182

8283
- Use PingCAP Clinic on Kubernetes

0 commit comments

Comments
 (0)