Skip to main content

AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS

Deep-dive reference for:

  • AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer milliseconds (u64).
  • Default: 5 ms.

What It Does​

Defines the timer cadence for journal WAL flushes when sync policy is interval.

This is a durability/flush scheduling control. It does not directly control transport backpressure.

Runtime Behavior​

In interval sync policy, the controller schedules a deadline every journal_sync_interval and flushes WAL when the deadline elapses and pending bytes are non-zero.

Timer-driven flushes are recorded with reason interval.

Policy interactions:

  • interval: timer is active and this value is used.
  • manual: timer is disabled; this value is ignored.
  • immediate: per-append flush path is used; background timer cadence does not apply.

Input Surfaces​

  • Env: AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS=<milliseconds>
  • Config file (aether.toml, top-level key):
    • journal_sync_interval_ms = <milliseconds>
  • Programmatic override:
    • ConfigOverrides.journal_sync_interval (Duration)

No dedicated CLI flag currently exists for this specific WAL sync timer interval.

Resolution and Override Order​

  • Defaults < aether.toml < environment < overrides.

Value Rules​

  • Must parse as unsigned integer milliseconds (u64).
  • Must be greater than zero.
    • 0 is rejected by config/env validation.

Important Interaction Notes​

  • Tune alongside:
    • AFS_AETHER_JOURNAL_SYNC_POLICY
    • AFS_AETHER_JOURNAL_SYNC_BACKLOG_BYTES
  • Smaller intervals flush more frequently (lower average pending bytes, higher flush overhead).
  • Larger intervals flush less frequently unless backlog threshold triggers earlier.
  • Config reload can update this interval at runtime; observers rebuild sync config and apply it.

Observability​

  • aether_journal_wal_flush_total with labels:
    • reason=interval|backlog|manual|shutdown
    • outcome=success|error
  • aether_journal_sync_count_total with label:
    • policy=interval|backlog|manual|shutdown

These counters confirm timer-driven flush activity and outcomes.

Example​

export AFS_AETHER_JOURNAL_SYNC_POLICY=interval
export AFS_AETHER_JOURNAL_SYNC_INTERVAL_MS=20
export AFS_AETHER_JOURNAL_SYNC_BACKLOG_BYTES=4194304

This sets interval mode to flush on a 20ms cadence, while still allowing earlier flushes when pending append bytes hit 4 MiB.

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/journal/sync.rs
  • packages/aether/src/config/reload.rs
  • packages/aether/src/metrics/names.rs