Skip to main content

AFS_AETHER_LOG_PATH

Deep-dive reference for:

  • AFS_AETHER_LOG_PATH

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: filesystem path (PathBuf).
  • Default:
    • unset (None) as a raw config value
    • effective default for file logging: <cache_dir>/logs/aether.log

What It Does​

Specifies the file path used for Aether logs when AFS_AETHER_LOG_DESTINATION=file.

If destination is stdout or stderr, this path is stored in config but not used as the active log writer target.

Input Surfaces​

  • Env: AFS_AETHER_LOG_PATH=/path/to/aether.log
  • Config file (aether.toml): 
    [logging]
    path = "/path/to/aether.log"

There is currently no dedicated CLI flag for log path.

Resolution and Override Order​

  1. Built-in default (no explicit path)
  2. aether.toml ([logging].path)
  3. Environment (AFS_AETHER_LOG_PATH)

Effective Path Resolution​

resolved_log_path() behaves as:

  • destination = file:
    • explicit path if set, otherwise <cache_dir>/logs/aether.log
  • destination = stdout or stderr:
    • returns explicit log_path only if set, otherwise None

Logging Runtime Behavior​

  • File destination:
    • parent directories are created as needed
    • file is opened/appended (or rotated, depending on rotation settings)
  • Stdout/stderr destination:
    • writer ignores log_path

aether logs tail Behavior​

aether logs tail resolves the file to tail in this order:

  1. config.resolved_log_path()
  2. direct env lookup via AFS_AETHER_LOG_PATH

If neither yields a path, it reports that logs are on stdout/stderr and tailing is unavailable.

Validation and Failure Modes​

  • Path value itself is not strongly validated at parse time.
  • Runtime startup fails if file destination cannot open/create the path.
  • With hourly/daily rotation, paths without a directory component can fail path splitting.

Reload Behavior (SIGHUP)​

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

Examples​

  • Explicit file log path:
    • AFS_AETHER_LOG_DESTINATION=file AFS_AETHER_LOG_PATH=/var/log/aether/aether.log aether mount --session-id s1 --mount-dir /mnt/aether
  • Use default file path under cache root:
    • AFS_AETHER_LOG_DESTINATION=file aether mount --session-id s1 --mount-dir /mnt/aether
  • AFS_AETHER_LOG_DESTINATION
  • AFS_AETHER_LOG_ROTATION
  • AFS_AETHER_LOG_ROTATION_MAX_BYTES
  • AFS_AETHER_LOG_ROTATION_MAX_FILES
  • AFS_AETHER_CACHE_DIR

Primary Implementation Sources​

  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/observability/logging.rs
  • packages/aether/src/config/reload.rs
  • packages/aether-cli/src/app/dispatch_and_runtime.rs