Skip to main content

AFS_AETHER_JOURNAL_CLEAR_AGE_SECS

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_CLEAR_AGE_SECS

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer seconds (u64).
  • Default: 10 seconds.

What It Does​

Defines the journal age low-water threshold used to clear journal-driven transport backpressure.

Age here means:

  • age of the oldest pending journal entry (now - oldest_entry_timestamp)

This is the clear-side companion to AFS_AETHER_JOURNAL_MAX_AGE_SECS (the engage threshold).

Runtime Behavior​

Journal backpressure engages when any high-water trigger fires (bytes, entries, or age).

Journal backpressure clears only when all low-water checks pass:

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

So this variable does not clear pressure by itself; it is part of the full low-water gate.

Input Surfaces​

  • Env: AFS_AETHER_JOURNAL_CLEAR_AGE_SECS=<seconds>
  • Config file (aether.toml):
    • [backpressure]
    • journal_clear_age_seconds = <seconds>
  • Programmatic override:
    • ConfigOverrides.journal_backpressure_low_age

No dedicated CLI flag currently exists for this specific backpressure age setting.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Must parse as unsigned integer seconds (u64).
  • Must be strictly less than AFS_AETHER_JOURNAL_MAX_AGE_SECS when both are configured.
    • Otherwise config validation fails.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_MAX_AGE_SECS
    • AFS_AETHER_JOURNAL_LOW_WATER_BYTES
    • AFS_AETHER_JOURNAL_LOW_WATER_ENTRIES
  • A larger gap between max-age and clear-age reduces backpressure flapping.
  • After trim operations, oldest-entry age is recomputed from the remaining journal head entry, so age-based clear behavior reflects actual backlog state.

Observability​

  • aether_journal_oldest_entry_age_seconds
  • aether_journal_pending_bytes
  • aether_journal_pending_entries

These are the core signals to confirm age/queue drain and backpressure clear behavior.

Example​

export AFS_AETHER_JOURNAL_MAX_AGE_SECS=30
export AFS_AETHER_JOURNAL_CLEAR_AGE_SECS=10
export AFS_AETHER_JOURNAL_HIGH_WATER_BYTES=33554432
export AFS_AETHER_JOURNAL_LOW_WATER_BYTES=25165824

This engages age-based pressure at 30s and allows age-based clear once oldest pending entry age falls to 10s or below (and bytes/entries low-water conditions are 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/journal/backend/journal_store_impl.rs
  • packages/aether/src/runtime/journal/backend/journal_store_types.rs