mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-05-30 15:42:25 +00:00
Nanaloveyuki
87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
---
|
|
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.
|