Skip to main content

AFS_AETHER_JOURNAL_HIGH_WATER_BYTES

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_HIGH_WATER_BYTES

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer bytes (u64).
  • Default: 33554432 bytes (32 MiB).

What It Does​

Defines the journal byte high-water threshold that engages journal-driven transport backpressure.

When pending journal bytes reach this threshold, the backpressure coordinator marks transport as blocked with journal as the source.

Runtime Behavior​

Journal backpressure byte-trigger condition:

  • pending_bytes >= journal_high_water_bytes (and high-water value is > 0)

Clear behavior is still gated by the full low-water checks:

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

So this variable controls a trigger threshold, not a standalone clear threshold.

Input Surfaces​

  • Env: AFS_AETHER_JOURNAL_HIGH_WATER_BYTES=<bytes>
  • Config file (aether.toml):
    • [backpressure]
    • journal_high_water_bytes = <bytes>
  • Programmatic override:
    • ConfigOverrides.journal_backpressure_high_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 (32MiB is invalid; use raw bytes).
  • 0 disables byte-based journal trigger logic from this threshold.
    • Entry-count and age thresholds can still engage journal backpressure.
  • Keep this value strictly greater than AFS_AETHER_JOURNAL_LOW_WATER_BYTES when byte hysteresis is enabled.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_LOW_WATER_BYTES
    • AFS_AETHER_JOURNAL_HIGH_WATER_ENTRIES
    • AFS_AETHER_JOURNAL_MAX_AGE_SECS
  • Backpressure engages when any journal high-water trigger fires (bytes, entries, or age).
  • Backpressure clears only when all configured low-water checks pass, so byte backlog reduction alone may not clear if entry count or age are still above low-water thresholds.

Observability​

  • aether_journal_pending_bytes
  • aether_journal_pending_entries
  • aether_journal_oldest_entry_age_seconds

These are the key gauges to confirm whether byte backlog is crossing the engage threshold and whether low-water conditions are met for clear.

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 journal pressure when pending bytes reach 64 MiB and allows byte-side clear once pending bytes drain to 48 MiB or lower (with entry/age low-water checks also satisfied).

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