add collect sql query plan using clinic

Author: Oreoxmt

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

@@ -0,0 +1,115 @@
+---
+title: Collect SQL Query Plan Related Information Using PingCAP Clinic Diag
+summary: Learn how to use PingCAP Clinic Diag to collect SQL query plan related information on clusters deployed using TiUP.
+---
+
+# Collect SQL Query Plan Related Information Using PingCAP Clinic Diag
+
+Since 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.
+
+## Description
+
+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).
+
+> **Warning:**
+>
+> - This is an experimental feature, and it is not recommended to use it in production.
+> - This feature **does not support** clusters deployed using TiDB Operator.
+
+## Usage
+
+### 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 that the version is >= **0.7.3**.
+
+    To check the version of Diag, you can use the following command:
+
+    ```bash
+    tiup diag --version
+    ```
+
+    If the version is older than **0.7.3**, you can use the following command to upgrade to the latest version:
+
+    ```bash
+    tiup update diag
+    ```
+
+### Collect data
+
+To collect data, you can use the following `diag collect` command:
+
+```bash
+diag collect <cluster-name> --profile=tidb-plan-replayer --explain-sql=<statement-filepath>
+```
+
+> **Note:**
+>
+> - To collect data using the `diag` command, you need to provide a `sql-statement` file which contains the SQL statements to be collected.
+> - The `statement-filepath` is the path to the `sql-statement` file.
+> - `PLAN REPLAYER` does **not** export data in the tables.
+> - When collecting data, only `EXPLAIN` is executed, and the SQL statements are not executed. Therefore, it has little performance impact on the database.
+
+The following is an example of the `sql-statement` file:
+
+```sql
+SELECT * FROM information_schema.slow_query;SELECT * FROM information_schema.statements_summary
+```
+
+The description of the `sql-statement` file is as follows:
+
+- To analyze multiple SQL statements, you can use the `;` to separate them.
+- Make sure that the database is specified in the `sql-statement` file, for the reason that `diag` executes statements with a new session.
+
+#### 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/<db.table>.schema` |
+| 5 | The statistics of the table in `sql-statement` | `statistics` | `statistics/<db.table>.json` |
+| 6 | The result of `EXPLAIN [ANALYZE] sql-statement` | `explain` | `explain/sql0` |
+| 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` |
+| 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` |
+
+### Custom data collection
+
+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:
+
+```toml
+name = "tidb-plan-replayer"
+version = "0.0.1"
+maintainers = [
+    "pingcap"
+]
+
+# list of data types to collect
+collectors = [
+    "log",
+    "config",
+    "db_vars",
+    "sql_bind",
+    "statistics",
+    "explain"
+]
+
+# list of component roles to collect
+roles = [
+    "tidb"
+]
+```
+
+To collect custom data, specify the path to configuration file using the `--profile` option:
+
+```bash
+diag collect <cluster-name> --profile=<profile-filepath> --explain-sql=<statement-filepath>
+```