Skip to main content

AFS_AETHER_LOG

Deep-dive reference for:

  • AFS_AETHER_LOG

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: string enum (LogLevel).
  • Accepted values: error, warn, info, debug, trace (case-insensitive in env input).
  • Default: info.

What It Does​

Sets the baseline Aether logging level used to build the tracing filter when RUST_LOG is not set.

In practice, this controls how much log detail Aether emits:

  • error: only errors
  • warn: warnings and errors
  • info: normal operational logs (default)
  • debug: debug + info/warn/error
  • trace: most verbose

Input Surfaces​

  • Env: AFS_AETHER_LOG=<level>
  • Config file (aether.toml): log_level = "<level>"
  • CLI:
    • aether mount --log-level <level>
    • global --quiet (forces error)
    • global --verbose / -v (forces debug with one -v, trace with -vv)

Resolution and Override Order​

  1. Built-in default (info)
  2. aether.toml (log_level)
  3. Environment (AFS_AETHER_LOG)
  4. CLI overrides (--log-level, --quiet, --verbose)

Important runtime caveat:

  • If RUST_LOG is set and valid, tracing uses that env filter instead of the AFS_AETHER_LOG-derived level.

Reload Behavior (SIGHUP)​

  • Config reload detects log_level changes and attempts hot-apply.
  • If logger filter source is config-derived, new level is applied without restart.
  • If RUST_LOG override is active, reload logs that the level change is skipped.

Validation​

  • Invalid AFS_AETHER_LOG env value fails config load with an explicit "expected one of error, warn, info, debug, trace" error.
  • Invalid log_level in aether.toml fails TOML deserialization.
  • Invalid CLI --log-level values are rejected by clap argument parsing.

Examples​

  • Set default runtime verbosity from env:
    • AFS_AETHER_LOG=debug aether mount --session-id s1 --mount-dir /mnt/aether
  • Override env/config at invocation time:
    • aether mount --log-level trace --session-id s1 --mount-dir /mnt/aether
  • Force quiet output:
    • aether --quiet mount --session-id s1 --mount-dir /mnt/aether
  • AFS_AETHER_LOG_FORMAT
  • AFS_AETHER_LOG_DESTINATION
  • AFS_AETHER_LOG_PATH
  • 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
  • packages/aether-cli/src/cli/args/cli_option_args.rs
  • packages/aether-cli/src/cli/args/cli_root_commands.rs