Add docs for WORKLOAD_NAME directive

vitessio · Mar 10, 2023 · f0dd259 · f0dd259
1 parent 0ba8a7f
commit f0dd259
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 0 deletions.
diff --git a/content/en/docs/17.0/reference/programs/vttablet.md b/content/en/docs/17.0/reference/programs/vttablet.md
@@ -147,6 +147,7 @@ The following global options apply to `vttablet`:
 | --enable-consolidator-replicas                                   | boolean       | Synonym to -enable_consolidator_replicas                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | --enable-lag-throttler                                           | boolean       | Synonym to -enable_lag_throttler                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | --enable-tx-throttler                                            | boolean       | Synonym to -enable_tx_throttler                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --enable-per-workload-table-metrics                              | boolean       | Synonym to --enable_per_workload_table_metrics                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | --enable_consolidator                                            | boolean       | This option enables the query consolidator. (default true)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | --enable_consolidator_replicas                                   | boolean       | This option enables the query consolidator only on replicas.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | --enable_hot_row_protection                                      | boolean       | If true, incoming transactions for the same row (range) will be queued and cannot consume all txpool slots.                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -156,6 +157,7 @@ The following global options apply to `vttablet`:
 | --enable_transaction_limit                                       | boolean       | If true, limit on number of transactions open at the same time will be enforced for all users. User trying to open a new transaction after exhausting their limit will receive an error immediately, regardless of whether there are available slots or not.                                                                                                                                                                                                                                               |
 | --enable_transaction_limit_dry_run                               | boolean       | If true, limit on number of transactions open at the same time will be tracked for all users, but not enforced.                                                                                                                                                                                                                                                                                                                                                                                            |
 | --enable_tx_throttler                                            | boolean       | If true replication-lag-based throttling on transactions will be enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --enable_per_workload_table_metrics                              | boolean       | If true, query counts and query error metrics include a label that identifies the workload.                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --enforce-tableacl-                                              | config        | if this flag is true, vttablet will fail to start if a valid tableacl config does not exist                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --enforce_strict_trans_tables                                    | boolean       | If true, vttablet requires MySQL to run with STRICT_TRANS_TABLES or STRICT_ALL_TABLES on. It is recommended to not turn this flag off. Otherwise MySQL may alter your supplied values before saving them to the database. (default true)                                                                                                                                                                                                                                                                   |
 | --external-compressor                                            | string        | command with arguments to use when compressing a backup.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

diff --git a/content/en/docs/17.0/user-guides/configuration-advanced/comment-directives.md b/content/en/docs/17.0/user-guides/configuration-advanced/comment-directives.md
@@ -90,3 +90,32 @@ select /*vt+ PLANNER=gen4 */ * from user;
 ```
 
 Valid values are the same as for the planner flag - `v3` and `gen4`.
+
+### Workload name (`WORKLOAD_NAME`)
+
+Specifies the client applicaiton workload name. This does not affect query execution, but can be used to instrument
+some `vttablet` metrics to include a label specifying the workload name. It can be useful if you are interested in
+getting insights about how much of the work being done at the `vttablet` level is being caused by each client
+application workload. For this to work, you must use  `--enable-per-workload-table-metrics` at the `vttablet`, and pass
+the client workload name on each query as a directive. For example:
+
+```sql
+select /*vt+ WORKLOAD_NAME=webstore */ * from commerce.customer;
+```
+
+will result in metrics such as this one:
+
+```bash
+% curl -s localhost:15100/metrics  | grep "table=\"customer\"" |grep webstore
+vttablet_query_counts{plan="Select",table="customer",workload="webstore"} 1
+vttablet_query_error_counts{plan="Select",table="customer",workload="webstore"} 0
+vttablet_query_rows_returned{plan="Select",table="customer",workload="webstore"} 0
+vttablet_query_times_ns{plan="Select",table="customer",workload="webstore"} 602557
+```
+
+As shown above, the metrics being instrumented this way are `vttablet_query_counts`, `vttablet_query_error_counts`,
+`vttablet_query_rows_returned` and `vttablet_query_times_ns`.
+
+If the query lacks the `WORKLOAD_NAME` directive, the corresponding label in the metric will have the value of an empty
+string. If `vttablet` is not started with `--enable-per-workload-table-metrics`, metrics are emitted without the
+workload label (e.g. `vttablet_query_counts{plan="Select",table="customer"}`.