Skip to main content

AFS_AETHER_JOURNAL_SYNC_POLICY

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_SYNC_POLICY

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: enum string (immediate | manual | interval).
  • Default: interval.

What It Does​

Selects the journal WAL synchronization strategy.

This setting controls when WAL flushes happen automatically and how append traffic is handled by the journal sync controller.

Runtime Behavior​

  • interval
    • Enables timer-driven WAL flushes using AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS.
    • Also allows early flushes when pending append bytes reach AFS_AETHER_JOURNAL_SYNC_BACKLOG_BYTES.
  • manual
    • Disables timer/backlog automatic flushing.
    • WAL flushes occur only on explicit manual flush calls (and on shutdown if pending data exists).
  • immediate
    • Disables background append tracking in the sync controller.
    • At mount/storage initialization, storage write options enable synchronous writes for this policy (sync_writes = true), so durability is pushed to the backend write path.

Input Surfaces​

  • Env: AFS_AETHER_JOURNAL_SYNC_POLICY=immediate|manual|interval
  • Config file (aether.toml, top-level key):
    • journal_sync_policy = "interval"
  • Programmatic override:
    • ConfigOverrides.journal_sync_policy

No dedicated CLI flag currently exists for this policy.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Accepted values: immediate, manual, interval.
  • Invalid values are rejected with a config error listing supported variants.
  • Env parsing accepts these canonical variant names.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS
    • AFS_AETHER_JOURNAL_SYNC_BACKLOG_BYTES
  • interval uses both timer and backlog thresholds.
  • manual ignores interval/backlog for automatic flushing.
  • immediate startup config enables storage-level sync writes.
  • Runtime policy updates change sync-controller behavior via update_sync_config.

Observability​

  • aether_journal_wal_flush_total with labels:
    • reason=backlog|interval|manual|shutdown
    • outcome=success|error
  • aether_journal_sync_count_total with label:
    • policy=backlog|interval|manual|shutdown
  • aether_journal_sync_total and aether_journal_sync_duration_seconds capture explicit sync/flush operations in storage journal paths.

Examples​

# Default-style interval behavior
export AFS_AETHER_JOURNAL_SYNC_POLICY=interval
export AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS=5
export AFS_AETHER_JOURNAL_SYNC_BACKLOG_BYTES=2097152

# Manual-only flushing
export AFS_AETHER_JOURNAL_SYNC_POLICY=manual

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/config/types/storage_builder.rs
  • packages/aether/src/runtime/journal/sync.rs
  • packages/aether/src/runtime/journal/backend/journal_store_types.rs
  • packages/aether/src/runtime/journal/backend/journal_store_impl.rs
  • packages/aether/src/config/reload.rs
  • packages/aether/src/metrics/names.rs