BitLogger/docs/api/with-file-rotation.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
with-file-rotation	api	config	20260520	Add or replace size-based file rotation on an existing file logger config preset.	preset file rotation public

With-file-rotation

Add or replace a size-based file rotation policy on an existing LoggerConfig. On the root src facade, this helper forwards to the preset builder owned by src/presets_pkg and rewrites the shared config model owned by src/config_model.

Interface

pub fn with_file_rotation(
  config : LoggerConfig,
  max_bytes : Int,
  max_backups~ : Int = 1,
) -> LoggerConfig {

input

• config : LoggerConfig - Base logger config to inspect and possibly update.
• max_bytes : Int - Maximum active file size before rotation.
• max_backups : Int - Number of rotated backup files to retain.

output

• LoggerConfig - Updated file config with rotation, or the original config unchanged when the sink is not file-based.

Explanation

Detailed rules explaining key parameters and behaviors

• with_file_rotation(...) only applies to file presets or other configs whose sink.kind=SinkKind::File.
• The root with_file_rotation(...) entry is a facade over @presets_pkg.with_file_rotation(...).
• The resulting sink.rotation field still uses the shared @file_model.FileRotation model.
• If the input config is not file-based, the helper returns the config unchanged.
• When the input config is file-based, the helper preserves min_level, target, timestamp, file path, append mode, auto-flush, formatter, and queue settings while replacing sink.rotation.
• Rotation policy creation follows file_rotation(...) normalization rules for max_bytes and max_backups.
• The default max_bytes : Int path keeps the standard 32-bit Int contract for config-built file rotation.
• If a native-only large-file threshold is required, use with_file_rotation_i64(...) rather than overloading the default Int path.

How to Use

Here are some specific examples provided.

When Need To Extend A File Preset

When file rotation should be added after the base preset is assembled:

let config = with_file_rotation(file("service.log"), 1024 * 1024, max_backups=3)

In this example, the file preset gains a size-based rotation policy.

And all other file sink settings remain unchanged.

When Compose Queue And Rotation Together

When the file logger also needs bounded queueing:

let config = with_file_rotation(
  with_queue(file("service.log"), max_pending=32),
  4096,
  max_backups=2,
)

In this example, queue settings are preserved while file rotation is added.

Error Case

e.g.:

• If the input config is not file-based, no error is raised and the config is returned unchanged.

• If max_bytes or max_backups are non-positive, normalization behavior follows file_rotation(...).

Notes

1. This helper is a no-op for console(...), json_console(...), and text_console(...) presets.

2. Use file(...) when you need to provide the initial file path, because with_file_rotation(...) does not create a file sink from a non-file config.

3. The wider with_file_rotation_i64(...) path is additive and native-focused; it does not replace the default config contract.