Skip to main content

AFS_AETHER_LOG_SAMPLE_INVALIDATION

Deep-dive reference for:

  • AFS_AETHER_LOG_SAMPLE_INVALIDATION

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: unsigned integer divisor (u32).
  • Default: 32.
  • Normalization: values are clamped to at least 1 (0 becomes 1).

What It Does​

Controls debug/trace log sampling for invalidation-related log targets.

Specifically, this applies to log targets beginning with:

  • aether::runtime::invalidation

Sampling is 1-in-N:

  • 1 => log every matching debug/trace event
  • 32 => log approximately every 32nd matching debug/trace event (default)
  • higher values => less verbose logs

Input Surfaces​

  • Env: AFS_AETHER_LOG_SAMPLE_INVALIDATION=<N>
  • Config file (aether.toml): 
    [logging.sampling]
    invalidation_debug_every = 32

There is currently no dedicated CLI flag for this setting.

Resolution and Override Order​

  1. Built-in default (32)
  2. aether.toml ([logging.sampling].invalidation_debug_every)
  3. Environment (AFS_AETHER_LOG_SAMPLE_INVALIDATION)

Sampling Scope Details​

  • Only affects matching debug/trace-level targets.
  • Log records at info level and above are always emitted (not sampled away).
  • Non-matching targets are unaffected.

Validation and Normalization​

  • Non-numeric env values fail config load.
  • 0 is accepted but normalized to 1.
  • In config file parsing, 0 is also normalized to 1.

Reload Behavior (SIGHUP)​

Changes to log sampling config are detected but not hot-applied; restart is required.

Examples​

  • Disable sampling for invalidation debug logs:
    • AFS_AETHER_LOG_SAMPLE_INVALIDATION=1 aether mount --session-id s1 --mount-dir /mnt/aether
  • Reduce invalidation debug volume:
    • AFS_AETHER_LOG_SAMPLE_INVALIDATION=100 aether mount --session-id s1 --mount-dir /mnt/aether
  • AFS_AETHER_LOG_SAMPLE_PREFETCH
  • AFS_AETHER_LOG
  • AFS_AETHER_LOG_FORMAT

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