Skip to main content

AFS_AETHER_CACHE_MAX_BYTES

Deep-dive reference for:

  • AFS_AETHER_CACHE_MAX_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 0 (documented as disabled / unlimited).

What It Does​

Configures the clean-cache byte budget used by Aether cache limiter flows.

This setting is separate from dirty-byte limits. Dirty data is governed by AFS_AETHER_CACHE_DIRTY_MAX_BYTES.

Runtime Behavior​

  • Mount startup wires this value into CacheLimits.max_bytes.
  • The limiter forwards that budget into the tiered in-memory cache (TieredCacheConfig.total_budget_bytes).
  • The tiered cache applies this budget to evictable tiers (prefetch, borrowed, clean) and uses weighted entry sizes (entry.length) to drive eviction.

Current integration note:

  • Enforcement is primarily eviction-based at the in-memory tier level.
  • There is no dedicated clean-limit-exceeded counter/error path currently emitted for this knob.
  • This setting is not the disk free-space guardrail; disk-pressure backpressure is controlled by:
    • AFS_AETHER_CACHE_DISK_LOW_FREE_BYTES / AFS_AETHER_CACHE_DISK_HIGH_FREE_BYTES
    • AFS_AETHER_CACHE_DISK_LOW_FREE_PERCENT / AFS_AETHER_CACHE_DISK_HIGH_FREE_PERCENT

Input Surfaces​

  • Env: AFS_AETHER_CACHE_MAX_BYTES=<bytes>
  • Config file (aether.toml):
    • cache_max_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.cache_max_bytes

No dedicated CLI flag is currently exposed for this variable.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Must parse as unsigned integer bytes (u64).
  • Unit suffixes are not accepted (1GiB is invalid; use raw bytes).
  • 0 is the documented disable value.

Implementation nuance:

  • Tier budget normalization in the tiered cache path clamps per-tier capacities to at least 1 byte.
  • In practice, 0 does not produce an unbounded tier budget in that path.

Interactions and Notes​

  • Pair with AFS_AETHER_CACHE_DIRTY_MAX_BYTES:
    • CACHE_MAX_BYTES controls clean/evictable tier budget behavior.
    • CACHE_DIRTY_MAX_BYTES controls hard dirty-byte acceptance/rejection.
  • Backpressure thresholds are separate controls:
    • dirty watermarks (AFS_AETHER_CACHE_DIRTY_HIGH_WATER_BYTES, AFS_AETHER_CACHE_DIRTY_LOW_WATER_BYTES)
    • disk-free watermarks (the AFS_AETHER_CACHE_DISK_* variables).

Observability​

  • Configured clean-limit gauge: aether_cache_max_bytes
  • Cache bytes gauge by state: aether_cache_bytes_total{state=clean|dirty|borrowed|prefetch}
  • Utilization gauge (reported when limit > 0): aether_cache_utilization_percent
  • Related tier gauges:
    • aether_cache_l1_entries
    • aether_cache_l1_bytes
    • aether_cache_l2_entries
    • aether_cache_l2_bytes_clean
    • aether_cache_l2_bytes_dirty

Example​

export AFS_AETHER_CACHE_MAX_BYTES=2147483648

This sets the cache limiter clean-cache budget to 2 GiB (raw bytes).

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/aether/src/cache/limiter/limiter_types.rs
  • packages/aether/src/cache/limiter/limiter_impl.rs
  • packages/aether/src/cache/moka_facade/config.rs
  • packages/aether/src/cache/moka_facade/tiered.rs