Skip to main content

AFS_AETHER_LOG_FORMAT

Deep-dive reference for:

  • AFS_AETHER_LOG_FORMAT

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: string enum (LogFormat).
  • Accepted values: json, text (case-insensitive in env input).
  • Default: json.

What It Does​

Controls the output structure of Aether log events.

  • json:
    • emits one JSON object per log line
    • includes structured keys like level/target/component plus event fields
  • text:
    • emits human-readable single-line logs with key/value fields

Input Surfaces​

  • Env: AFS_AETHER_LOG_FORMAT=<json|text>
  • Config file (aether.toml): 
    [logging]
    format = "json"

There is currently no dedicated CLI flag for log format.

Resolution and Override Order​

  1. Built-in default (json)
  2. aether.toml ([logging].format)
  3. Environment (AFS_AETHER_LOG_FORMAT)

Format Semantics​

json format:

  • Serializes each event as JSON.
  • Adds standard keys including timestamp (when enabled), level, target, component, trace_id, and session_id, plus event fields.

text format:

  • Renders level/component/target followed by message and key/value fields.
  • Includes session_id from the event or configured session context when available.

ANSI Color Interaction​

  • ANSI/color output is only enabled for text format.
  • For json, ANSI is disabled regardless of CLI color setting.

Reload Behavior (SIGHUP)​

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

Validation​

  • Invalid env values fail config load with:
    • expected one of text, json
  • Invalid config values fail TOML enum deserialization.

Examples​

  • JSON logs (recommended for ingestion):
    • AFS_AETHER_LOG_FORMAT=json aether mount --session-id s1 --mount-dir /mnt/aether
  • Text logs (human-readable):
    • AFS_AETHER_LOG_FORMAT=text aether mount --session-id s1 --mount-dir /mnt/aether
  • AFS_AETHER_LOG
  • AFS_AETHER_LOG_DESTINATION
  • AFS_AETHER_LOG_PATH
  • AFS_AETHER_LOG_REDACT
  • AFS_AETHER_LOG_SAMPLE_PREFETCH
  • AFS_AETHER_LOG_SAMPLE_INVALIDATION

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