Skip to main content

AFS_AETHER_JOURNAL_HIGH_WATER_ENTRIES

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_HIGH_WATER_ENTRIES

Status​

  • active

Audience​

  • production/user

Type and Default​

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

What It Does​

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

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

Runtime Behavior​

Journal backpressure entry-trigger condition:

  • pending_entries >= journal_high_water_entries (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_ENTRIES=<count>
  • Config file (aether.toml):
    • [backpressure]
    • journal_high_water_entries = <count>
  • Programmatic override:
    • ConfigOverrides.journal_backpressure_high_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 disables entry-count journal trigger logic from this threshold.
    • Byte and age thresholds can still engage journal backpressure.
  • Keep this value strictly greater than AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES when entry-count hysteresis is enabled.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES
    • AFS_AETHER_JOURNAL_HIGH_WATER_BYTES
    • 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 entry-count reduction alone may not clear if bytes or age are still above low-water thresholds.

Observability​

  • aether_journal_pending_entries
  • aether_journal_pending_bytes
  • aether_journal_oldest_entry_age_seconds

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

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 journal pressure when pending entries reach 8192 and allows entry-side clear once pending entries drain to 4096 or lower (with byte/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