diff --git a/docs/api/console.md b/docs/api/console.md new file mode 100644 index 0000000..803a31d --- /dev/null +++ b/docs/api/console.md @@ -0,0 +1,73 @@ +--- +name: console +group: api +category: config +update-time: 20260520 +description: Create a minimal logger config preset for the built-in console sink. +key-word: + - preset + - console + - config + - public +--- + +## Console + +Create a `LoggerConfig` preset for the built-in plain console sink. This helper is the shortest way to assemble a config-driven logger that writes directly to the terminal without text formatter customization. + +### Interface + +```moonbit +pub fn console( + min_level~ : Level = Level::Info, + target~ : String = "", + timestamp~ : Bool = false, +) -> LoggerConfig { +``` + +#### input + +- `min_level : Level` - Minimum enabled level for the preset. +- `target : String` - Default target stored in the returned config. +- `timestamp : Bool` - Whether the built logger should emit timestamps. + +#### output + +- `LoggerConfig` - Config using `SinkKind::Console` with no queue wrapper by default. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This preset always returns `sink.kind=SinkKind::Console`. +- `queue=None` by default, so output remains unqueued unless `with_queue(...)` is applied later. +- This helper only selects the sink shape and top-level logger config fields; it does not build a runtime logger by itself. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Minimal Terminal Config + +When application startup wants a simple console config: +```moonbit +let config = console(min_level=Level::Debug, target="cli") +let logger = build_logger(config) +``` + +In this example, the logger uses the built-in console sink. + +And no extra queue or file policy is configured. + +### Error Case + +e.g.: +- If `target` is empty, the config is still valid. + +- If later runtime assembly targets an environment with sink-specific limitations, those runtime rules still apply outside this preset. + +### Notes + +1. Use this preset when you want the shortest path to console output. + +2. Apply `with_queue(...)` separately if bounded synchronous buffering is needed. diff --git a/docs/api/file.md b/docs/api/file.md new file mode 100644 index 0000000..df4f931 --- /dev/null +++ b/docs/api/file.md @@ -0,0 +1,100 @@ +--- +name: file +group: api +category: config +update-time: 20260520 +description: Create a logger config preset for the built-in file sink with optional rotation and formatter settings. +key-word: + - preset + - file + - rotation + - public +--- + +## File + +Create a `LoggerConfig` preset for the built-in file sink. This helper packages file path, append policy, auto-flush behavior, optional rotation, and text formatter settings into a single config object for runtime logger assembly. + +### Interface + +```moonbit +pub fn file( + path : String, + min_level~ : Level = Level::Info, + target~ : String = "", + timestamp~ : Bool = false, + append~ : Bool = true, + auto_flush~ : Bool = true, + rotation~ : FileRotation? = None, + text_formatter~ : TextFormatterConfig = default_text_formatter_config(), +) -> LoggerConfig raise ConfigError { +``` + +#### input + +- `path : String` - Output file path for the file sink. +- `min_level : Level` - Minimum enabled level for the preset. +- `target : String` - Default target stored in the returned config. +- `timestamp : Bool` - Whether the built logger should emit timestamps. +- `append : Bool` - Whether file writes should append instead of truncate-on-open behavior. +- `auto_flush : Bool` - Whether writes should be flushed automatically. +- `rotation : FileRotation?` - Optional size-based file rotation policy. +- `text_formatter : TextFormatterConfig` - Formatter config used for file text rendering. + +#### output + +- `LoggerConfig` - Config using `SinkKind::File` and the supplied file-specific settings. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This preset always returns `sink.kind=SinkKind::File`. +- `path` must be non-empty. +- `rotation=None` leaves file rotation disabled until a rotation policy is provided directly or through `with_file_rotation(...)`. +- `queue=None` by default, so buffering is opt-in through `with_queue(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Config-driven File Logger + +When application boot wants typed file logging config: +```moonbit +let config = file( + "service.log", + min_level=Level::Warn, + append=true, + auto_flush=true, +) +``` + +In this example, the returned config targets the built-in file sink. + +And rotation remains disabled until configured. + +#### When Need File Config With Rotation Prepared Up Front + +When file retention should be included immediately: +```moonbit +let config = file( + "service.log", + rotation=Some(file_rotation(1024 * 1024, max_backups=3)), +) +``` + +In this example, the file preset carries both path and rotation policy. + +### Error Case + +e.g.: +- If `path` is empty, this preset raises `ConfigError::InvalidConfig("File sink requires non-empty path")`. + +- If you need console output instead of file output, use a console preset because file-only settings are meaningful only for `SinkKind::File`. + +### Notes + +1. This is the only preset in this set that accepts file path and file rotation settings directly. + +2. `with_file_rotation(...)` is designed to extend this preset or any other file-based `LoggerConfig`. diff --git a/docs/api/index.md b/docs/api/index.md index b4a1f83..f85e42e 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -111,6 +111,15 @@ BitLogger API navigation. - [build-logger.md](./build-logger.md) - [parse-and-build-logger.md](./parse-and-build-logger.md) +## Presets + +- [console.md](./console.md) +- [json-console.md](./json-console.md) +- [text-console.md](./text-console.md) +- [file.md](./file.md) +- [with-queue.md](./with-queue.md) +- [with-file-rotation.md](./with-file-rotation.md) + ## Async logger - [async-logger.md](./async-logger.md) diff --git a/docs/api/json-console.md b/docs/api/json-console.md new file mode 100644 index 0000000..e9b4eb1 --- /dev/null +++ b/docs/api/json-console.md @@ -0,0 +1,73 @@ +--- +name: json-console +group: api +category: config +update-time: 20260520 +description: Create a logger config preset for the built-in JSON console sink. +key-word: + - preset + - json + - console + - public +--- + +## Json-console + +Create a `LoggerConfig` preset for structured JSON output on the console. This preset is intended for config-driven logging pipelines that want machine-readable terminal output. + +### Interface + +```moonbit +pub fn json_console( + min_level~ : Level = Level::Info, + target~ : String = "", + timestamp~ : Bool = false, +) -> LoggerConfig { +``` + +#### input + +- `min_level : Level` - Minimum enabled level for the preset. +- `target : String` - Default target stored in the returned config. +- `timestamp : Bool` - Whether emitted records should include timestamps. + +#### output + +- `LoggerConfig` - Config using `SinkKind::JsonConsole` with no queue wrapper by default. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This preset always returns `sink.kind=SinkKind::JsonConsole`. +- `queue=None` by default, so JSON records are not buffered unless `with_queue(...)` is added later. +- The preset does not carry file-only fields such as `path` or `rotation` in a meaningful way because the sink kind is not file-based. + +### How to Use + +Here are some specific examples provided. + +#### When Need Structured Console Output + +When logs should be easy to collect or parse from stdout: +```moonbit +let config = json_console(min_level=Level::Info, target="api", timestamp=true) +let logger = build_logger(config) +``` + +In this example, records are emitted through the JSON console sink. + +And timestamps are enabled at the top-level logger config. + +### Error Case + +e.g.: +- If `target` is empty, the preset still returns a valid config. + +- If you need file rotation or file paths, this preset is the wrong sink shape and should be replaced with `file(...)`. + +### Notes + +1. Use this preset when downstream tooling expects structured console logs. + +2. `with_file_rotation(...)` does not change this preset because it only applies to file configs. diff --git a/docs/api/text-console.md b/docs/api/text-console.md new file mode 100644 index 0000000..374686d --- /dev/null +++ b/docs/api/text-console.md @@ -0,0 +1,75 @@ +--- +name: text-console +group: api +category: config +update-time: 20260520 +description: Create a logger config preset for the built-in text console sink with formatter settings. +key-word: + - preset + - text + - console + - public +--- + +## Text-console + +Create a `LoggerConfig` preset for text-formatted console output. This helper bundles `SinkKind::TextConsole` together with a `TextFormatterConfig` so config-driven logger assembly can control text rendering without manual `SinkConfig::new(...)` calls. + +### Interface + +```moonbit +pub fn text_console( + min_level~ : Level = Level::Info, + target~ : String = "", + timestamp~ : Bool = false, + text_formatter~ : TextFormatterConfig = default_text_formatter_config(), +) -> LoggerConfig { +``` + +#### input + +- `min_level : Level` - Minimum enabled level for the preset. +- `target : String` - Default target stored in the returned config. +- `timestamp : Bool` - Whether the built logger should emit timestamps. +- `text_formatter : TextFormatterConfig` - Formatter config used by the text console sink. + +#### output + +- `LoggerConfig` - Config using `SinkKind::TextConsole` with the supplied formatter and no queue wrapper by default. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This preset always returns `sink.kind=SinkKind::TextConsole`. +- `text_formatter` is copied into `config.sink.text_formatter`. +- `queue=None` by default, so buffering remains opt-in through `with_queue(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Customized Human-readable Console Output + +When console logs should use a specific separator or timestamp display: +```moonbit +let formatter = TextFormatterConfig::new(show_timestamp=false, separator=" | ") +let config = text_console(target="worker", text_formatter=formatter) +``` + +In this example, the text console sink uses the supplied formatter config. + +And the preset stays fully compatible with later `build_logger(...)` assembly. + +### Error Case + +e.g.: +- If `target` is empty, the preset still returns a valid config. + +- If you later apply `with_file_rotation(...)`, the config stays unchanged because this is not a file sink preset. + +### Notes + +1. Use this preset instead of `console(...)` when text formatting must be configured explicitly. + +2. File-only settings such as `path` and `rotation` are not part of this preset. diff --git a/docs/api/with-file-rotation.md b/docs/api/with-file-rotation.md new file mode 100644 index 0000000..ae446bf --- /dev/null +++ b/docs/api/with-file-rotation.md @@ -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. diff --git a/docs/api/with-queue.md b/docs/api/with-queue.md new file mode 100644 index 0000000..75e02f4 --- /dev/null +++ b/docs/api/with-queue.md @@ -0,0 +1,76 @@ +--- +name: with-queue +group: api +category: config +update-time: 20260520 +description: Add a queue wrapper to an existing logger config preset. +key-word: + - preset + - queue + - config + - public +--- + +## With-queue + +Add a synchronous queue wrapper to an existing `LoggerConfig`. This preset helper is the config-side counterpart to `Logger::with_queue(...)`, allowing queue behavior to be expressed before the runtime logger is built. + +### Interface + +```moonbit +pub fn with_queue( + config : LoggerConfig, + max_pending~ : Int = 0, + overflow~ : QueueOverflowPolicy = QueueOverflowPolicy::DropNewest, +) -> LoggerConfig { +``` + +#### input + +- `config : LoggerConfig` - Base logger config to wrap. +- `max_pending : Int` - Maximum number of pending records allowed in the queue. +- `overflow : QueueOverflowPolicy` - Overflow behavior such as `DropNewest` or `DropOldest`. + +#### output + +- `LoggerConfig` - A copy of the input config with `queue=Some(QueueConfig::new(...))`. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper preserves the original config's `min_level`, `target`, `timestamp`, and `sink` fields. +- Only the top-level `queue` field is added or replaced. +- The helper can be composed with any preset, including `console(...)`, `json_console(...)`, `text_console(...)`, and `file(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Config-side Queueing + +When queue behavior should be configured before calling `build_logger(...)`: +```moonbit +let config = with_queue( + text_console(target="svc"), + max_pending=32, + overflow=QueueOverflowPolicy::DropOldest, +) +``` + +In this example, the text console preset is wrapped with a bounded queue config. + +And sink-specific settings remain unchanged. + +### Error Case + +e.g.: +- If `max_pending` is too small, burst traffic may trigger overflow handling sooner. + +- If the wrapped runtime logger is never flushed or drained, queued records may remain pending depending on how the built sink is used. + +### Notes + +1. This helper is config composition only; it does not build or run the logger. + +2. Queue wrapping can be combined with `with_file_rotation(...)` when the base config is file-based.