Skip to main content

AFS_AETHER_LOG_ROTATION

Deep-dive reference for:

  • AFS_AETHER_LOG_ROTATION

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: string enum (LogRotation).
  • Accepted values: none, hourly, daily, size (case-insensitive in env input).
  • Default: none.

What It Does​

Controls log-file rollover policy for Aether when file logging is enabled.

Rotation policy is applied only when AFS_AETHER_LOG_DESTINATION=file.

Input Surfaces​

  • Env: AFS_AETHER_LOG_ROTATION=<none|hourly|daily|size>
  • Config file (aether.toml):
    • [logging] rotation = ... (same enum semantics)

There is currently no dedicated CLI flag for log rotation mode.

Resolution and Override Order​

  1. Built-in default (none)
  2. aether.toml ([logging].rotation)
  3. Environment (AFS_AETHER_LOG_ROTATION)

Mode Semantics​

  • none:
    • append to the active log file indefinitely.
  • hourly:
    • time-based rolling file appender with hourly rollover.
  • daily:
    • time-based rolling file appender with daily rollover.
  • size:
    • custom size-based rotation.
    • active file rolls when current_size + write > max_bytes.
    • archives are renamed with numeric suffixes (.1, .2, ...), keeping up to max_files.

When mode is size and limits are not explicitly set, defaults are:

  • max_bytes = 50 * 1024 * 1024 (50 MiB)
  • max_files = 5

Related variables:

  • AFS_AETHER_LOG_ROTATION_MAX_BYTES
  • AFS_AETHER_LOG_ROTATION_MAX_FILES

Setting either of those also forces effective mode to size if current mode is not size.

Interaction With Destination​

  • If destination is stdout or stderr, rotation settings are loaded in config but not used by the active writer.
  • Rotation behavior is only active for file destination.

Validation​

  • Invalid mode value fails config load with:
    • unknown rotation mode '<value>'
  • For size mode, max_bytes and max_files must be greater than zero.

Reload Behavior (SIGHUP)​

log_rotation changes are detected on config reload, but are not hot-applied. The process logs a restart-required warning; rotation changes take effect after restart.

Examples​

  • Disable rotation:
    • AFS_AETHER_LOG_DESTINATION=file AFS_AETHER_LOG_ROTATION=none aether mount --session-id s1 --mount-dir /mnt/aether
  • Daily rotation:
    • AFS_AETHER_LOG_DESTINATION=file AFS_AETHER_LOG_ROTATION=daily aether mount --session-id s1 --mount-dir /mnt/aether
  • Size rotation with explicit limits:
    • AFS_AETHER_LOG_DESTINATION=file AFS_AETHER_LOG_ROTATION=size AFS_AETHER_LOG_ROTATION_MAX_BYTES=104857600 AFS_AETHER_LOG_ROTATION_MAX_FILES=10 aether mount --session-id s1 --mount-dir /mnt/aether
  • AFS_AETHER_LOG_DESTINATION
  • AFS_AETHER_LOG_PATH
  • AFS_AETHER_LOG_ROTATION_MAX_BYTES
  • AFS_AETHER_LOG_ROTATION_MAX_FILES

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/observability/logging.rs
  • packages/aether/src/config/reload.rs