From bd1ef991896d02dbb7b23c08a709b145afc89864 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 12 May 2026 16:10:24 +0800 Subject: [PATCH] :memo: Add global logger API docs --- docs/api/default-logger.md | 75 ++++++++++++++++++++++++++++++ docs/api/global-debug.md | 77 +++++++++++++++++++++++++++++++ docs/api/global-error.md | 76 ++++++++++++++++++++++++++++++ docs/api/global-info.md | 77 +++++++++++++++++++++++++++++++ docs/api/global-log.md | 77 +++++++++++++++++++++++++++++++ docs/api/global-trace.md | 77 +++++++++++++++++++++++++++++++ docs/api/global-warn.md | 76 ++++++++++++++++++++++++++++++ docs/api/index.md | 12 +++++ docs/api/set-default-min-level.md | 76 ++++++++++++++++++++++++++++++ docs/api/set-default-target.md | 77 +++++++++++++++++++++++++++++++ 10 files changed, 700 insertions(+) create mode 100644 docs/api/default-logger.md create mode 100644 docs/api/global-debug.md create mode 100644 docs/api/global-error.md create mode 100644 docs/api/global-info.md create mode 100644 docs/api/global-log.md create mode 100644 docs/api/global-trace.md create mode 100644 docs/api/global-warn.md create mode 100644 docs/api/set-default-min-level.md create mode 100644 docs/api/set-default-target.md diff --git a/docs/api/default-logger.md b/docs/api/default-logger.md new file mode 100644 index 0000000..4e27b33 --- /dev/null +++ b/docs/api/default-logger.md @@ -0,0 +1,75 @@ +--- +name: default-logger +group: api +category: global +update-time: 20260512 +description: Create the shared console-backed logger value used by the global logging helpers. +key-word: + - global + - logger + - default + - public +--- + +## Default-logger + +Create a `Logger[ConsoleSink]` from the current shared default global configuration. This is the logger value used internally by the global helper functions such as `log(...)`, `info(...)`, and `error(...)`. + +### Interface + +```moonbit +pub fn default_logger() -> Logger[ConsoleSink] {} +``` + +#### output + +- `Logger[ConsoleSink]` - Logger built from the shared console sink, current default minimum level, and current default target. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The returned logger is built from `default_console_sink`, `default_min_level_ref`, and `default_target_ref`. +- Each call reflects the current shared configuration at that moment. +- The logger writes to the standard console sink path. +- This helper is useful when you want the same baseline behavior as the global shortcuts but still need the explicit `Logger` object for chaining or inspection. + +### How to Use + +Here are some specific examples provided. + +#### When Start From Global Defaults But Keep A Logger Value + +When code wants the default console path with later composition: +```moonbit +let logger = default_logger().with_timestamp() +logger.info("service started") +``` + +In this example, the logger starts from global defaults and then gains extra instance-level behavior. + +#### When Inspect Current Shared Behavior + +When code should branch using the same threshold as global helpers: +```moonbit +let logger = default_logger() +if logger.is_enabled(Level::Debug) { + logger.debug("debug path active") +} +``` + +In this example, the explicit logger mirrors the same level gate used by global shortcut calls. + +### Error Case + +e.g.: +- If the shared default target is empty, the returned logger is still valid and simply uses an empty target. + +- Changes made later through `set_default_min_level(...)` or `set_default_target(...)` do not mutate an already-stored logger value. + +### Notes + +1. This helper returns a normal `Logger`, so further chaining is available. + +2. It is the bridge between the simple global API and the explicit typed logger workflow. + diff --git a/docs/api/global-debug.md b/docs/api/global-debug.md new file mode 100644 index 0000000..aa64c50 --- /dev/null +++ b/docs/api/global-debug.md @@ -0,0 +1,77 @@ +--- +name: global-debug +group: api +category: global +update-time: 20260512 +description: Emit a debug-level record through the shared default logger shortcut. +key-word: + - global + - debug + - default + - public +--- + +## Global-debug + +Emit a debug-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Debug, ...)`. + +### Interface + +```moonbit +pub fn debug(message : String, fields~ : Array[Field] = []) -> Unit {} +``` + +#### input + +- `message : String` - Debug message text. +- `fields : Array[Field]` - Optional structured fields attached to the record. + +#### output + +- `Unit` - No return value. The record is handled through the shared default logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper delegates to `default_logger().debug(...)`. +- The record uses the current shared minimum level and target configuration. +- Debug output is typically intended for development and troubleshooting. +- This helper is best suited to small apps or code paths that intentionally rely on the shared logger. + +### How to Use + +Here are some specific examples provided. + +#### When Need Simple Global Debug Logging + +When code wants quick diagnostics without wiring a logger variable: +```moonbit +set_default_min_level(Level::Debug) +debug("cache refreshed") +``` + +In this example, the shared global path starts accepting debug records. + +#### When Attach Structured Debug Context + +When a debug event should include machine-readable detail: +```moonbit +debug("session loaded", fields=[field("user_id", "42")]) +``` + +In this example, the global shortcut still supports structured fields. + +### Error Case + +e.g.: +- If the shared minimum level is above `Debug`, the record is skipped. + +- If different modules need distinct targets or sinks, a shared global debug path may be too coarse. + +### Notes + +1. Prefer explicit loggers once application logging becomes subsystem-specific. + +2. Use `set_default_min_level(...)` before expecting global debug output to appear. + diff --git a/docs/api/global-error.md b/docs/api/global-error.md new file mode 100644 index 0000000..e0055e7 --- /dev/null +++ b/docs/api/global-error.md @@ -0,0 +1,76 @@ +--- +name: global-error +group: api +category: global +update-time: 20260512 +description: Emit an error-level record through the shared default logger shortcut. +key-word: + - global + - error + - default + - public +--- + +## Global-error + +Emit an error-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Error, ...)`. + +### Interface + +```moonbit +pub fn error(message : String, fields~ : Array[Field] = []) -> Unit {} +``` + +#### input + +- `message : String` - Error message text. +- `fields : Array[Field]` - Optional structured fields attached to the record. + +#### output + +- `Unit` - No return value. The record is handled through the shared default logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper delegates to `default_logger().error(...)`. +- It uses the shared console sink, default target, and current threshold configuration. +- `Error` is the highest built-in severity in the global sync helper set. +- This helper is useful when a small app wants a direct shared failure-reporting path. + +### How to Use + +Here are some specific examples provided. + +#### When Report A Global Failure Event + +When a small application should emit an explicit failure log: +```moonbit +error("worker execution failed") +``` + +In this example, the shared default logger emits a high-severity error record. + +#### When Attach Structured Error Context + +When an error event should include machine-readable detail: +```moonbit +error("dispatch failed", fields=[field("job_id", "42")]) +``` + +In this example, the global helper still supports structured fields. + +### Error Case + +e.g.: +- If the shared minimum level is above `Error`, the call still returns without writing, though this configuration is unusual. + +- If one module should not share the same sink or target policy, the global helper path may be too blunt. + +### Notes + +1. Use this helper for simple shared error reporting. + +2. Explicit `Logger` values are usually better once the application needs richer routing or ownership boundaries. + diff --git a/docs/api/global-info.md b/docs/api/global-info.md new file mode 100644 index 0000000..ee331ae --- /dev/null +++ b/docs/api/global-info.md @@ -0,0 +1,77 @@ +--- +name: global-info +group: api +category: global +update-time: 20260512 +description: Emit an info-level record through the shared default logger shortcut. +key-word: + - global + - info + - default + - public +--- + +## Global-info + +Emit an info-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Info, ...)`. + +### Interface + +```moonbit +pub fn info(message : String, fields~ : Array[Field] = []) -> Unit {} +``` + +#### input + +- `message : String` - Informational message text. +- `fields : Array[Field]` - Optional structured fields attached to the record. + +#### output + +- `Unit` - No return value. The record is handled through the shared default logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper delegates to `default_logger().info(...)`. +- It uses the shared console sink and current default target. +- `Info` is the default global threshold unless changed through `set_default_min_level(...)`. +- This is the simplest entry point for normal app-level informational events. + +### How to Use + +Here are some specific examples provided. + +#### When Emit Simple Global Application Events + +When a small app wants direct lifecycle logging: +```moonbit +set_default_target("app") +info("service started") +``` + +In this example, the shared default logger emits an informational record under the `app` target. + +#### When Attach Structured Informational Data + +When a global info event should include metadata: +```moonbit +info("request completed", fields=[field("status", "200")]) +``` + +In this example, the global helper still supports structured fields. + +### Error Case + +e.g.: +- If the shared minimum level is above `Info`, the record is skipped. + +- If different components need different targets, shared global info logging may become too broad. + +### Notes + +1. This is the most common global write helper for small applications or scripts. + +2. Prefer explicit loggers when the codebase grows beyond one shared logging path. + diff --git a/docs/api/global-log.md b/docs/api/global-log.md new file mode 100644 index 0000000..043dfab --- /dev/null +++ b/docs/api/global-log.md @@ -0,0 +1,77 @@ +--- +name: global-log +group: api +category: global +update-time: 20260512 +description: Emit a record through the shared default logger with an explicit level and optional fields. +key-word: + - global + - log + - default + - public +--- + +## Global-log + +Emit a record through the shared default logger with an explicit level and message. This is the core global write API behind the global severity-specific shortcuts. + +### Interface + +```moonbit +pub fn log(level : Level, message : String, fields~ : Array[Field] = []) -> Unit {} +``` + +#### input + +- `level : Level` - Severity level for the record. +- `message : String` - Log message text. +- `fields : Array[Field]` - Optional structured fields attached to the record. + +#### output + +- `Unit` - No return value. The record is emitted through the current shared default logger behavior. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The function calls `default_logger().log(level, message, fields=fields)`. +- It uses the shared console sink and the current global default threshold and target. +- Per-call target override is not exposed by this global shortcut. +- This helper is most useful when convenience matters more than explicit logger ownership. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Simple Global Logging Entry + +When application code wants a direct severity-controlled write: +```moonbit +log(Level::Info, "service started") +``` + +In this example, the shared default logger handles the record without requiring an explicit logger variable. + +#### When Attach Structured Metadata Globally + +When a global event should still include fields: +```moonbit +log(Level::Warn, "retry scheduled", fields=[field("attempt", "2")]) +``` + +In this example, the global path still supports structured logging data. + +### Error Case + +e.g.: +- If the level is below the current shared minimum threshold, the write is skipped. + +- If a custom target override is required, the explicit `Logger::log(...)` API is a better fit. + +### Notes + +1. This API is convenient but intentionally less configurable than an explicit logger value. + +2. Prefer explicit loggers when different subsystems need different sink or target behavior. + diff --git a/docs/api/global-trace.md b/docs/api/global-trace.md new file mode 100644 index 0000000..bda8bc5 --- /dev/null +++ b/docs/api/global-trace.md @@ -0,0 +1,77 @@ +--- +name: global-trace +group: api +category: global +update-time: 20260512 +description: Emit a trace-level record through the shared default logger shortcut. +key-word: + - global + - trace + - default + - public +--- + +## Global-trace + +Emit a trace-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Trace, ...)`. + +### Interface + +```moonbit +pub fn trace(message : String, fields~ : Array[Field] = []) -> Unit {} +``` + +#### input + +- `message : String` - Trace message text. +- `fields : Array[Field]` - Optional structured fields attached to the record. + +#### output + +- `Unit` - No return value. The record is handled through the shared default logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper delegates to `default_logger().trace(...)`. +- Trace is the lowest built-in severity and is commonly disabled unless the shared minimum level is lowered. +- The shared default target and console sink are used. +- This helper favors convenience over explicit per-component logger ownership. + +### How to Use + +Here are some specific examples provided. + +#### When Need Quick Global Trace Output + +When a script or small app wants temporary low-level diagnostics: +```moonbit +set_default_min_level(Level::Trace) +trace("entered sync loop") +``` + +In this example, the shared global path begins accepting trace records. + +#### When Attach Structured Trace Context + +When a global trace event should carry fields: +```moonbit +trace("cache probe", fields=[field("key", "user:42")]) +``` + +In this example, the global helper still supports structured metadata. + +### Error Case + +e.g.: +- If the shared minimum level is above `Trace`, the record is skipped. + +- If you need per-call target control, use an explicit `Logger` instead of this helper. + +### Notes + +1. Global trace logging is convenient for scripts but easy to overuse in larger systems. + +2. This helper always goes through the shared default logger path. + diff --git a/docs/api/global-warn.md b/docs/api/global-warn.md new file mode 100644 index 0000000..bb9d660 --- /dev/null +++ b/docs/api/global-warn.md @@ -0,0 +1,76 @@ +--- +name: global-warn +group: api +category: global +update-time: 20260512 +description: Emit a warn-level record through the shared default logger shortcut. +key-word: + - global + - warn + - default + - public +--- + +## Global-warn + +Emit a warn-level record through the shared default logger. This is the global convenience wrapper for `log(Level::Warn, ...)`. + +### Interface + +```moonbit +pub fn warn(message : String, fields~ : Array[Field] = []) -> Unit {} +``` + +#### input + +- `message : String` - Warning message text. +- `fields : Array[Field]` - Optional structured fields attached to the record. + +#### output + +- `Unit` - No return value. The record is handled through the shared default logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper delegates to `default_logger().warn(...)`. +- The shared current threshold and target determine whether and how the record is emitted. +- Warning logs are suited to degraded or suspicious states that do not necessarily stop execution. +- This helper offers convenience for a single shared logging path. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Quick Global Warning + +When a recoverable issue should be surfaced without creating a logger variable: +```moonbit +warn("cache miss ratio increased") +``` + +In this example, the shared default logger emits a warning-severity record. + +#### When Attach Structured Warning Context + +When the warning should include machine-readable detail: +```moonbit +warn("retry scheduled", fields=[field("attempt", "3")]) +``` + +In this example, the global helper still supports structured metadata. + +### Error Case + +e.g.: +- If the shared minimum level is above `Warn`, the record is skipped. + +- If subsystem-specific routing is needed, a shared global warning path may be too limited. + +### Notes + +1. Global warnings are convenient for simple apps and scripts. + +2. Warning-level global events are often the first candidate for separate monitoring or routing later. + diff --git a/docs/api/index.md b/docs/api/index.md index 457b1fe..75e66d2 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -38,6 +38,18 @@ BitLogger API navigation. - [logger-warn.md](./logger-warn.md) - [logger-error.md](./logger-error.md) +## Global logger helpers + +- [set-default-min-level.md](./set-default-min-level.md) +- [set-default-target.md](./set-default-target.md) +- [default-logger.md](./default-logger.md) +- [global-log.md](./global-log.md) +- [global-trace.md](./global-trace.md) +- [global-debug.md](./global-debug.md) +- [global-info.md](./global-info.md) +- [global-warn.md](./global-warn.md) +- [global-error.md](./global-error.md) + ## Formatter and fields - [text-formatter.md](./text-formatter.md) diff --git a/docs/api/set-default-min-level.md b/docs/api/set-default-min-level.md new file mode 100644 index 0000000..f7e5639 --- /dev/null +++ b/docs/api/set-default-min-level.md @@ -0,0 +1,76 @@ +--- +name: set-default-min-level +group: api +category: global +update-time: 20260512 +description: Update the minimum level used by the shared default logger helpers. +key-word: + - global + - level + - default + - public +--- + +## Set-default-min-level + +Update the minimum level used by the shared default logger returned by `default_logger()` and consumed by the global `log(...)`, `info(...)`, `warn(...)`, and similar helpers. + +### Interface + +```moonbit +pub fn set_default_min_level(level : Level) -> Unit {} +``` + +#### input + +- `level : Level` - New minimum level for the shared default logger configuration. + +#### output + +- `Unit` - No return value. The stored default threshold is updated for later global calls. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The function updates the internal `Ref[Level]` used by `default_logger()`. +- It does not mutate any separately stored `Logger` values that were created earlier. +- Later calls to `default_logger()` and the global logging shortcuts observe the new threshold. +- This is the main API for adjusting process-wide default severity without building a custom logger variable. + +### How to Use + +Here are some specific examples provided. + +#### When Raise Global Threshold In Production + +When verbose logs should be suppressed process-wide: +```moonbit +set_default_min_level(Level::Warn) +``` + +In this example, later global `info(...)` calls are skipped while `warn(...)` and `error(...)` remain active. + +#### When Enable Temporary Debug Visibility + +When diagnostics should be turned on for a session: +```moonbit +set_default_min_level(Level::Debug) +debug("cache probe enabled") +``` + +In this example, the shared global path starts accepting debug records. + +### Error Case + +e.g.: +- If the level is set too high, lower-severity global writes are intentionally skipped. + +- Existing custom `Logger` instances keep their own thresholds and are not retroactively changed. + +### Notes + +1. This API only affects the shared default logger workflow. + +2. Prefer explicit logger instances when different subsystems need different thresholds at the same time. + diff --git a/docs/api/set-default-target.md b/docs/api/set-default-target.md new file mode 100644 index 0000000..0f7aaea --- /dev/null +++ b/docs/api/set-default-target.md @@ -0,0 +1,77 @@ +--- +name: set-default-target +group: api +category: global +update-time: 20260512 +description: Update the default target used by the shared global logger helpers. +key-word: + - global + - target + - default + - public +--- + +## Set-default-target + +Update the default target used by the shared default logger returned by `default_logger()` and by the global write helpers such as `info(...)` and `error(...)`. + +### Interface + +```moonbit +pub fn set_default_target(target : String) -> Unit {} +``` + +#### input + +- `target : String` - New default target string for the shared global logger configuration. + +#### output + +- `Unit` - No return value. The stored default target is updated for later global calls. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- The function updates the internal `Ref[String]` used by `default_logger()`. +- It does not mutate any custom `Logger` values created earlier. +- Later global writes inherit the new target unless a different explicit logger path is used. +- This is useful when one application wants the convenience of global helpers while still labeling records consistently. + +### How to Use + +Here are some specific examples provided. + +#### When Label Global Application Logs + +When global helper calls should carry one stable target: +```moonbit +set_default_target("app") +info("service started") +``` + +In this example, the emitted global record uses `app` as its target. + +#### When Re-scope A Temporary Execution Context + +When a script or tool should tag its own global output: +```moonbit +set_default_target("tool.migration") +warn("running fallback path") +``` + +In this example, later global writes stay grouped under the migration target. + +### Error Case + +e.g.: +- If `target` is empty, global writes remain valid and simply omit the target unless another logger path supplies one. + +- Previously created custom loggers are unaffected because they do not read the shared default target reference afterward. + +### Notes + +1. This API is best suited for small apps, scripts, or a single shared logging entry path. + +2. Prefer explicit child or per-component loggers when target structure needs to vary across subsystems. +