Overhaul concept docs

[tanveergill]

Description of change

Checklist

• Tested in playground or other setup
• Screenshot (Grafana) from playground added to PR for 15+ minute run
• Documentation is changed or added
• Tests and/or benchmarks are included
• Breaking changes

Summary by CodeRabbit

• Documentation
  • Updated internal documentation links and sidebar positions for improved navigation and clarity.
  • Introduced new documentation for the Concurrency Limiter and Request Prioritization features.
  • Enhanced existing documentation with clearer explanations and updated references.
  • Reorganized content to better reflect feature hierarchies and usage.
  • Added new sections on advanced concepts, including detailed guides on scheduling and rate limiting.

[coderabbitai]

Walkthrough

The changes reflect a restructuring and clarification of the documentation for a system's request handling components. The updates include repositioning of sections within the sidebar, refining explanations of scheduling mechanisms, and introducing new concepts like the Concurrency Limiter. Links have been updated to align with the reorganized content, and Prometheus metrics have been enhanced for better observability of the system's flow control capabilities.

Changes

File Path	Change Summary
api/aperture/policy/language/v1/flowcontrol.proto	Updated documentation links for Load Scheduler and workload definition.
docs/content/concepts/advanced/advanced.md	Changed sidebar_position from 8 to 10.
docs/content/concepts/advanced/agent-group.md	Updated hyperlink to point to new quota scheduler documentation location.
docs/content/concepts/cache.md	Updated sidebar_position from 7 to 9.
docs/content/concepts/concurrency-limiter.md	Added new documentation for Concurrency Limiter.
docs/content/concepts/control-point.md	Reordered control points and updated Feature Control Points content.
docs/content/concepts/{flow-label,flow-lifecycle,rate-limiter}.md	Updated links and revised explanations.
docs/content/concepts/request-prioritization/{concurrency-scheduler,load-scheduler,quota-scheduler,request-prioritization}.md	Introduced new documentation and updated sidebar_position, links, and content clarity.
docs/content/concepts/scheduler.md	New documentation detailing Scheduler functionality.
docs/content/concepts/selector.md	Updated link to Load Scheduler documentation.
docs/content/faq.md	Updated links to Load Scheduler and Scheduler documentation.
docs/content/introduction.md	Updated feature names and paths.
docs/content/reference/blueprints/load-scheduling/average-latency.md	Modified description of load scheduler functionality.
docs/content/reference/configuration/spec.md	Updated references to Load Scheduler and workload definition.
docs/content/reference/observability/prometheus-metrics/agent.md	Updated Prometheus metrics descriptions and labels.
pkg/policies/flowcontrol/service/check/metrics.go	Shifted from single counter to counter vector for checkReceivedTotal in Prometheus metrics.

🐇✨
To docs and links anew we hop,
With clearer paths that won't make you stop.
Sidebar dances, metrics in rows,
In Aperture's garden, the understanding grows. 🌱📚

---

Tips

Chat with CodeRabbit Bot (@coderabbitai)

• You can directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit-tests for this file.
• You can tag CodeRabbit on specific lines of code or entire files in the PR by tagging @coderabbitai in a comment. Examples:
  • @coderabbitai generate unit tests for this file.
  • @coderabbitai modularize this function.
• You can tag @coderabbitai in a PR comment and ask questions about the PR and the codebase. Examples:
  • @coderabbitai generate interesting stats about this repository from git and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit tests.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid.
  • @coderabbitai read the files in the src/scheduler package and generate README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• The JSON schema for the configuration file is available here.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/coderabbit-overrides.v2.json

CodeRabbit Discord Community

Join our Discord Community to get help, request features, and share feedback.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 8296f81 and 5e3ce9f.

Files ignored due to filter (12)

• api/buf.lock
• api/gen/proto/go/aperture/policy/language/v1/flowcontrol.pb.go
• blueprints/gen/jsonschema/_definitions.json
• docs/content/assets/openapiv2/aperture-controller.swagger.yaml
• docs/content/assets/openapiv2/aperture.swagger.yaml
• docs/content/concepts/assets/img/scheduler-dark.svg
• docs/content/concepts/assets/img/scheduler-light.svg
• docs/content/concepts/scheduler/assets/img/load-scheduler-dark.svg
• docs/content/concepts/scheduler/assets/img/load-scheduler-light.svg
• docs/content/concepts/scheduler/assets/img/quota-scheduler-dark.svg
• docs/content/concepts/scheduler/assets/img/quota-scheduler-light.svg
• docs/gen/policy/policy.yaml

Files selected for processing (21)

• api/aperture/policy/language/v1/flowcontrol.proto (2 hunks)
• docs/content/concepts/advanced/advanced.md (1 hunks)
• docs/content/concepts/advanced/agent-group.md (1 hunks)
• docs/content/concepts/cache.md (1 hunks)
• docs/content/concepts/concurrency-limiter.md (1 hunks)
• docs/content/concepts/control-point.md (2 hunks)
• docs/content/concepts/flow-label.md (1 hunks)
• docs/content/concepts/flow-lifecycle.md (2 hunks)
• docs/content/concepts/rate-limiter.md (2 hunks)
• docs/content/concepts/request-prioritization/concurrency-scheduler.md (1 hunks)
• docs/content/concepts/request-prioritization/load-scheduler.md (3 hunks)
• docs/content/concepts/request-prioritization/quota-scheduler.md (2 hunks)
• docs/content/concepts/request-prioritization/request-prioritization.md (1 hunks)
• docs/content/concepts/scheduler.md (1 hunks)
• docs/content/concepts/selector.md (1 hunks)
• docs/content/faq.md (1 hunks)
• docs/content/introduction.md (1 hunks)
• docs/content/reference/blueprints/load-scheduling/average-latency.md (1 hunks)
• docs/content/reference/configuration/spec.md (2 hunks)
• docs/content/reference/observability/prometheus-metrics/agent.md (8 hunks)
• pkg/policies/flowcontrol/service/check/metrics.go (3 hunks)

Files skipped from review due to trivial changes (12)

• api/aperture/policy/language/v1/flowcontrol.proto
• docs/content/concepts/advanced/agent-group.md
• docs/content/concepts/cache.md
• docs/content/concepts/concurrency-limiter.md
• docs/content/concepts/control-point.md
• docs/content/concepts/flow-label.md
• docs/content/concepts/flow-lifecycle.md
• docs/content/concepts/rate-limiter.md
• docs/content/concepts/request-prioritization/load-scheduler.md
• docs/content/concepts/request-prioritization/quota-scheduler.md
• docs/content/concepts/selector.md
• docs/content/reference/configuration/spec.md

Additional comments: 17

docs/content/concepts/advanced/advanced.md (1)

• 3-3: Please verify that the change in sidebar_position from 8 to 10 is intentional and correctly reflects the desired order in the sidebar navigation.

docs/content/concepts/request-prioritization/request-prioritization.md (1)

• 2-3: The addition of the Request Prioritization documentation with sidebar_position: 8 looks good. Please ensure this position is consistent with the overall documentation structure.

docs/content/concepts/request-prioritization/concurrency-scheduler.md (1)

• 2-7: The introduction of the Concurrency Scheduler documentation with sidebar_position: 2 is well-detailed. Please confirm that the sidebar position aligns with the documentation structure and that the references are accurate.

docs/content/faq.md (1)

• 112-113: The updates to the hyperlinks for load-scheduler and scheduler in the FAQ section are correct, assuming the new paths accurately reflect the restructured documentation.

pkg/policies/flowcontrol/service/check/metrics.go (1)

• 55-55: The transition to using a CounterVec for checkReceivedTotal with labels for better granularity is a good improvement. Please ensure that the labels used are comprehensive and accurately represent the metrics being tracked.

docs/content/introduction.md (1)

• 53-70: The semantic updates to feature names and paths in the introduction documentation are clear and seem to align with the restructured documentation. Please confirm that the new paths are correct and accessible.

docs/content/concepts/scheduler.md (1)

• 2-9: The addition of the Scheduler documentation with sidebar_position: 7 is comprehensive. Please verify that the sidebar position is correct and that all references and links are accurate and functional.

docs/content/reference/blueprints/load-scheduling/average-latency.md (1)

• 30-35: The rephrased description of the load scheduler's functionality and its interaction with Aperture Agents through etcd provides a clearer understanding of the component's behavior. Ensure that the new terms used, such as "load multiplier," are consistently defined and used across all documentation to avoid confusion.

docs/content/reference/observability/prometheus-metrics/agent.md (9)

• 59-62: The update to the agent_group label description for the Load Scheduler metrics ensures clarity in the documentation. It's important that the new label accurately reflects the policy it belongs to and is consistent with the rest of the documentation.

• 88-97: The changes to the agent_group label and the addition of new labels and metrics for the Rate Limiter improve the granularity and specificity of the metrics. Verify that these label changes are reflected in any dashboards or alerts that may use the old labels to prevent any monitoring disruptions.

• 106-121: Introduction of new metrics and labels for the Concurrency Limiter is a positive change for observability. Ensure that the new metrics are documented in the user-facing documentation and that any systems relying on the old metrics are updated accordingly.

• 148-151: The update to the agent_group label for the Sampler metrics is consistent with the changes in other sections. Confirm that these changes are synchronized with any operational tooling that relies on these labels.

• 178-181: The changes to the agent_group label for the Classifier metrics align with the updates in other metric sections. As with other label changes, ensure that all dependent systems are updated to accommodate these changes.

• 194-199: The addition of new Flow Control metrics enhances the observability of the system. It's crucial to verify that these new metrics are integrated into the monitoring setup and that any documentation for users is updated to include these metrics.

• 209-212: Updating the agent_group label for Flow Control metrics is approved. Ensure that this change is communicated to users and reflected in any related operational tooling.

• 239-242: The update to the agent_group label for Distributed Cache metrics is consistent with updates in other sections. Verify that this change is reflected in all relevant systems and documentation.

• 274-277: The changes to the agent_group label for Scheduler metrics are approved. Ensure that these changes are accurately reflected in all user-facing and internal documentation, as well as any dependent tooling.

[coderabbitai]

Review Status

Actionable comments generated: 0

Configuration used: CodeRabbit UI

Commits

Files that changed from the base of the PR and between 5e3ce9f and 21d408e.

Files selected for processing (2)

• docs/content/concepts/rate-limiter.md (2 hunks)
• docs/content/concepts/request-prioritization/concurrency-scheduler.md (1 hunks)

Files skipped from review as they are similar to previous changes (2)

• docs/content/concepts/rate-limiter.md
• docs/content/concepts/request-prioritization/concurrency-scheduler.md