diff --git a/TOC.md b/TOC.md index 5d34d6ec1b940..a5f0dc8e0c5e4 100644 --- a/TOC.md +++ b/TOC.md @@ -380,6 +380,7 @@ - [Overview](/clinic/clinic-introduction.md) - [Quick Start](/clinic/quick-start-with-clinic.md) - [Troubleshoot Clusters Using PingCAP Clinic](/clinic/clinic-user-guide-for-tiup.md) + - [Collect SQL Query Plan Related Information](/clinic/clinic-collect-sql-query-plan.md) - [PingCAP Clinic Diagnostic Data](/clinic/clinic-data-instruction-for-tiup.md) - [TiDB Operator](/tidb-operator-overview.md) - [Dumpling](/dumpling-overview.md) diff --git a/clinic/clinic-collect-sql-query-plan.md b/clinic/clinic-collect-sql-query-plan.md new file mode 100644 index 0000000000000..115cd1306b910 --- /dev/null +++ b/clinic/clinic-collect-sql-query-plan.md @@ -0,0 +1,118 @@ +--- +title: Collect SQL Query Plan Information Using PingCAP Clinic Diag +summary: Learn how to use PingCAP Clinic Diag to collect SQL query plan information on clusters deployed using TiUP. +--- + +# Collect SQL Query Plan Information Using PingCAP Clinic Diag + +Starting from v5.3.0, TiDB introduces the [`PLAN REPLAYER`](/sql-plan-replayer.md) feature to import and export SQL query plan 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 information conveniently. + +## Description + +When you troubleshoot issues in TiDB v4.0 or higher versions, you can use Diag to export the relevant data in the cluster as a ZIP-formatted file and upload it to PingCAP Clinic for technical support quickly. Before using Diag to collect data, you need to provide a SQL statement file for collection. The data collected by Diag includes log information and cluster information in addition to the data collected by the `PLAN REPLAYER` feature. For more information, see [Output](#output). + +> **Warning:** +> +> - This is an experimental feature. It is not recommended that you use it in a production environment. +> - This feature **does not support** clusters deployed using TiDB Operator. + +## Usage + +This section describes how to use Diag to collect SQL query plan information. You need to install Diag first, and then collect data using Diag. + +### Install Diag + +- You can use the following TiUP command to install Diag. The latest version is installed by default: + + ```bash + tiup install diag + ``` + +- If you have installed Diag, make sure the version is >= **0.7.3**. + + To check the version of Diag, you can use the following command: + + ```bash + tiup diag --version + ``` + + If the Diag version does not meet the requirement, you can upgrade to the latest version using the following command: + + ```bash + tiup update diag + ``` + +### Full data collection + +To collect data, you can use the following `diag collect` command and replace the `` and `` with your actual information: + +```bash +diag collect --profile=tidb-plan-replayer --explain-sql= +``` + +> **Note:** +> +> - Before collecting data using `diag`, you need to specify the `sql-statement` file using the `--explain-sql` option: +> +> - In the preceding command, the `` is the path of the `sql-statement` file. +> - The `sql-statement` file contains the SQL statements to be collected. +> - If there are multiple SQL statements to be collected, you can use the `;` to separate them. +> - Because the preceding `diag` command creates a new session to execute the SQL statements, make sure that the SQL statements in the `sql-statement` file must explicitly specify the database name, such as `SELECT * FROM test.t1`. +> +> - `PLAN REPLAYER` does **not** export data in the tables. +> - Only `EXPLAIN` is executed during data collection and the SQL statements are not executed. Therefore, the impact on the database performance during collection is minimal. + +The following is an example of the `sql-statement` file: + +```sql +SELECT * FROM test.t1;SELECT * FROM test.t2; +``` + +#### Output + +The output of the collection is as follows: + +| Number | Item | Diag collector | Output file | +| :--- | :--- | :--- | :--- | +| 1 | TiDB configuration | `config` | `tidb.toml` | +| 2 | TiDB session variables | `db_vars` | `global_variables.csv`, `mysql.tidb.csv` | +| 3 | TiDB SQL bindings | `sql_bind` | `sql_bind/global_bind.csv` | +| 4 | The table schema in `sql-statement` | `statistics` | `statistics/.schema` | +| 5 | The statistics of the table in `sql-statement` | `statistics` | `statistics/.json` | +| 6 | The result of `EXPLAIN [ANALYZE] sql-statement` | `explain` | `explain/sql0` | +| 7 |
  • TiDB logs
  • TiUP logs of cluster operations
|
  • `log`
  • `-R=tidb`
| `tidb.log`, `tidb_slow_query.log`, `tidb_stdeer.log`, `cluster_audit/$auditfilename` | +| 8 | The cluster information collected by default
  • Basic information of the cluster
  • The collection result of Diag
| default | `cluster.json`, `meta.yaml`, `$collectid_diag_audit.log` | + +### Custom data collection + +You can create a customized configuration file to collect part of the data in the preceding [output](#output) table. The following takes `tidb-plan-replayer.toml` as an example: + +```toml +name = "tidb-plan-replayer" +version = "0.0.1" +maintainers = [ + "pingcap" +] + +# list of data types to collect +collectors = [ + "config", + "sql_bind", + "plan_replayer" +] + +# list of component roles to collect +roles = [ + "tidb" +] +``` + +To collect custom data, specify the path to the configuration file using the `--profile` option: + +```bash +diag collect --profile= --explain-sql= +``` + +### Import the data into a TiDB cluster + +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) diff --git a/clinic/clinic-introduction.md b/clinic/clinic-introduction.md index 7a3583a217df4..9e2bcc11fc9dc 100644 --- a/clinic/clinic-introduction.md +++ b/clinic/clinic-introduction.md @@ -77,6 +77,7 @@ First, Diag gets cluster topology information from the deployment tool TiUP (tiu - Use PingCAP Clinic in an on-premise environment - [Quick Start with PingCAP Clinic](/clinic/quick-start-with-clinic.md) - [Troubleshoot Clusters using PingCAP Clinic](/clinic/clinic-user-guide-for-tiup.md) + - [Collect SQL Query Plan Related Information](/clinic/clinic-collect-sql-query-plan.md) - [PingCAP Clinic Diagnostic Data](/clinic/clinic-data-instruction-for-tiup.md) - Use PingCAP Clinic on Kubernetes