Skip to main content

AFS_AETHER_LOG_DESTINATION

Deep-dive reference for:

  • AFS_AETHER_LOG_DESTINATION

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: string enum (LogDestination).
  • Accepted values: stderr, stdout, file (case-insensitive in env input).
  • Default: stderr.

What It Does​

Selects where Aether writes runtime logs:

  • stderr: write logs to standard error.
  • stdout: write logs to standard output.
  • file: write logs to a file (with optional rotation policy).

Input Surfaces​

  • Env: AFS_AETHER_LOG_DESTINATION=<stderr|stdout|file>
  • Config file (aether.toml): 
    [logging]
    destination = "stderr"

There is currently no dedicated CLI flag for log destination.

Resolution and Override Order​

  1. Built-in default (stderr)
  2. aether.toml ([logging].destination)
  3. Environment (AFS_AETHER_LOG_DESTINATION)

File-Destination Behavior​

When destination is file, Aether resolves the log path as:

  1. explicit log path (AFS_AETHER_LOG_PATH or [logging].path)
  2. fallback default: <cache_dir>/logs/aether.log

Notes:

  • Parent directories are created automatically.
  • File rotation behavior comes from AFS_AETHER_LOG_ROTATION and related rotation vars.
  • If path setup/open fails, logging initialization fails and command startup fails.

Interaction With AFS_AETHER_LOG_PATH​

  • Setting AFS_AETHER_LOG_PATH alone does not switch output to file.
  • You must set destination to file for file writing to be used.

Reload Behavior (SIGHUP)​

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

Validation​

  • Invalid env values fail config load with:
    • expected one of stderr, stdout, file
  • Invalid config values fail TOML enum deserialization.

Examples​

  • Send logs to stdout:
    • AFS_AETHER_LOG_DESTINATION=stdout aether mount --session-id s1 --mount-dir /mnt/aether
  • Enable file logs with explicit path:
    • AFS_AETHER_LOG_DESTINATION=file AFS_AETHER_LOG_PATH=/var/log/aether/aether.log aether mount --session-id s1 --mount-dir /mnt/aether
  • Enable file logs with default path under cache root:
    • AFS_AETHER_LOG_DESTINATION=file aether mount --session-id s1 --mount-dir /mnt/aether
  • AFS_AETHER_LOG
  • AFS_AETHER_LOG_PATH
  • AFS_AETHER_LOG_FORMAT
  • AFS_AETHER_LOG_ROTATION
  • 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/apply_env.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/observability/logging.rs
  • packages/aether/src/config/reload.rs