mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-05-30 15:42:25 +00:00
Nanaloveyuki
82 lines
2.0 KiB
Markdown
82 lines
2.0 KiB
Markdown
---
|
|
name: file-rotation
|
|
group: api
|
|
category: sink
|
|
update-time: 20260512
|
|
description: Create a size-based file rotation policy for native file sinks.
|
|
key-word:
|
|
- file
|
|
- rotation
|
|
- policy
|
|
- public
|
|
---
|
|
|
|
## File-rotation
|
|
|
|
Create a size-based file rotation policy for `file_sink(...)`. This helper defines how large a file may grow before rotation and how many historical backups should be retained.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn file_rotation(max_bytes : Int, max_backups~ : Int = 1) -> FileRotation {}
|
|
```
|
|
|
|
#### input
|
|
|
|
- `max_bytes : Int` - Maximum active file size threshold before rotation.
|
|
- `max_backups : Int` - Number of retained backup files.
|
|
|
|
#### output
|
|
|
|
- `FileRotation` - Rotation policy usable by direct file sinks or config-driven sink state.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- `max_bytes <= 0` is normalized to `1`.
|
|
- `max_backups <= 0` is normalized to `1`.
|
|
- Rotation is size-based only.
|
|
- This policy is consumed by `file_sink(...)`, file policy helpers, and config-driven file sink assembly.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need Bounded Local Log Files
|
|
|
|
When a file should not grow without limit:
|
|
```moonbit
|
|
let sink = file_sink(
|
|
"app.log",
|
|
rotation=Some(file_rotation(1024 * 1024, max_backups=3)),
|
|
)
|
|
```
|
|
|
|
In this example, the file rotates after the configured size threshold.
|
|
|
|
And up to three backup files are retained.
|
|
|
|
#### When Need Runtime Policy Composition
|
|
|
|
When file sink policy is assembled explicitly:
|
|
```moonbit
|
|
let policy = FileSinkPolicy::new(rotation=Some(file_rotation(4096, max_backups=2)))
|
|
```
|
|
|
|
In this example, rotation can be bundled with append and auto-flush settings.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If `max_bytes` is non-positive, it is clamped to `1`.
|
|
|
|
- If `max_backups` is non-positive, it is clamped to `1`.
|
|
|
|
### Notes
|
|
|
|
1. This API defines policy only; it does not open files by itself.
|
|
|
|
2. Rotation currently focuses on size thresholds rather than time schedules or compression.
|
|
|