Skip to main content

AFS_AETHER_JOURNAL_MAX_AGE_SECS

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_MAX_AGE_SECS

Status​

  • active

Audience​

  • production/user

Type and Default​

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

What It Does​

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

Age means:

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

When oldest pending age reaches this threshold, journal backpressure triggers.

Runtime Behavior​

Journal backpressure age-trigger condition:

  • oldest_age >= journal_max_age

Backpressure 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 controls an engage threshold, while AFS_AETHER_JOURNAL_CLEAR_AGE_SECS is its clear-side companion.

Input Surfaces​

  • Env: AFS_AETHER_JOURNAL_MAX_AGE_SECS=<seconds>
  • Config file (aether.toml):
    • [backpressure]
    • journal_max_age_seconds = <seconds>
  • Programmatic override:
    • ConfigOverrides.journal_backpressure_high_age

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 seconds (u64).
  • Must be strictly greater than AFS_AETHER_JOURNAL_CLEAR_AGE_SECS when both are configured; otherwise validation fails.
  • Avoid 0; with age-based backpressure enabled, 0 is not a practical setting.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_CLEAR_AGE_SECS
    • AFS_AETHER_JOURNAL_HIGH_WATER_BYTES
    • AFS_AETHER_JOURNAL_HIGH_WATER_ENTRIES
  • Backpressure engages when any high-water trigger fires (bytes, entries, or age).
  • Backpressure clears only when all low-water checks pass.
  • A larger gap between max-age and clear-age reduces block/clear flapping.

Observability​

  • aether_journal_oldest_entry_age_seconds
  • aether_journal_pending_bytes
  • aether_journal_pending_entries

These signals are the primary way to verify age-trigger engagement and clear readiness.

Example​

export AFS_AETHER_JOURNAL_MAX_AGE_SECS=45
export AFS_AETHER_JOURNAL_CLEAR_AGE_SECS=15
export AFS_AETHER_JOURNAL_HIGH_WATER_BYTES=67108864
export AFS_AETHER_JOURNAL_LOW_WATER_BYTES=50331648

This engages age-based pressure when the oldest pending entry reaches 45s and allows age-side clear once it drops to 15s or lower (with byte/entry low-water checks also met).

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