Skip to main content

AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer count (u64).
  • Default: 2048 entries.

What It Does​

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

This value does not engage journal backpressure by itself. It is one of the conditions that must pass before journal backpressure can 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_ENTRIES=<count>
  • Config file (aether.toml):
    • [backpressure]
    • journal_low_water_entries = <count>
  • Programmatic override:
    • ConfigOverrides.journal_backpressure_low_entries

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 count (u64).
  • 0 is allowed and effectively disables entry-count clear gating.
  • When entry-count hysteresis is enabled, keep this strictly below AFS_AETHER_JOURNAL_HIGH_WATER_ENTRIES; otherwise validation fails.

Important Interaction Notes​

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

Observability​

  • aether_journal_pending_entries
  • aether_journal_pending_bytes
  • 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_ENTRIES=8192
export AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES=4096
export AFS_AETHER_JOURNAL_HIGH_WATER_BYTES=67108864
export AFS_AETHER_JOURNAL_LOW_WATER_BYTES=50331648

This engages entry-based pressure at 8192 entries and permits entry-side clear at 4096, while still requiring byte/age low-water checks 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