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..f3a20233b 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. @@ -47,3 +48,66 @@ 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](../../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](../../features/query-throttler/) activity: + +#### QueryThrottlerRequests + +Tracks the total number of requests evaluated by the query throttler. + +**Labels:** + +* `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) + +#### QueryThrottlerThrottled + +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) +* `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 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. + +**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) + +### 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.