Skip to main content

AFS_AETHER_JOURNAL_LOW_WATER_BYTES

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_LOW_WATER_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 25165824 bytes (24 MiB).

What It Does​

Defines the journal byte low-water threshold used by the backpressure clear path.

This value does not engage journal backpressure by itself. It participates in the condition that allows journal backpressure to clear after a prior block.

Runtime Behavior​

Journal backpressure can engage from any high-water trigger (bytes, entries, or age).

Journal clear remains gated by all low-water checks:

  • pending_bytes <= journal_low_water_bytes
  • pending_entries <= journal_low_water_entries
  • oldest_age <= journal_clear_age

So this variable is one part of the clear gate, not a standalone control.

Input Surfaces​

  • Env: AFS_AETHER_JOURNAL_LOW_WATER_BYTES=<bytes>
  • Config file (aether.toml):
    • [backpressure]
    • journal_low_water_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.journal_backpressure_low_bytes

No dedicated CLI flag currently exists for this specific journal backpressure threshold.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Must parse as unsigned integer bytes (u64).
  • Unit suffixes are not accepted (24MiB is invalid; use raw bytes).
  • 0 is allowed and effectively disables byte-based clear gating.
  • When byte hysteresis is enabled, keep this strictly below AFS_AETHER_JOURNAL_HIGH_WATER_BYTES; otherwise validation fails.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_HIGH_WATER_BYTES
    • AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES
    • AFS_AETHER_JOURNAL_CLEAR_AGE_SECS
  • If bytes are below low-water but entries/age are still above their low-water values, journal pressure does not clear yet.
  • A wider gap between high-water and low-water bytes reduces block/clear flapping.

Observability​

  • aether_journal_pending_bytes
  • aether_journal_pending_entries
  • aether_journal_oldest_entry_age_seconds

These gauges are the primary way to verify whether clear-side thresholds are met.

Example​

export AFS_AETHER_JOURNAL_HIGH_WATER_BYTES=67108864
export AFS_AETHER_JOURNAL_LOW_WATER_BYTES=50331648
export AFS_AETHER_JOURNAL_HIGH_WATER_ENTRIES=4096
export AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES=2048

This engages byte-based pressure at 64 MiB and permits byte-side clear at 48 MiB, while still requiring entries/age low-water conditions to pass.

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/runtime/infra/backpressure/backpressure_types.rs
  • packages/aether/src/runtime/infra/backpressure/coordinator_impl.rs