From f1f141e7887ec5757f00d44abbcd69fc502d3c87 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 13:28:40 +0000 Subject: [PATCH 1/4] Document QueryThrottler metrics --- .../24.0/reference/query-serving/metrics.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/content/en/docs/24.0/reference/query-serving/metrics.md b/content/en/docs/24.0/reference/query-serving/metrics.md index c9d4d1270..932727509 100644 --- a/content/en/docs/24.0/reference/query-serving/metrics.md +++ b/content/en/docs/24.0/reference/query-serving/metrics.md @@ -47,3 +47,61 @@ Some common optimizations include: Users can identify unoptimized queries using the plan classification in VTGate’s /debug/query_plans endpoint and apply the necessary improvements. By analyzing these metrics, users can fine-tune query execution, reduce latency, and improve overall performance in Vitess. + +## QueryThrottler Metrics + +The QueryThrottler is a VTTablet component that evaluates queries to determine if they should be throttled based on configurable throttling strategies. VTTablet exposes several metrics to monitor QueryThrottler activity. + +### Available Metrics + +VTTablet exposes the following metrics for monitoring QueryThrottler activity: + +#### QueryThrottlerRequests + +Tracks the total number of requests evaluated by the query throttler. + +**Labels:** +* `strategy`: The throttling strategy being used (e.g., "MockStrategy", "Unknown") +* `workload`: The workload name from ExecuteOptions (defaults to "default" or "unknown") +* `priority`: The query priority value (0-100, defaults to 100) + +#### QueryThrottlerThrottled + +Tracks the number of requests that were throttled by the query throttler. + +**Labels:** +* `strategy`: The throttling strategy being used +* `workload`: The workload name from ExecuteOptions +* `priority`: The query priority value (0-100) +* `metric_name`: Name of the metric that triggered throttling (e.g., "cpu", "memory") +* `metric_value`: The value of the metric that triggered throttling +* `dry_run`: Whether the throttler is in dry-run mode (true/false). In dry-run mode, throttling decisions are logged but queries are not throttled. + +#### QueryThrottlerTotalLatencyNs + +Measures the total latency of the QueryThrottler.Throttle function call in nanoseconds, from entry to exit. + +**Labels:** +* `strategy`: The throttling strategy being used +* `workload`: The workload name from ExecuteOptions +* `priority`: The query priority value (0-100) + +#### QueryThrottlerEvaluateLatencyNs + +Measures the latency of the strategy evaluation phase in nanoseconds, from when the Throttle function begins to when the Evaluate method completes. + +**Labels:** +* `strategy`: The throttling strategy being used +* `workload`: The workload name from ExecuteOptions +* `priority`: The query priority value (0-100) + +### Using QueryThrottler Metrics + +You can use these metrics to: +* Monitor queries being evaluated for throttling +* Track throttling rates by strategy, workload, and priority +* Identify which metrics are triggering throttling decisions +* Measure the performance overhead of throttling evaluation +* Verify dry-run mode behavior before enabling throttling + +For example, you can use these metrics to determine if a particular workload or query priority is being throttled more frequently, or to measure the latency impact of throttling evaluation on query execution. From e4a6f5142140d1762e127798213c4d7d4f616da7 Mon Sep 17 00:00:00 2001 From: Stuti Biyani Date: Thu, 4 Dec 2025 12:48:00 +0530 Subject: [PATCH 2/4] Update docs for throttler metrics Signed-off-by: Stuti Biyani --- .../24.0/reference/query-serving/metrics.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/content/en/docs/24.0/reference/query-serving/metrics.md b/content/en/docs/24.0/reference/query-serving/metrics.md index 932727509..801cc3e4d 100644 --- a/content/en/docs/24.0/reference/query-serving/metrics.md +++ b/content/en/docs/24.0/reference/query-serving/metrics.md @@ -61,39 +61,39 @@ VTTablet exposes the following metrics for monitoring QueryThrottler activity: Tracks the total number of requests evaluated by the query throttler. **Labels:** -* `strategy`: The throttling strategy being used (e.g., "MockStrategy", "Unknown") -* `workload`: The workload name from ExecuteOptions (defaults to "default" or "unknown") -* `priority`: The query priority value (0-100, defaults to 100) +* `Strategy`: The throttling strategy being used (e.g., "TabletThrottlerStrategy") +* `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive +* `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) #### QueryThrottlerThrottled Tracks the number of requests that were throttled by the query throttler. **Labels:** -* `strategy`: The throttling strategy being used -* `workload`: The workload name from ExecuteOptions -* `priority`: The query priority value (0-100) -* `metric_name`: Name of the metric that triggered throttling (e.g., "cpu", "memory") -* `metric_value`: The value of the metric that triggered throttling -* `dry_run`: Whether the throttler is in dry-run mode (true/false). In dry-run mode, throttling decisions are logged but queries are not throttled. +* `Strategy`: The throttling strategy being used +* `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive +* `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) +* `MetricName`: Name of the metric that triggered throttling (e.g., "cpu", "lag") +* `MetricValue`: The value of the metric that triggered throttling +* `DryRun`: Whether the throttler is in dry-run mode (true/false). In dry-run mode, throttling decisions are logged but queries are not throttled. #### QueryThrottlerTotalLatencyNs -Measures the total latency of the QueryThrottler.Throttle function call in nanoseconds, from entry to exit. +Measures the total latency in nanoseconds for each throttling request from entry to exit, including evaluation, metric checks, and all overhead. **Labels:** -* `strategy`: The throttling strategy being used -* `workload`: The workload name from ExecuteOptions -* `priority`: The query priority value (0-100) +* `Strategy`: The throttling strategy being used +* `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive +* `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) #### QueryThrottlerEvaluateLatencyNs -Measures the latency of the strategy evaluation phase in nanoseconds, from when the Throttle function begins to when the Evaluate method completes. +Measures the latency in nanoseconds of the strategy evaluation phase, specifically the time taken to make the throttling decision. **Labels:** -* `strategy`: The throttling strategy being used -* `workload`: The workload name from ExecuteOptions -* `priority`: The query priority value (0-100) +* `Strategy`: The throttling strategy being used +* `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive +* `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) ### Using QueryThrottler Metrics From 7afcdaa9b0f96de52190dc62a8c3478529f28992 Mon Sep 17 00:00:00 2001 From: Matt Lord Date: Thu, 18 Dec 2025 14:56:42 +0000 Subject: [PATCH 3/4] Minor tweaks Signed-off-by: Matt Lord --- .../docs/24.0/reference/query-serving/metrics.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/content/en/docs/24.0/reference/query-serving/metrics.md b/content/en/docs/24.0/reference/query-serving/metrics.md index 801cc3e4d..5dde49440 100644 --- a/content/en/docs/24.0/reference/query-serving/metrics.md +++ b/content/en/docs/24.0/reference/query-serving/metrics.md @@ -12,6 +12,7 @@ These updates help users track query performance, identify costly execution plan Vitess now classifies query plans based on their execution strategies, allowing for more precise execution decisions. The classifications include: + * `Local`: Queries executed locally on VTGate without involving any shard. * `Passthrough`: Queries forwarded to single shard without having any additional processing at VTGate. * `MultiShard`: Queries executed across multiple shards with controlled routing. @@ -50,18 +51,19 @@ By analyzing these metrics, users can fine-tune query execution, reduce latency, ## QueryThrottler Metrics -The QueryThrottler is a VTTablet component that evaluates queries to determine if they should be throttled based on configurable throttling strategies. VTTablet exposes several metrics to monitor QueryThrottler activity. +The [QueryThrottler](../QueryThrottler/) is a VTTablet component that evaluates queries to determine if they should be throttled based on configurable throttling strategies. VTTablet exposes several metrics to monitor [QueryThrottler](../QueryThrottler/) activity. ### Available Metrics -VTTablet exposes the following metrics for monitoring QueryThrottler activity: +VTTablet exposes the following metrics for monitoring [QueryThrottler](../QueryThrottler/) activity: #### QueryThrottlerRequests Tracks the total number of requests evaluated by the query throttler. **Labels:** -* `Strategy`: The throttling strategy being used (e.g., "TabletThrottlerStrategy") + +* `Strategy`: The throttling strategy being used (e.g., `TabletThrottler`) * `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive * `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) @@ -70,6 +72,7 @@ Tracks the total number of requests evaluated by the query throttler. Tracks the number of requests that were throttled by the query throttler. **Labels:** + * `Strategy`: The throttling strategy being used * `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive * `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) @@ -82,15 +85,17 @@ Tracks the number of requests that were throttled by the query throttler. Measures the total latency in nanoseconds for each throttling request from entry to exit, including evaluation, metric checks, and all overhead. **Labels:** + * `Strategy`: The throttling strategy being used * `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive * `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) #### QueryThrottlerEvaluateLatencyNs -Measures the latency in nanoseconds of the strategy evaluation phase, specifically the time taken to make the throttling decision. +Measures the latency in nanoseconds of the strategy evaluation phase, specifically the time taken to make the throttling decision. **Labels:** + * `Strategy`: The throttling strategy being used * `Workload`: The client application workload name from the `WORKLOAD_NAME` comment directive * `Priority`: The query priority value (0-100) determining query throttling preference (lower = higher priority) @@ -98,6 +103,7 @@ Measures the latency in nanoseconds of the strategy evaluation phase, specifical ### Using QueryThrottler Metrics You can use these metrics to: + * Monitor queries being evaluated for throttling * Track throttling rates by strategy, workload, and priority * Identify which metrics are triggering throttling decisions From ed6fd1756e9f61a92621946b85a6778196c29510 Mon Sep 17 00:00:00 2001 From: Matt Lord Date: Thu, 18 Dec 2025 15:00:35 +0000 Subject: [PATCH 4/4] Fix links Signed-off-by: Matt Lord --- content/en/docs/24.0/reference/query-serving/metrics.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/24.0/reference/query-serving/metrics.md b/content/en/docs/24.0/reference/query-serving/metrics.md index 5dde49440..f3a20233b 100644 --- a/content/en/docs/24.0/reference/query-serving/metrics.md +++ b/content/en/docs/24.0/reference/query-serving/metrics.md @@ -51,11 +51,11 @@ By analyzing these metrics, users can fine-tune query execution, reduce latency, ## QueryThrottler Metrics -The [QueryThrottler](../QueryThrottler/) is a VTTablet component that evaluates queries to determine if they should be throttled based on configurable throttling strategies. VTTablet exposes several metrics to monitor [QueryThrottler](../QueryThrottler/) activity. +The [QueryThrottler](../../features/query-throttler/) is a VTTablet component that evaluates queries to determine if they should be throttled based on configurable throttling strategies. VTTablet exposes several metrics to monitor [QueryThrottler](../../features/query-throttler/) activity. ### Available Metrics -VTTablet exposes the following metrics for monitoring [QueryThrottler](../QueryThrottler/) activity: +VTTablet exposes the following metrics for monitoring [QueryThrottler](../../features/query-throttler/) activity: #### QueryThrottlerRequests