From b4a10918d31685c7f3d3ba4ca4faadb66a3bb1c0 Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Tue, 18 Apr 2023 21:51:46 +0800 Subject: [PATCH 1/9] initial translation --- .../sql-statement-calibrate-resource.md | 82 +++++++++++++++++-- 1 file changed, 74 insertions(+), 8 deletions(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index c848b87b3b2c7..434cd9903555c 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -5,7 +5,22 @@ summary: An overview of the usage of CALIBRATE RESOURCE for the TiDB database. # `CALIBRATE RESOURCE` -The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request Unit (RU)`](/tidb-resource-control#what-is-request-unit-ru) capacity of the current cluster. +The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request Unit (RU)`](/tidb-resource-control#what-is-request-unit-ru) capacity of the current cluster. TiDB provides two methods for estimation: + +- Method 1: view the capacity within a specified time window depending on the actual workload. The following constraints apply to improve the accuracy of the estimation: + - The time window ranges from 10 minutes to 24 hours. + - In the specified time window, if the CPU utilization of TiDB and TiKV is too low, you cannot estimate the capacity. + +- Method 2: specify `WORKLOAD` to view the RU capacity. The default value is TPCC. The following options are currently supported: + + - OLTP_READ_WRITE + - OLTP_READ_ONLY + - OLTP_WRITE_ONLY + - TPCC + +> **Note:** +> +> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component, the actual RU that each cluster can consume is also related to the actual workload. The estimated value in Method 2 is for reference only and might differ from the actual maximum value. It is recommended to use Method 1 for estimation based on the actual workload. @@ -18,21 +33,72 @@ The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request ## Synopsis ```ebnf+diagram -CalibrateResourceStmt ::= 'CALIBRATE' 'RESOURCE' +CalibrateResourceStmt ::= 'CALIBRATE' 'RESOURCE' WorkloadOption + +WorkloadOption ::= +( 'WORKLOAD' ('TPCC' | 'OLTP_READ_WRITE' | 'OLTP_READ_ONLY' | 'OLTP_WRITE_ONLY') ) +| ( 'START_TIME' 'TIMESTAMP' ('DURATION' stringLit | 'END_TIME' 'TIMESTAMP')?)? + ``` ## Examples +Specify the start time `START_TIME` and the time window `DURATION` to view the RU capacity according to the actual workload. + ```sql -CALIBRATE RESOURCE; +CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '20m'; +-------+ | QUOTA | +-------+ -| 68569 | +| 27969 | +-------+ -1 row in set (0.03 sec) +1 row in set (0.01 sec) ``` -> *Note:** -> -> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component. The actual RU that each cluster consumes is also related to the actual workload. This estimation is for reference only and might have some deviation from the actual maximum value. +Specify the start time `START_TIME` and the end time `END_TIME` to view the RU capacity according to the actual workload. + +```sql +CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' END_TIME '2023-04-18 08:20:00'; ++-------+ +| QUOTA | ++-------+ +| 27969 | ++-------+ +1 row in set (0.01 sec) +``` + +When the time window range `DURATION` does not fall between 10 minutes and 24 hours, an alert occurs. + +```sql +CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '25h'; +ERROR 1105 (HY000): the duration of calibration is too long, which could lead to inaccurate output. Please make the duration between 10m0s and 24h0m0s +CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '9m'; +ERROR 1105 (HY000): the duration of calibration is too short, which could lead to inaccurate output. Please make the duration between 10m0s and 24h0m0s +``` + +When the workload within the time window is too low, an alert occurs. + +```sql +CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '60m'; +ERROR 1105 (HY000): The workload in selected time window is too low, with which TiDB is unable to reach a capacity estimation; please select another time window with higher workload, or calibrate resource by hardware instead +``` + +Specify `WORKLOAD` to view the RU capacity. The default value is `TPCC`. + +```sql +CALIBRATE RESOURCE; ++-------+ +| QUOTA | ++-------+ +| 190470 | ++-------+ +1 row in set (0.01 sec) + +CALIBRATE RESOURCE WORKLOAD OLTP_WRITE_ONLY; ++-------+ +| QUOTA | ++-------+ +| 27444 | ++-------+ +1 row in set (0.01 sec) +``` From 6f3556af60d4af08c23b7f0ac7fe9bb76689dd1d Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Tue, 18 Apr 2023 21:54:33 +0800 Subject: [PATCH 2/9] Update sql-statement-calibrate-resource.md --- sql-statements/sql-statement-calibrate-resource.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index 434cd9903555c..0d8f9d183e646 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -11,7 +11,7 @@ The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request - The time window ranges from 10 minutes to 24 hours. - In the specified time window, if the CPU utilization of TiDB and TiKV is too low, you cannot estimate the capacity. -- Method 2: specify `WORKLOAD` to view the RU capacity. The default value is TPCC. The following options are currently supported: +- Method 2: specify `WORKLOAD` to view the RU capacity. The default value is `TPCC`. The following options are currently supported: - OLTP_READ_WRITE - OLTP_READ_ONLY @@ -20,7 +20,7 @@ The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request > **Note:** > -> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component, the actual RU that each cluster can consume is also related to the actual workload. The estimated value in Method 2 is for reference only and might differ from the actual maximum value. It is recommended to use Method 1 for estimation based on the actual workload. +> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component. The actual RU that each cluster can consume is also related to the actual workload. The estimated value in Method 2 is for reference only and might differ from the actual maximum value. It is recommended to use Method 1 for estimation based on the actual workload. From ebc5d3a827b45d7b0f1fce8d56d14f23e7839aa8 Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Tue, 18 Apr 2023 22:05:45 +0800 Subject: [PATCH 3/9] add privileges --- privilege-management.md | 4 ++++ sql-statements/sql-statement-calibrate-resource.md | 8 ++++++++ 2 files changed, 12 insertions(+) diff --git a/privilege-management.md b/privilege-management.md index 21b771e45f579..3e7394838021f 100644 --- a/privilege-management.md +++ b/privilege-management.md @@ -389,6 +389,10 @@ Requires `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. Requires `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. +### CALIBRATE RESOURCE + +Requires `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. + ## Implementation of the privilege system ### Privilege table diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index 0d8f9d183e646..8fa5c640fa913 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -41,6 +41,14 @@ WorkloadOption ::= ``` +## Privileges + +To execute this command, you need the following configuration and privileges: + +- You have enabled [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-new-in-v660). +- You have `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. +- You have the `SELECT` privilege for all tables in the `METRICS_SCHEMA` schema. + ## Examples Specify the start time `START_TIME` and the time window `DURATION` to view the RU capacity according to the actual workload. From 9789f18d46d945681d778618b5dbae222d91948a Mon Sep 17 00:00:00 2001 From: xixirangrang <35301108+hfxsd@users.noreply.github.com> Date: Wed, 19 Apr 2023 13:56:54 +0800 Subject: [PATCH 4/9] add parameter descriptions --- .../sql-statement-calibrate-resource.md | 43 ++++++++++++------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index 8fa5c640fa913..3006b34568ec9 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -5,22 +5,7 @@ summary: An overview of the usage of CALIBRATE RESOURCE for the TiDB database. # `CALIBRATE RESOURCE` -The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request Unit (RU)`](/tidb-resource-control#what-is-request-unit-ru) capacity of the current cluster. TiDB provides two methods for estimation: - -- Method 1: view the capacity within a specified time window depending on the actual workload. The following constraints apply to improve the accuracy of the estimation: - - The time window ranges from 10 minutes to 24 hours. - - In the specified time window, if the CPU utilization of TiDB and TiKV is too low, you cannot estimate the capacity. - -- Method 2: specify `WORKLOAD` to view the RU capacity. The default value is `TPCC`. The following options are currently supported: - - - OLTP_READ_WRITE - - OLTP_READ_ONLY - - OLTP_WRITE_ONLY - - TPCC - -> **Note:** -> -> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component. The actual RU that each cluster can consume is also related to the actual workload. The estimated value in Method 2 is for reference only and might differ from the actual maximum value. It is recommended to use Method 1 for estimation based on the actual workload. +The `CALIBRATE RESOURCE` statement is used to estimate and output the ['Request Unit (RU)`](/tidb-resource-control#what-is-request-unit-ru) capacity of the current cluster. @@ -49,6 +34,32 @@ To execute this command, you need the following configuration and privileges: - You have `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. - You have the `SELECT` privilege for all tables in the `METRICS_SCHEMA` schema. +## Parameters + +TiDB provides two methods for estimation: + +### Estimate capacity based on actual workload + +If your application is already running online, or you can run actual business tests, it is recommended to use the actual workload over a period of time to estimate the total capacity. Observe the following constraints to improve the accuracy of the estimation: + +- Use the `START_TIME` parameter to specify the time point at which the estimation starts, in the format of "2006-01-02 15:04:05". The default estimation end time is the current time. +- After specifying the `START_TIME` parameter, you can use the `END_TIME` parameter to specify the estimation end time, or use the `DURATION` parameter to specify the estimation time window from `START_TIME`. +- The time window ranges from 10 minutes to 24 hours. +- In the specified time window, if the CPU utilization of TiDB and TiKV is too low, you cannot estimate the capacity. + +### Estimate capacity based on hardware deployment + +This approach is mainly based on the current cluster configuration, combined with the empirical values observed for different workloads for estimation. Because different types of workloads require different ratios of hardware, the output capacity of the same configuration of hardware might be different. The `WORKLOAD` parameter here provides the following different workload types. The default value is `TPCC`. + +- `tpcc`: applies to workloads with heavy data write. It is estimated based on a workload model similar to TPC-C. +- `oltp_write_only`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `sysbench oltp_write_only`. +- `oltp_read_write`: applies to workloads with even data read and write. It is estimated based on a workload model similar to `sysbench oltp_read_write`. +- `oltp_read_only`: applies to workloads with heavy data read. It is estimated based on a workload model similar to `sysbench oltp_read_only`. + +> **Note:** +> +> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component. The actual RU that each cluster can consume is also related to the actual workload. The estimated value estimated based on hardware deployment is for reference only and might differ from the actual maximum value. It is recommended to [estimate capacity based on actual workload](#estimate-capacity-based-on-actual-workload). + ## Examples Specify the start time `START_TIME` and the time window `DURATION` to view the RU capacity according to the actual workload. From 38e22723f42ecdaa4a9383a0a0f82c4f43a86bd7 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 20 Apr 2023 09:59:01 +0800 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: Hu# --- sql-statements/sql-statement-calibrate-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index 3006b34568ec9..0582dfaccab02 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -51,7 +51,7 @@ If your application is already running online, or you can run actual business te This approach is mainly based on the current cluster configuration, combined with the empirical values observed for different workloads for estimation. Because different types of workloads require different ratios of hardware, the output capacity of the same configuration of hardware might be different. The `WORKLOAD` parameter here provides the following different workload types. The default value is `TPCC`. -- `tpcc`: applies to workloads with heavy data write. It is estimated based on a workload model similar to TPC-C. +- `tpcc`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `TPC-C`. - `oltp_write_only`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `sysbench oltp_write_only`. - `oltp_read_write`: applies to workloads with even data read and write. It is estimated based on a workload model similar to `sysbench oltp_read_write`. - `oltp_read_only`: applies to workloads with heavy data read. It is estimated based on a workload model similar to `sysbench oltp_read_only`. From 63b119ebec84501a80af17c305ea4493c50ca1bf Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 20 Apr 2023 12:09:36 +0800 Subject: [PATCH 6/9] Update sql-statements/sql-statement-calibrate-resource.md --- sql-statements/sql-statement-calibrate-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index 0582dfaccab02..0432d8763ea64 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -34,7 +34,7 @@ To execute this command, you need the following configuration and privileges: - You have `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. - You have the `SELECT` privilege for all tables in the `METRICS_SCHEMA` schema. -## Parameters +## Estimation methods TiDB provides two methods for estimation: From 00eb56a60060cd4c89e6ab3c4fc01b2d6e774b74 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 20 Apr 2023 12:25:08 +0800 Subject: [PATCH 7/9] Update sql-statements/sql-statement-calibrate-resource.md --- sql-statements/sql-statement-calibrate-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index 0432d8763ea64..d031bfc97fd42 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -34,7 +34,7 @@ To execute this command, you need the following configuration and privileges: - You have `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. - You have the `SELECT` privilege for all tables in the `METRICS_SCHEMA` schema. -## Estimation methods +## Methods for estimating capacity TiDB provides two methods for estimation: From 3a4d747ae38ff0448d7780a4258056756f0d5279 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 20 Apr 2023 12:49:26 +0800 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: Roger Song --- sql-statements/sql-statement-calibrate-resource.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index d031bfc97fd42..eb7e09d78f6ae 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -49,7 +49,7 @@ If your application is already running online, or you can run actual business te ### Estimate capacity based on hardware deployment -This approach is mainly based on the current cluster configuration, combined with the empirical values observed for different workloads for estimation. Because different types of workloads require different ratios of hardware, the output capacity of the same configuration of hardware might be different. The `WORKLOAD` parameter here provides the following different workload types. The default value is `TPCC`. +This approach is mainly based on the current cluster configuration, combined with the empirical values observed for different workloads for estimation. Because different types of workloads require different ratios of hardware, the output capacity of the same configuration of hardware might be different. The `WORKLOAD` parameter here accepts the following different workload types. The default value is `TPCC`. - `tpcc`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `TPC-C`. - `oltp_write_only`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `sysbench oltp_write_only`. @@ -58,7 +58,7 @@ This approach is mainly based on the current cluster configuration, combined wit > **Note:** > -> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component. The actual RU that each cluster can consume is also related to the actual workload. The estimated value estimated based on hardware deployment is for reference only and might differ from the actual maximum value. It is recommended to [estimate capacity based on actual workload](#estimate-capacity-based-on-actual-workload). +> The RU capacity of a cluster varies with the topology of the cluster and the hardware and software configuration of each component. The actual RU that each cluster can provide is also related to the actual workload. The estimated value based on hardware deployment is for reference only and might differ from the actual maximum value. It is recommended to [estimate capacity based on actual workload](#estimate-capacity-based-on-actual-workload). ## Examples From 1437d9760fda169bc076e875a8c8b582b8f6a366 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Sun, 23 Apr 2023 14:03:17 +0800 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Aolin --- .../sql-statement-calibrate-resource.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/sql-statements/sql-statement-calibrate-resource.md b/sql-statements/sql-statement-calibrate-resource.md index eb7e09d78f6ae..9dca783224589 100644 --- a/sql-statements/sql-statement-calibrate-resource.md +++ b/sql-statements/sql-statement-calibrate-resource.md @@ -28,11 +28,11 @@ WorkloadOption ::= ## Privileges -To execute this command, you need the following configuration and privileges: +To execute this command, make sure that the following requirements are met: - You have enabled [`tidb_enable_resource_control`](/system-variables.md#tidb_enable_resource_control-new-in-v660). -- You have `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. -- You have the `SELECT` privilege for all tables in the `METRICS_SCHEMA` schema. +- The user has `SUPER` or `RESOURCE_GROUP_ADMIN` privilege. +- The user has the `SELECT` privilege for all tables in the `METRICS_SCHEMA` schema. ## Methods for estimating capacity @@ -40,21 +40,21 @@ TiDB provides two methods for estimation: ### Estimate capacity based on actual workload -If your application is already running online, or you can run actual business tests, it is recommended to use the actual workload over a period of time to estimate the total capacity. Observe the following constraints to improve the accuracy of the estimation: +If your application is already running in a production environment, or you can run actual business tests, it is recommended to use the actual workload over a period of time to estimate the total capacity. To improve the accuracy of the estimation, observe the following constraints: -- Use the `START_TIME` parameter to specify the time point at which the estimation starts, in the format of "2006-01-02 15:04:05". The default estimation end time is the current time. +- Use the `START_TIME` parameter to specify the time point at which the estimation starts, in the format of `2006-01-02 15:04:05`. The default estimation end time is the current time. - After specifying the `START_TIME` parameter, you can use the `END_TIME` parameter to specify the estimation end time, or use the `DURATION` parameter to specify the estimation time window from `START_TIME`. - The time window ranges from 10 minutes to 24 hours. - In the specified time window, if the CPU utilization of TiDB and TiKV is too low, you cannot estimate the capacity. ### Estimate capacity based on hardware deployment -This approach is mainly based on the current cluster configuration, combined with the empirical values observed for different workloads for estimation. Because different types of workloads require different ratios of hardware, the output capacity of the same configuration of hardware might be different. The `WORKLOAD` parameter here accepts the following different workload types. The default value is `TPCC`. +This method mainly estimates capacity based on the current cluster configuration, combined with the empirical values observed for different workloads. Because different types of workloads require different ratios of hardware, the output capacity of the same configuration of hardware might be different. The `WORKLOAD` parameter here accepts the following different workload types. The default value is `TPCC`. -- `tpcc`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `TPC-C`. -- `oltp_write_only`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `sysbench oltp_write_only`. -- `oltp_read_write`: applies to workloads with even data read and write. It is estimated based on a workload model similar to `sysbench oltp_read_write`. -- `oltp_read_only`: applies to workloads with heavy data read. It is estimated based on a workload model similar to `sysbench oltp_read_only`. +- `TPCC`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `TPC-C`. +- `OLTP_WRITE_ONLY`: applies to workloads with heavy data write. It is estimated based on a workload model similar to `sysbench oltp_write_only`. +- `OLTP_READ_WRITE`: applies to workloads with even data read and write. It is estimated based on a workload model similar to `sysbench oltp_read_write`. +- `OLTP_READ_ONLY`: applies to workloads with heavy data read. It is estimated based on a workload model similar to `sysbench oltp_read_only`. > **Note:** > @@ -86,7 +86,7 @@ CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' END_TIME '2023-04-18 08:20:0 1 row in set (0.01 sec) ``` -When the time window range `DURATION` does not fall between 10 minutes and 24 hours, an alert occurs. +When the time window range `DURATION` does not fall between 10 minutes and 24 hours, an error occurs. ```sql CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '25h'; @@ -95,7 +95,7 @@ CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '9m'; ERROR 1105 (HY000): the duration of calibration is too short, which could lead to inaccurate output. Please make the duration between 10m0s and 24h0m0s ``` -When the workload within the time window is too low, an alert occurs. +When the workload within the time window is too low, an error occurs. ```sql CALIBRATE RESOURCE START_TIME '2023-04-18 08:00:00' DURATION '60m';