Skip to content

feat(flowcontrol): add per-band and global queue utilization gauges - #2184

Open
sudoalok wants to merge 1 commit into
llm-d:mainfrom
sudoalok:feat/flowcontrol-utilization-gauges-2102
Open

feat(flowcontrol): add per-band and global queue utilization gauges#2184
sudoalok wants to merge 1 commit into
llm-d:mainfrom
sudoalok:feat/flowcontrol-utilization-gauges-2102

Conversation

@sudoalok

Copy link
Copy Markdown
Contributor

Adds the queue utilization gauges from #2102 so operators can alert on "queue is at N% of its limit" without having to join config values into the PromQL.

flow_control_queue_utilization_requests and _bytes, labels {priority, inference_pool} to match flow_control_requests_total, llm_d_epp prefix only. computed in the dispatch cycle right next to the pool_saturation emit since utilization is basically the demand side twin of it. per band series always get emitted, global aggregate only when a global limit is set, and an unlimited dimension gets skipped instead of showing up as 0.

few notes:

  • the global aggregate uses priority="" while the per band ones carry the actual band number. can switch to a named sentinel if you'd rather have that
  • it reads registry.Stats() once per dispatch cycle like we discussed on [Flow Control] Production readiness: enable the flowControl feature gate by default #1187, it's periodic so not on the enqueue hot path, and the metric names/labels stay the same when the engine merge moves the data source later
  • extended TestFlowControlMetricsEmitted with a queueUtilizationGauge helper following the same shape as queueSizeGaugeSum. i kept require.Eventually for the utilization checks since these gauges get refreshed by the dispatch cycle and not synchronously like queue_size, so they lag by a tick

build/vet/fmt clean, flowcontrol and metrics suites pass, race clean too.

Fixes #2102

@sudoalok
sudoalok requested review from a team, LukeAVanDrie and shmuelk as code owners July 25, 2026 05:59
@sudoalok
sudoalok requested review from liu-cong and vMaroon July 25, 2026 05:59
@github-actions github-actions Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jul 25, 2026
@shmuelk

shmuelk commented Jul 26, 2026

Copy link
Copy Markdown
Contributor

Please remove the file release-notes.d/unreleased/2184.md and add the release notes to the proper (and missing) release notes section of the PR description.

@shmuelk

shmuelk commented Jul 26, 2026

Copy link
Copy Markdown
Contributor

The PR's description and code talks about queue utilization. I thought the metrics would be per queue. That would actually be quite bad, as it would be priorityBand per flow ID. There are those that want to assign every user session its own flow ID.

Instead the metrics are per priorityBand, which is much more contained. I think better names are needed here. Unfortunately as a true Software Engineer, I'm having trouble coming up with a better name/term.

Signed-off-by: Alok Behera <alokbeherak061@gmail.com>
@sudoalok
sudoalok force-pushed the feat/flowcontrol-utilization-gauges-2102 branch from 9e94454 to 3784c7d Compare July 27, 2026 04:20
@sudoalok

Copy link
Copy Markdown
Contributor Author

yeah good catch on both

i didnt realize the release-notes bot generates that from the PR description, i had hand written it (and numbered it 2190 by mistake on top of that). the note is in the description now under the release-note block.

on the naming you're right that the name was misleading. these are per priority band, aggregated over all the flows in the band, never per flow id. the problem is "queue" already means the per flow queue in this code, flow_control_queue_size and flow_control_queue_bytes both carry fairness_id, so a queue_utilization with no fairness_id reads exactly like the per flow id explosion you were worried about.

renamed them to flow_control_capacity_utilization_requests and flow_control_capacity_utilization_bytes. capacity is what the contract already calls the limit (CapacityRequests, CapacityBytes, TotalCapacityRequests in PriorityBandStats/AggregateStats), so the name is literally occupancy / configured capacity, and the priority label carries the level, with priority="" for the aggregate across all bands. i thought about a band_ prefix but that would be wrong for the "" row.

@LukeAVanDrie flagging this since #2102 spells out flow_control_queue_utilization_* by name. happy to go back to the issue's name if you'd rather keep that contract.

@ahg-g

ahg-g commented Jul 29, 2026

Copy link
Copy Markdown
Collaborator

/assign @LukeAVanDrie

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Flow Control] [Graduation Blocker] Per-band and global queue utilization ratio gauges

3 participants