Add TiDB Dashboard documents (#2668)

dashboard/dashboard-cluster-info.md

@@ -0,0 +1,70 @@
+---
+title: TiDB Dashboard Cluster Information Page
+summary: View the running status of TiDB, TiKV, PD, TiFlash components in the entire cluster and the running status of the host on which these components are located.
+category: how-to
+---
+
+# TiDB Dashboard Cluster Information Page
+
+On the cluster information page, you can view the running status of TiDB, TiKV, PD, TiFlash components in the entire cluster and the running status of the host on which these components are located.
+
+## Access the page
+
+You can use one of the following two methods to access the cluster information page:
+
+- After logging into TiDB Dashboard, click **Cluster Info** on the left navigation menu:
+
+  ![Access cluster information page](/media/dashboard/dashboard-cluster-info-access.png)
+
+- Visit <http://127.0.0.1:2379/dashboard/#/cluster_info/instance> in your browser. Replace `127.0.0.1:2379` with the actual PD instance address and port.
+
+## Instance list
+
+Click **Instances** to view the list of instances:
+
+![Instance list](/media/dashboard/dashboard-cluster-info-instances.png)
+
+This instance list shows the overview information of all instances of TiDB, TiKV, PD, and TiFlash components in the cluster.
+
+The list includes the following information:
+
+- Address: The instance address.
+- Status: The running status of the instance.
+- Up Time: The start time of the instance.
+- Version: The instance version number.
+- Deployment directory: The directory in which the instance binary file is located.
+- Git Hash: The Git Hash value corresponding to the instance binary file.
+
+An instance has the following running status:
+
+- Up: The instance is running properly.
+- Down or Unreachable: The instance is not started or a network problem exists on the corresponding host.
+- Tombstone: The data on the instance has been completely migrated out and the scaling-in is complete. This status exists only on TiKV or TiFlash instances.
+- Leaving: The data on the instance is being migrated out and the scaling-in is in process. This status exists only on TiKV or TiFlash instances.
+- Unknown: The running state of the instance is unknown.
+
+> **Note:**
+>
+> Some columns in the table can be displayed only when the instance is up.
+
+## Host list
+
+Click **Hosts** to view the list of hosts:
+
+![Host list](/media/dashboard/dashboard-cluster-info-hosts.png)
+
+This host list shows the running status of hosts that correspond to all instances of TiDB, TiKV, PD, and TiFlash components in the cluster.
+
+The list includes the following information:
+
+- Address: The Host IP address.
+- CPU: The number of logical cores of the host CPU.
+- CPU Usage: The user-mode and kernel-mode CPU usage in the current 1 second.
+- Memory: The total physical memory size of the host.
+- Memory Usage: The current memory usage of the host.
+- Disk: The file system of the disk on the host on which the instance is running and the mounting path of this disk.
+- Disk Usage: The space usage of the disk on the host on which the instance is running.
+
+> **Note:**
+>
+> The host list information is provided by each instance process, so when all instances on the host are down, the host information is not displayed.

dashboard/dashboard-overview.md

@@ -0,0 +1,95 @@
+---
+title: Overview Page
+summary: Learn the overview page of TiDB Dashboard.
+category: how-to
+---
+
+# Overview Page
+
+This page shows the overview of the entire TiDB cluster, including the following information:
+
+- Queries per second (QPS) of the entire cluster.
+- The query latency of the entire cluster.
+- The SQL statements that have accumulated the longest execution time over the recent period.
+- The slow queries whose execution time over the recent period exceeds the threshold.
+- The node count and status of each instance.
+- Monitor and alert messages.
+
+## Access the page
+
+After logging into TiDB Dashboard, the overview page is entered by default, or you can click **Overview** on the left navigation menu to enter this page:
+
+![Enter overview page](/media/dashboard/dashboard-overview-access.png)
+
+## QPS
+
+This area shows the number of successful and failed queries per second for the entire cluster over the recent hour:
+
+![QPS](/media/dashboard/dashboard-overview-qps.png)
+
+> **Note:**
+>
+> This feature is available only in the cluster where the Prometheus monitoring component is deployed. If Prometheus is not deployed, an error will be displayed.
+
+## Latency
+
+This area shows the latency of 99.9%, 99%, and 90% of queries in the entire cluster over the recent one hour:
+
+![Latency](/media/dashboard/dashboard-overview-latency.png)
+
+> **Note:**
+>
+> This feature is available only on the cluster where the Prometheus monitoring component is deployed. If Prometheus is not deployed, an error will be displayed.
+
+## Top SQL statements
+
+This area shows the ten types of SQL statements that have accumulated the longest execution time in the entire cluster over the recent period. SQL statements with different query parameters but of the same structure are classified into the same SQL type and displayed in the same row:
+
+![Top SQL](/media/dashboard/dashboard-overview-top-statements.png)
+
+The information shown in this area is consistent with the more detailed [SQL Statements Page](/dashboard/dashboard-statement-list.md). You can click the **Top SQL Statements** heading to view the complete list. For details of the columns in this table, see [SQL Statements Page](/dashboard/dashboard-statement-list.md).
+
+> **Note:**
+>
+> This feature is available only on the cluster where SQL Statements feature is enabled.
+
+## Recent slow queries
+
+By default, this area shows the latest 10 slow queries in the entire cluster over the recent 30 minutes:
+
+![Recent slow queries](/media/dashboard/dashboard-overview-slow-query.png)
+
+By default, the SQL query that is executed longer than 300 milliseconds is counted as a slow query and displayed on the table. You can change this threshold by modifying the [tidb_slow_log_threshold](/tidb-specific-system-variables.md#tidb_slow_log_threshold) variable or the [slow-threshold](/tidb-configuration-file.md#slow-threshold) TiDB parameter.
+
+The content displayed in this area is consistent with the more detailed [Slow Queries Page](/dashboard/dashboard-slow-query.md). You can click the **Recent Slow Queries** title to view the complete list. For details of the columns in this table, see this [Slow Queries Page](/dashboard/dashboard-slow-query.md).
+
+> **Note:**
+>
+> This feature is available only in the cluster with slow query logs enabled. By default, slow query logs are enabled in the cluster deployed using TiUP or TiDB Ansible.
+
+## Instances
+
+This area summarizes the total number of instances and abnormal instances of TiDB, TiKV, PD, and TiFlash in the entire cluster:
+
+![Instances](/media/dashboard/dashboard-overview-instances.png)
+
+The statuses in the image above are described as follows:
+
+- Up: The instance is running properly (including the offline storage instance).
+- Down: The instance is running abnormally, such as network disconnection, process crash, and so on.
+
+Click the **Instance** title to enter the [Cluster Info Page](/dashboard/dashboard-cluster-info.md) that shows the detailed running status of each instance.
+
+## Monitor and alert
+
+This area provides links for you to view detailed monitor and alert:
+
+![Monitor and alert](/media/dashboard/dashboard-overview-monitor.png)
+
+- **View Metrics**: Click this link to jump to the Grafana dashboard where you can view detailed monitoring information of the cluster. For details of each monitoring metric in the Grafana dashboard, see [monitoring metrics](/grafana-overview-dashboard.md).
+- **View Alerts**: Click this link to jump to the AlertManager page where you can view detailed alert information of the cluster. If alerts exist in the cluster, the number of alerts is directly shown in the link text.
+- **Run Diagnostics**: Click this link to jump to the more detailed [cluster diagnostics page](/dashboard/dashboard-diagnostics-access.md).
+
+> **Note:**
+>
+> The **View Metrics** link is available only in the cluster where the Grafana node is deployed. The **View Alerts** link is available only in the cluster where the AlertManager node is deployed.

dashboard/dashboard-slow-query.md

@@ -0,0 +1,61 @@
+---
+title: Slow Queries Page of TiDB Dashboard
+summary: Learn the Slow Queries page of TiDB Dashboard.
+category: how-to
+---
+
+# Slow Queries Page of TiDB Dashboard
+
+On the Slow Queries page of TiDB Dashboard, you can search and view all slow queries in the cluster.
+
+By default, SQL queries with an execution time of more than 300 milliseconds are considered as slow queries. These queries are recorded in the [slow query logs](/identify-slow-queries.md) and can be searched via TiDB Dashboard. You can adjust the threshold of slow queries through the [`tidb_slow_log_threshold`](/tidb-specific-system-variables.md#tidb_slow_log_threshold) session variable or the [`slow-threshold`](/tidb-configuration-file.md#slow-threshold) TiDB parameter.
+
+> **Note:**
+>
+> If the slow query log is disabled, this feature will be unavailable. The slow query log is enabled by default, and you can enable or disable the slow query log through the [`enable-slow-log`](/tidb-configuration-file.md#enable-slow-log) TiDB configuration item.
+
+## Access the page
+
+You can use one of the following two methods to access the slow query page:
+
+* After logging into TiDB Dashboard, click **Slow Queries** on the left navigation menu:
+
+![Access slow query page](/media/dashboard/dashboard-slow-queries-access.png)
+
+* Visit <http://127.0.0.1:2379/dashboard/#/slow_query> in your browser. Replace `127.0.0.1:2379` with the actual PD address and port.
+
+All data displayed on the slow query page comes from TiDB slow query system tables and slow query logs. See [slow query logs](/identify-slow-queries.md) for details.
+
+### Change Filters
+
+You can filter slow queries based on the time range, the related database, SQL keywords, SQL types, the number of slow queries to be displayed. In the image below, 100 slow queries over the recent 30 minutes are displayed by default.
+
+![Modify list filters](/media/dashboard/dashboard-slow-queries-list1.png)
+
+### Display More Columns
+
+Click **Columns** on the page and you can choose to see more columns. You can move your mouse to the **(i)** icon at the right side of a column name to view the description of this column:
+
+![Show more columns](/media/dashboard/dashboard-slow-queries-list2.png)
+
+### Sort by Column
+
+By default, the list is sorted by **Finish Time** in the descending order. Click column headings to sort by the column or switch the sorting order:
+
+![Modify sorting basis](/media/dashboard/dashboard-slow-queries-list3.png)
+
+## View execution details
+
+Click any item in the list to display detailed execution information of the slow query, including:
+
+- Query: The text of the SQL statement (see area 1 in the image below);
+- Plan: The execution plan of the slow query. See [Understand the Query Execution Plan](/query-execution-plan.md) to learn how to read the execution plan (see area 2 in the image below);
+- Other sorted SQL execution information (see area 3 in the image below).
+
+![View execution details](/media/dashboard/dashboard-slow-queries-detail1.png)
+
+Click the **Expand** link to show the detailed information of an item. Click the **Copy** link to copy the detailed information to the clipboard.
+
+Click the corresponding tab titles to switch information of different sorted SQL executions.
+
+![Show different sorted execution information](/media/dashboard/dashboard-slow-queries-detail2.png)

dashboard/dashboard-statement-details.md

@@ -0,0 +1,61 @@
+---
+title: Statement Execution Details of TiDB Dashboard
+summary: View the execution details of a single SQL statement in TiDB Dashboard.
+category: how-to
+---
+
+# Statement Execution Details of TiDB Dashboard
+
+Click any item in the list to enter the detail page of the SQL statement to view more detailed information. This information includes the following parts:
+
+- The overview of SQL statements, which includes the SQL template, the SQL template ID, the current time range of displayed SQL executions, the number of execution plans and the database in which the SQL statement is executed (see area 1 in the image below).
+- The execution plan list: If the SQL statement has multiple execution plans, this list is displayed. You can select different execution plans, and the details of the selected plans are displayed below the list. If there is only one execution plan, the list is not displayed (see area 2 below).
+- Execution detail of plans, which displays the detailed information of the selected execution plans. See [Execution plan in details](#execution-plan-in-details) (area 3 in the image below).
+
+![Details](/media/dashboard/dashboard-statement-detail.png)
+
+## Execution details of plans
+
+The execution detail of plans includes the following information:
+
+- SQL sample: The text of a certain SQL statement that is actually executed corresponding to the plan. Any SQL statement that has been executed within the time range might be used as a SQL sample.
+- Execution plan: For details of the execution plan, see [Understand the Query Execution Plan](/query-execution-plan.md). If multiple execution plans are selected, only (any) one of them is displayed.
+- For basic information, execution time, Coprocessor read, transaction, and slow query of the SQL statement, you can click the corresponding tab titles to switch among different information.
+
+![Execution details of plans](/media/dashboard/dashboard-statement-plans-detail.png)
+
+### Basic Tab
+
+The basic information of a SQL execution includes the table names, index name, execution count, and total latency. The **Description** column provides detailed description of each field.
+
+![Basic information](/media/dashboard/dashboard-statement-plans-basic.png)
+
+### Time Tab
+
+Click the **Time** tab, and you can see how long each stage of the execution plan lasts.
+
+> **Note:**
+>
+> Because some operations might be performed in parallel within a single SQL statement, the cumulative duration of each stage might exceed the actual execution time of the SQL statement.
+
+![Execution time](/media/dashboard/dashboard-statement-plans-time.png)
+
+### Coprocessor Read Tab
+
+Click the **Coprocessor Read** tab, and you can see information related to Coprocessor read.
+
+![Coprocessor read](/media/dashboard/dashboard-statement-plans-cop-read.png)
+
+### Transaction Tab
+
+Click the **Transaction** tab, and you can see information related to execution plans and transactions, such as the average number of written keys or the maximum number of written keys.
+
+![Transaction](/media/dashboard/dashboard-statement-plans-transaction.png)
+
+### Slow Query Tab
+
+If an execution plan is executed too slowly, you can see its associated slow query records under the **Slow Query** tab.
+
+![Slow Query](/media/dashboard/dashboard-statement-plans-slow-queries.png)
+
+The information displayed in this area has the same structure with the slow query page. See [TiDB Dashboard Slow Query Page](/dashboard/dashboard-slow-query.md) for details.

dashboard/dashboard-statement-list.md

@@ -0,0 +1,64 @@
+---
+title: SQL Statements Page of TiDB Dashboard
+summary: View the execution status of all SQL statements in the TiDB cluster.
+category: how-to
+---
+
+# SQL Statements Page of TiDB Dashboard
+
+The SQL statements page shows the execution status of all SQL statements in the cluster. This page is often used to analyze the SQL statement whose total or single execution time is long.
+
+On this page, SQL queries with a consistent structure (even if the query parameters are inconsistent) are classified as the same SQL statement. For example, both `SELECT * FROM employee WHERE id IN (1, 2, 3)` and `select * from EMPLOYEE where ID in (4, 5)` are classified as the same `select * from employee where id in (...)` SQL statement.
+
+## Access the page
+
+You can use one of the following two methods to access the SQL statement summary page:
+
+- After logging into TiDB Dashboard, click **SQL Statements** on the left navigation menu:
+
+  ![Access SQL statement summary page](/media/dashboard/dashboard-statement-access.png)
+
+- Visit <http://127.0.0.1:2379/dashboard/#/statement> in your browser. Replace `127.0.0.1:2379` with the actual PD instance address and port.
+
+All the data shown on the SQL statement summary page are from the TiDB statement summary tables. For more details about the tables, see [TiDB Statement Summary Tables](/statement-summary-tables.md).
+
+### Change Filters
+
+On the top of the SQL statement summary page, you can modify the time range of SQL executions to be displayed. You can also filter the list by database in which SQL statements are executed, or by SQL types. The following image shows all SQL executions over the recent data collection cycle (recent 30 minutes by default).
+
+![Modify filters](/media/dashboard/dashboard-statement-filter-options.png)
+
+### Display More Columns
+
+Click **Columns** on the page and you can choose to see more columns. You can move your mouse to the **(i)** icon at the right side of a column name to view the description of this column:
+
+![Choose columns](/media/dashboard/dashboard-statement-columns-selector.png)
+
+### Sort by Column
+
+By default, the list is sorted by **Total Latency** from high to low. Click on different column headings to modify the sorting basis or switch the sorting order:
+
+![Modify list sorting](/media/dashboard/dashboard-statement-change-order.png)
+
+### Change Settings
+
+On the list page, click the **Settings** button on the top right to change the settings of the SQL statements feature:
+
+![Settings entry](/media/dashboard/dashboard-statement-setting-entry.png)
+
+After clicking the **Settings** button, you can see the following setting dialog box:
+
+![Settings](/media/dashboard/dashboard-statement-settings.png)
+
+On the setting page, you can disable or enable the SQL statements feature. When the SQL statements feature is enabled, you can modify the following settings:
+
+- Collect interval: The length of period for each SQL statement analysis, which is 30 minutes by default. The SQL statements feature summarizes and counts all SQL statements within a period of time. If the period is too long, the granularity of the summary is coarse, which is not good for locating problems; if the period is too short, the granularity of the statistics is fine, which is good for locating problems, but this will result in more records and more memory usage within the same data retention duration. Therefore, you need to adjust this value based on the actual situation, and properly lower this value when locating problems.
+- Data retain duration: The retention duration of summary information, which is 1 day by default. Data retained longer than this duration will be deleted from system tables.
+
+See [Configurations of Statement Summary Tables](/statement-summary-tables.md#configurations) for details.
+
+> **Note:**
+>
+> + Because the statement system table is only stored in memory, after the SQL Statements feature is disabled, the data in the system table will be cleared.
+>
+> + The values of `Collect interval` and `retain duration` affect the memory usage, so it is recommended to adjust these values according to the actual situation. The value of `retain duration` should not be set too large.