GC auto-tuning

Status: Production-ready Contract: RFC-2026-034 §12 (AngaraGC Phase 4 auto-tuning)

Overview

AngaraGC auto-tuning automatically adjusts Garbage Collection budgets based on workload telemetry:

Bloat ratio — how much dead data accumulates
Epoch lag — how far behind active transactions are from committed state
Cycle latency — how long each GC cycle takes

The controller uses a PID-like feedback loop to balance aggressive cleanup (high budget) against latency impact (low budget).

Configuration

Enable auto-tuning

export ANGARABASE_GC_BACKGROUND=1 # Enable GC background worker
export ANGARABASE_GC_AUTO_TUNING=1 # Enable auto-tuning controller

Or via config file:

[gc]
auto_tuning_enabled = true

Tuning parameters (optional)

Default values are production-safe. Override only if you understand the trade-offs:

# Target bloat ratio (default: 20%)
export ANGARABASE_GC_TARGET_BLOAT_RATIO=20

# Target epoch lag (default: 1000 epochs)
export ANGARABASE_GC_TARGET_LAG=1000

# Latency spike threshold (default: 100ms)
export ANGARABASE_GC_LATENCY_THRESHOLD=100

# Budget bounds (default: 100..100000 tuples/cycle)
export ANGARABASE_GC_BUDGET_MIN=100
export ANGARABASE_GC_BUDGET_MAX=100000

Monitoring

View current auto-tuning state

SELECT * FROM sys.gc_tuning_status;

Returns:

current_budget — current GC budget (tuples/cycle)
current_sleep_ms — current sleep interval between cycles
tuning_decision — last decision (increase, decrease, hold)

Prometheus metrics

# Controller state
angarabase_gc_tuning_budget_tuples_per_cycle
angarabase_gc_tuning_sleep_ms
angarabase_gc_tuning_bloat_ratio_percent
angarabase_gc_tuning_min_active_epoch_lag
angarabase_gc_tuning_cycle_duration_ms_last

# Decision counters
angarabase_gc_tuning_decision_total_increase
angarabase_gc_tuning_decision_total_decrease
angarabase_gc_tuning_decision_total_hold

Operational notes

When to enable

Production workloads with variable load: auto-tuning adapts to workload changes
High bloat risk: auto-tuning increases budget when bloat accumulates
Latency-sensitive workloads: auto-tuning backs off when GC causes latency spikes

When NOT to enable

Predictable workloads with stable budget: manual tuning may be simpler
Debugging GC issues: disable auto-tuning to isolate issues with fixed budget

Bounds safety

Controller never violates min_budget or max_budget
Bounds clamp adaptive adjustments, ensuring predictable worst-case behavior
Default bounds are conservative; adjust only after profiling

Troubleshooting

Auto-tuning oscillates

Symptom: Decision alternates increase/decrease rapidly.

Fix: Increase latency threshold or bloat target to reduce sensitivity:

export ANGARABASE_GC_LATENCY_THRESHOLD=200 # more tolerance for latency
export ANGARABASE_GC_TARGET_BLOAT_RATIO=30 # more tolerance for bloat

Budget stuck at min/max

Symptom: current_budget reaches bound and stays there.

Diagnosis:

Stuck at max: Bloat or lag persistently above target → increase max_budget or investigate workload
Stuck at min: Latency spikes persist → investigate GC contention or reduce GC work

Reference

RFC-2026-034 §12: AngaraGC auto-tuning design
Implementation scope
crates/angarabased/src/gc_worker.rs: Controller implementation
crates/angarabase/src/virtual_catalog/mod.rs: sys.gc_tuning_status view

After angara_gc.auto_tuning = on and GC metrics have stabilized:

Diagnostics — how to read sys.health and GC metrics under load.
Monitoring — which alerts to create for the “GC backlog is growing” area.
Transactions and MVCC — conceptually, what AngaraGC cleans up.

AngaraBook