Skip to content

docs: add autoscaler and scaling policies guide#535

Merged
kcenon merged 2 commits into
mainfrom
docs/issue-530-document-autoscaler-and-scaling-policies
Feb 8, 2026
Merged

docs: add autoscaler and scaling policies guide#535
kcenon merged 2 commits into
mainfrom
docs/issue-530-document-autoscaler-and-scaling-policies

Conversation

@kcenon

@kcenon kcenon commented Feb 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Summary

  • Create comprehensive docs/AUTOSCALER_GUIDE.md documentation for the autoscaling subsystem
  • Cover all 7 sections specified in issue [Task] docs: Document autoscaler and scaling policies #530: architecture, scaling policies, autoscaler API, pool integration, metrics/observability, configuration examples, and best practices
  • Document asymmetric scaling triggers (scale-up OR logic, scale-down AND logic)
  • Include state machine diagram for the monitor loop
  • Provide configuration examples for basic, burst, manual, and shared-autoscaler patterns
  • Add anti-patterns and troubleshooting sections

Closes #530

Test Plan

  • Verify code examples compile against current API (autoscaler.h, autoscaling_policy.h, autoscaling_pool_policy.h)
  • Cross-reference scaling thresholds and defaults with autoscaling_policy.h source
  • Review anti-patterns section against is_valid() implementation
  • Check all internal documentation links resolve

@kcenon
docs: add autoscaler and scaling policies guide (#530)
c120f0c 
Comprehensive documentation for the autoscaling subsystem covering:
- Architecture with monitor loop state machine diagram
- Scaling policies: scale-up OR logic, scale-down AND logic
- Complete autoscaler API reference
- Pool integration via autoscaling_pool_policy
- Metrics and observability (samples, decisions, stats, callbacks)
- Configuration examples for basic, burst, and manual scaling
- Best practices for thresholds, cooldowns, and production monitoring
- Anti-patterns and troubleshooting guide
@kcenon kcenon mentioned this pull request Feb 8, 2026
Closed
6 tasks
@github-actions

github-actions Bot commented Feb 8, 2026

Copy link
Copy Markdown
Contributor

📊 Performance Benchmark Results

Performance Benchmark Report

No benchmark data available.

ℹ️ No baseline reference available

This is the first benchmark run or baseline file is missing.

@kcenon
fix(docs): dereference pool pointer in composing policies example
0de5ec4 
The autoscaling_pool_policy constructor takes thread_pool& but the
example used pool (shared_ptr) instead of *pool.
@kcenon

kcenon commented Feb 8, 2026

Copy link
Copy Markdown
Owner Author

Test Plan Verification Results

All 4 test plan items have been verified against the source code.

1. Code Examples vs Current API

  • 18 API call sites verified against source headers
  • 1 bug found and fixed: autoscaling_pool_policy(pool, ...) → autoscaling_pool_policy(*pool, ...) in Composing Multiple Policies section (line 421)
    • pool->add_policy(...) uses pointer semantics, so constructor expecting thread_pool& requires dereferencing
    • Fixed in commit 0de5ec4
  • All other examples match: constructor signatures, return types, method names, fluent builder patterns

2. Scaling Thresholds and Defaults

  • 18/18 default values match autoscaling_policy.h source exactly
  • All threshold descriptions (OR logic for scale-up, AND logic for scale-down) match source comments

3. Anti-Patterns vs is_valid()

4. Internal Documentation Links

  • 5/5 source file links resolve to existing headers
  • 5/5 related documentation links resolve to existing docs

Summary

Item Status
Code examples compile against current API Fixed 1 bug, rest OK
Scaling thresholds match source All 18 values match
Anti-patterns match is_valid() All 6 accurate
Documentation links resolve All 10 links valid

@github-actions

github-actions Bot commented Feb 8, 2026

Copy link
Copy Markdown
Contributor

📊 Performance Benchmark Results

Performance Benchmark Report

No benchmark data available.

ℹ️ No baseline reference available

This is the first benchmark run or baseline file is missing.

@kcenon kcenon merged commit c9b2998 into main Feb 8, 2026
26 checks passed
@kcenon kcenon deleted the docs/issue-530-document-autoscaler-and-scaling-policies branch February 8, 2026 15:15
kcenon added a commit that referenced this pull request Apr 13, 2026
@kcenon
docs: add autoscaler and scaling policies guide (#535)
647386f 
* docs: add autoscaler and scaling policies guide (#530)

Comprehensive documentation for the autoscaling subsystem covering:
- Architecture with monitor loop state machine diagram
- Scaling policies: scale-up OR logic, scale-down AND logic
- Complete autoscaler API reference
- Pool integration via autoscaling_pool_policy
- Metrics and observability (samples, decisions, stats, callbacks)
- Configuration examples for basic, burst, and manual scaling
- Best practices for thresholds, cooldowns, and production monitoring
- Anti-patterns and troubleshooting guide

* fix(docs): dereference pool pointer in composing policies example

The autoscaling_pool_policy constructor takes thread_pool& but the
example used pool (shared_ptr) instead of *pool.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task] docs: Document autoscaler and scaling policies

1 participant

@kcenon