Capacity assessor summary

← Back to docs · Architecture · Decisions · Previous: Grid services · Next: Grid portal

Change: openspec/changes/capacity-assessor (proposal only, no design.md). Crate: crates/welkin-capacity. Status: sections 1 and 2 implemented; sections 3 to 5 are stubs waiting for region-simulator-core (Phase 3).

Purpose

An operator wants to know how many islands a machine can run and how many users can be on them. Published guidance is old and written for the C# server, so the crate scans the host and applies sourced coefficients. Once the simulator exists it will measure instead.

Commits

CommitContent
97f5ebdfeat(capacity): the whole crate: host scan, coefficients, estimate engine, and the stub modules
880338achore: marks the change 13/13 in tasks.md
5fc2401docs: marks capacity-assessor accepted in ROADMAP.md

Implemented (tasks 1.1 to 2.2)

Host scan (host.rs). CPU model, cores, threads and frequency. Memory, with the cgroup v1 and v2 limit read so that effective_bytes is the smaller of host memory and the container limit. Disk total and free space for a path. Container detection with memory limit and CPU quota.

Network (network.rs). A stub: public IP, upload and download speed are optional fields filled by manual configuration. There is no speed test and no public-address detection yet, so task 1.2 is met only in part.

Report (report.rs). HostReport combines the sections above and renders as JSON (to_json) and as text (Display). A command and an API call for the report are not in the crate yet.

Coefficients (coefficients.rs). CoefficientSet carries a version (0.1.0) and 12 coefficients, each with a unit and a source. It loads and saves as JSON. The values and sources are those in the proposal table:

CoefficientValueSource
memory_per_region_mb1024OSgrid wiki tutorial
cpu_cores_per_region1OpenSimulator wiki
cpu_idle_region_fraction0.025OpenSimulator wiki (0.7.6)
memory_base_mb200Hypergrid Business hosting guide
memory_per_1k_prims_mb30Hypergrid Business hosting guide
memory_per_user_mb50Hypergrid Business hosting guide
max_regions_per_simulator4OSgrid forum post
max_regions_per_server16OSgrid forum post
max_agents_per_region100Regions.ini.example
max_prims_per_region15000Regions.ini.example
client_throttle_max_bps187500OpenSimDefaults.ini
scene_throttle_max_bps2500000OpenSimDefaults.ini

Estimate engine (estimate.rs). estimate_capacity takes a host report, a coefficient set and a workload profile.

ProfileAgents per regionPrims per regionScripts fraction
quiet530000.1
typical2080000.3
busy60140000.6
  • CPU limit: (cores minus 1 reserved, floor 0.5) divided by cores per region.
  • Memory limit: (effective memory minus base) divided by per-region memory, where per-region memory is the region figure plus users and prims for the profile.
  • Island count is the lowest of those and max_regions_per_server.
  • Users are islands times agents per region, capped by upload bandwidth divided by the client throttle when upload speed is known.
  • The result is a range of 80% to 120% of the point value, names the limiting resource, and carries is_measured: false.

Disk is scanned but does not yet enter the estimate. The scene throttle, idle-region fraction and per-simulator limit are stored but unused.

Tests. Five unit tests in estimate.rs: quiet on 8 cores and 32 GB, busy on 4 cores and 8 GB, single core reserve, bandwidth-limited, and coefficient round trip.

Stubbed (tasks 3 to 5)

Each module compiles with its types and a TODO marker, and returns empty or placeholder values.

ModuleTaskWaiting on
benchmark.rs3.1 to 3.3: synthetic island, loopback avatars, per-workload runs. Types BenchmarkConfig (default 5000 objects, 1000 scripts, 10 avatars) and BenchmarkResult existregion-simulator-core
model.rs4.1 to 4.3: calibrate_from_benchmark returns an empty CalibratedModel; TradeoffPoint definedbenchmark, then cutover load tests
live.rs5.1 to 5.2: RegionStatistics and CapacityWarning defined, thresholds 80% and 95%; check_warnings returns nothingrunning regions, portal

Status mismatch to resolve

880338a ticks all 13 tasks in tasks.md, and the ROADMAP marks the change accepted. Per the commit message this was a PM decision to accept stubs. The checkboxes for 1.2 (speed test, public address, command and API), 3.x, 4.x and 5.x describe work that is not done. They should be re-opened or moved into the Phase 3 change so the task list matches the code.

Risk

The proposal rates the risk MEDIUM: an estimate that is too high can overload a machine. The current estimate is built from unmeasured, third-party figures, so it always reports a range, the limiting resource and is_measured: false. Coefficients are to be calibrated by the cutover load tests.