From 888be5b6fcc8637ed7725b09526912c6019f5c63 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:18:33 +0800 Subject: [PATCH] :memo: refine library logger write docs --- docs/api/library-logger-error.md | 11 +++++++++-- docs/api/library-logger-info.md | 12 ++++++++++-- docs/api/library-logger-is-enabled.md | 13 ++++++++++--- docs/api/library-logger-log.md | 22 +++++++++++++++++++++- docs/api/library-logger-warn.md | 13 ++++++++++--- 5 files changed, 60 insertions(+), 11 deletions(-) diff --git a/docs/api/library-logger-error.md b/docs/api/library-logger-error.md index 5a05c12..1de7231 100644 --- a/docs/api/library-logger-error.md +++ b/docs/api/library-logger-error.md @@ -3,7 +3,7 @@ name: library-logger-error group: api category: facade update-time: 20260613 -description: Emit an error-level record through a LibraryLogger facade using the highest built-in severity shortcut. +description: Emit an error-level record through a LibraryLogger facade by delegating to the wrapped logger's error shortcut. key-word: - library - facade @@ -39,10 +39,11 @@ pub fn[S : Sink] LibraryLogger::error( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Error, ...)` on the wrapped logger. +- This helper delegates to `error(...)` on the wrapped logger, which in turn uses `log(Level::Error, ...)`. - `Error` is the highest built-in severity in this sync facade API. - Per-call target override is not exposed here; use `log(...)` when explicit target control is required. - Sink composition, filtering, patching, and queue wrappers still apply normally. +- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first. ### How to Use @@ -66,6 +67,8 @@ logger.error("dispatch failed", fields=[field("job_id", "42")]) In this example, the record carries machine-readable context without dropping to the generic `log(...)` form. +And any shared context already carried by the facade still participates through the wrapped logger pipeline. + ### Error Case e.g.: @@ -73,8 +76,12 @@ e.g.: - If a target override is required, use `log(...)` instead of this severity shortcut. +- If callers need broader composition helpers after logging, they must unwrap first with `to_logger()`. + ### Notes 1. Use this helper for high-severity library failures. 2. Emitting an error record is separate from throwing or handling program exceptions. + +3. Use `log(...)` instead when the call site needs a per-call target override or a dynamic level. diff --git a/docs/api/library-logger-info.md b/docs/api/library-logger-info.md index 692f203..ae824f9 100644 --- a/docs/api/library-logger-info.md +++ b/docs/api/library-logger-info.md @@ -3,7 +3,7 @@ name: library-logger-info group: api category: facade update-time: 20260613 -description: Emit an info-level record through a LibraryLogger facade using the informational severity shortcut. +description: Emit an info-level record through a LibraryLogger facade by delegating to the wrapped logger's info shortcut. key-word: - library - facade @@ -39,10 +39,12 @@ pub fn[S : Sink] LibraryLogger::info( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Info, ...)` on the wrapped logger. +- This helper delegates to `info(...)` on the wrapped logger, which in turn uses `log(Level::Info, ...)`. - `Info` is the default minimum logger threshold unless changed explicitly. - Per-call target override is not exposed here; use `log(...)` if needed. +- Any existing sink wrappers inside the logger pipeline still participate normally in the write path. - The library facade keeps the same write semantics while exposing a smaller public surface. +- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first. ### How to Use @@ -66,6 +68,8 @@ logger.info("request completed", fields=[field("status", "200")]) In this example, the event remains concise while still carrying useful fields. +And any shared context already carried by the facade still participates through the wrapped logger pipeline. + ### Error Case e.g.: @@ -73,8 +77,12 @@ e.g.: - If the event needs an explicit alternate target, use `log(...)` instead of this shortcut. +- If callers need broader composition helpers after logging, they must unwrap first with `to_logger()`. + ### Notes 1. This is the common convenience method for normal library-facing events. 2. Because `Info` is often the default threshold, this helper is a natural baseline for facade examples. + +3. Use `log(...)` instead when the call site needs a per-call target override or a dynamic level. diff --git a/docs/api/library-logger-is-enabled.md b/docs/api/library-logger-is-enabled.md index 0f6a540..fe858b4 100644 --- a/docs/api/library-logger-is-enabled.md +++ b/docs/api/library-logger-is-enabled.md @@ -3,7 +3,7 @@ name: library-logger-is-enabled group: api category: facade update-time: 20260613 -description: Check whether a LibraryLogger facade would accept a record at a given level. +description: Check whether a LibraryLogger facade passes the wrapped logger's min-level gate for a given severity. key-word: - library - facade @@ -35,8 +35,9 @@ pub fn[S] LibraryLogger::is_enabled(self : LibraryLogger[S], level : Level) -> B Detailed rules explaining key parameters and behaviors - This method delegates directly to the wrapped logger's `is_enabled(...)` behavior. -- It only checks logger-level severity gating; it does not evaluate sink filters or patch logic. -- The result reflects the current facade value, so derived facades with different thresholds can return different answers. +- It only checks logger-level severity gating through `min_level`; it does not evaluate later sink filters, patch logic, or any sink-side buffering/wrapping behavior. +- The result reflects the current wrapped logger state, so derived facades with different thresholds can return different answers. +- This check does not require unwrapping because it is part of the narrower library-facing surface. - Use it when message construction or field gathering is expensive enough to justify a pre-check. ### How to Use @@ -65,6 +66,8 @@ if logger.is_enabled(Level::Info) { In this example, the check mirrors the same severity gate used by later write calls. +And a `true` result still means only that the level gate passed, not that the record is guaranteed to survive later sink-side filtering or routing. + ### Error Case e.g.: @@ -72,8 +75,12 @@ e.g.: - A `true` result does not guarantee final sink output if later filter logic rejects the record. +- If callers need broader composition helpers rather than just the level gate, they must unwrap first with `to_logger()`. + ### Notes 1. This is a cheap severity check, not a full end-to-end delivery guarantee. 2. Prefer using it only when precomputing the log payload is meaningfully expensive. + +3. Use `log(...)` or the severity shortcuts directly when no expensive precomputation needs to be avoided. diff --git a/docs/api/library-logger-log.md b/docs/api/library-logger-log.md index f69bae4..10aadcf 100644 --- a/docs/api/library-logger-log.md +++ b/docs/api/library-logger-log.md @@ -3,7 +3,7 @@ name: library-logger-log group: api category: facade update-time: 20260613 -description: Emit a record through a LibraryLogger facade with explicit level, message, fields, and optional target override. +description: Emit a record through a LibraryLogger facade with explicit level, message, fields, and optional target override by delegating to the wrapped logger. key-word: - library - facade @@ -46,7 +46,9 @@ Detailed rules explaining key parameters and behaviors - This method delegates directly to the wrapped logger's `log(...)` behavior. - The logger checks `is_enabled(level)` before building and writing the record. - If `target` is empty, the facade's stored default target is used. +- Any existing sink wrappers already inside the wrapped logger, such as `ContextSink`, `FilterSink`, `PatchSink`, or queued/runtime sink variants, still participate normally in the write path. - The narrower library facade does not change record construction semantics; it only limits the visible API surface. +- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first. ### How to Use @@ -77,6 +79,20 @@ fn log_retry(logger : LibraryLogger[ConsoleSink], attempt : Int) -> Unit { In this example, `log(...)` acts as the shared primitive under custom library-facing wrappers. +#### When Need Shared Context Plus Event-specific Fields + +When a facade already carries shared context but one write needs extra detail: +```moonbit +let logger = base.with_context_fields([field("service", "cache")]) +logger.log( + Level::Info, + "entry refreshed", + fields=[field("key", "user:42")], +) +``` + +In this example, both the stored shared context and the per-call fields still flow through the wrapped logger pipeline. + ### Error Case e.g.: @@ -84,8 +100,12 @@ e.g.: - If `target` is empty and the logger default target is also empty, the emitted record simply has no target label. +- If callers need broader composition helpers after writing, they must unwrap first with `to_logger()`. + ### Notes 1. Use this API when the call site needs full control instead of a fixed-severity helper. 2. The facade remains synchronous; any buffering behavior only comes from the wrapped sink type. + +3. Use the optional `target` argument when one write should temporarily override the facade's default target without rebuilding or rewrapping it. diff --git a/docs/api/library-logger-warn.md b/docs/api/library-logger-warn.md index 3739e96..ded6559 100644 --- a/docs/api/library-logger-warn.md +++ b/docs/api/library-logger-warn.md @@ -3,7 +3,7 @@ name: library-logger-warn group: api category: facade update-time: 20260613 -description: Emit a warn-level record through a LibraryLogger facade using the warning severity shortcut. +description: Emit a warn-level record through a LibraryLogger facade by delegating to the wrapped logger's warn shortcut. key-word: - library - facade @@ -39,10 +39,11 @@ pub fn[S : Sink] LibraryLogger::warn( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Warn, ...)` on the wrapped logger. +- This helper delegates to `warn(...)` on the wrapped logger, which in turn uses `log(Level::Warn, ...)`. - Warning records are useful for abnormal but non-fatal conditions. - Per-call target override is not exposed here; use `log(...)` when that is required. -- All logger wrappers still participate normally in the write path. +- All sink-side wrappers still participate normally in the write path. +- Broader composition helpers remain on the underlying `Logger[S]` and require `to_logger()` first. ### How to Use @@ -66,6 +67,8 @@ logger.warn("retry scheduled", fields=[field("attempt", "3")]) In this example, the warning remains easy to filter and inspect later. +And any shared context already carried by the facade still participates through the wrapped logger pipeline. + ### Error Case e.g.: @@ -73,8 +76,12 @@ e.g.: - If a target override is needed at this call site, use `log(...)` instead of this shortcut. +- If callers need broader composition helpers after logging, they must unwrap first with `to_logger()`. + ### Notes 1. Use this helper for degraded or suspicious states that do not stop execution. 2. Warning logs are often a practical signal threshold for alerting or separate routing. + +3. Use `log(...)` instead when the call site needs a per-call target override or a dynamic level.