docs: document Enterprise resource groups for query workload isolation - #548
Open
kafka1991 wants to merge 5 commits into
Open
docs: document Enterprise resource groups for query workload isolation#548kafka1991 wants to merge 5 commits into
kafka1991 wants to merge 5 commits into
Conversation
Add three pages and wire them into the sidebar. The concept page covers how a query is assigned to a group, what is managed, and how strong each of the four controls actually is: admission is an exact gate, CPU weight is a share that only bites under contention, the CPU cap is a rate over a short window, and memory limits are batched per worker. It also explains why CPU control is cooperative, what happens on a replica and after an internal fault, and what the feature costs when nothing competes. The operations page covers day-to-day use: quick start, requirements, the instance settings, group and mapping statements, policy parameters, six worked scenarios, the inspection functions, the per-group metrics, the errors clients see, and troubleshooting. The scenarios start with an instance that stops answering while CPU looks idle, which is the case resource groups address most directly, since a query that reaches a cooperative checkpoint releases its worker instead of holding it to completion. The configuration page documents the seven instance settings, including that the feature turns itself off rather than refusing to start when it was left at its default and an SQL pool is in legacy mode. Complete the query_activity() column list, document current_resource_group(), resource_groups() and resource_group_mappings() in the function reference, and add the resource group series to the metrics reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Nua5uVhTxq3uBnUD31b1aD
|
🚀 Build success! Latest successful preview: https://preview-548--questdb-documentation.netlify.app/docs/ Commit SHA: 8d2f734
|
kafka1991
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resource groups let one Enterprise instance run competing query workloads without one starving another.
New pages:
concepts/resource-groups.mdcovers how a query is assigned to a group, what is managed, and what each control actually guarantees.operations/resource-groups.mdcovers creating groups, mapping principals, choosing limits, inspection and troubleshooting.configuration/resource-groups.mdcovers the seven instance settings.query/functions/meta.mdgainscurrent_resource_group(),resource_groups()andresource_group_mappings(), and itsquery_activity()column list was four columns out of date.operations/logging-metrics.mdgains the ten per-group and seven instance-wide series.sidebars.jsgains three entries.The pages are explicit about what each control cannot do. Weights do nothing while only one group has work. The CPU cap is a rate over roughly a 100 ms window, not an instantaneous ceiling. Memory accounting is batched per worker, so a group can overshoot briefly. Admission is the only exact control. Getting this wrong is the main way someone ends up disappointed by the feature.
The first scenario on the operations page is the one likely to be read during an incident: the instance stops answering while CPU looks idle. Worth a close read. It says that enabling the feature alone frees the workers, and that Fiber pools without resource groups do not, which neither setting's name suggests.
Claims were checked against the implementation rather than design notes: managed statement types, mapping resolution order, policy value ranges, the error strings clients see, both table function schemas, the metric names, and the
-1versusNULLdifference between the Prometheus and SQL views of an uncapped group.One ordering note. The pages describe the feature as it stands on the Enterprise branch, including that it disables itself rather than refusing to start when it is left at its default and a SQL worker pool is in legacy mode. This should not merge ahead of that release.