📝 Document logger config presets

2026-05-30 15:42:25 +00:00 · 2026-05-20 10:07:52 +08:00
parent dca34bc114
commit 4860d1e08b
7 changed files with 492 additions and 0 deletions
@@ -0,0 +1,86 @@
+---
+name: with-file-rotation
+group: api
+category: config
+update-time: 20260520
+description: Add or replace size-based file rotation on an existing file logger config preset.
+key-word:
+    - preset
+    - file
+    - rotation
+    - public
+---
+
+## With-file-rotation
+
+Add or replace a size-based file rotation policy on an existing `LoggerConfig`. This helper is intentionally narrow: it only mutates configs whose sink kind is `File` and leaves every non-file config unchanged.
+
+### Interface
+
+```moonbit
+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`.
+- 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`.
+
+### 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:
+```moonbit
+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:
+```moonbit
+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.