GC auto-tuning

AngaraGC automatically adjusts the garbage-collection budget to the workload from telemetry:

• Bloat ratio — how much dead data has accumulated;
• Epoch lag — how far active transactions trail the committed state;
• Cycle latency — how long each GC cycle takes.

The controller uses a feedback loop, balancing aggressive cleanup (high budget) against latency impact (low budget).

Enabling

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

Or via config ([gc] auto_tuning is on by default):

[gc]
auto_tuning = true

The controller’s targets are fixed (set in the implementation, not configurable): bloat target ≈ 20%, epoch-lag target ≈ 1000, latency-spike threshold ≈ 100 ms, budget bounds 100..100000 rows/cycle, sleep 10..1000 ms. The controller never leaves the min/max budget.

Observability

SELECT * FROM sys.gc_tuning_status;

Columns:

• current_budget — current GC budget (rows/cycle);
• sleep_ms — current pause between cycles;
• tuning_decision — last decision (increase / decrease / hold).

Prometheus metrics:

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
angarabase_gc_tuning_decision_total_increase
angarabase_gc_tuning_decision_total_decrease
angarabase_gc_tuning_decision_total_hold

When to enable

• Variable load — auto-tuning adapts to changes.
• High bloat risk — raises the budget as dead versions accumulate.
• Latency-sensitive workloads — backs off on latency spikes.

When not to: a predictable workload with a stable budget (a static mode is simpler — disable auto-tuning and set a fixed budget in [gc]); or while debugging GC, to isolate behavior with a fixed budget.

Troubleshooting

Auto-tuning oscillates (tuning_decision alternates increase/decrease rapidly): the controller is self-correcting; if oscillation persists, disable auto-tuning (ANGARABASE_GC_AUTO_TUNING=0) and use a static budget.

Budget stuck at min/max (current_budget reaches a bound):

• at max — bloat/lag persistently above target → investigate the workload;
• at min — persistent latency spikes → look for GC contention or reduce GC work.

Next

Once gc.auto_tuning is on and GC metrics have settled:

• Diagnostics — reading sys.health and GC metrics under load.
• Monitoring — alerts for a growing GC backlog.
• Transactions and MVCC — what AngaraGC cleans up.