diff --git a/docs/api/library-async-logger-error.md b/docs/api/library-async-logger-error.md index 89ea0bb..5987602 100644 --- a/docs/api/library-async-logger-error.md +++ b/docs/api/library-async-logger-error.md @@ -3,7 +3,7 @@ name: library-async-logger-error group: api category: facade update-time: 20260614 -description: Enqueue an error-level record through a LibraryAsyncLogger facade using the highest built-in severity shortcut and the repo's direct async call style. +description: Enqueue an error-level record through a LibraryAsyncLogger facade by delegating to the wrapped async logger's error shortcut. key-word: - async - library @@ -39,10 +39,11 @@ pub async fn[S] LibraryAsyncLogger::error( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Error, ...)` on the wrapped async logger. -- The record is still subject to patching, filtering, and overflow policy. +- This helper delegates to `error(...)` on the wrapped async logger, which in turn uses `log(Level::Error, ...)`. +- The record is still subject to stored shared context fields, patching, filtering, and overflow policy. - Error records represent the highest built-in severity in this async facade API. - Use this helper when a named error call is clearer than a raw `log(...)` call. +- Async state helpers remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first. ### How to Use @@ -69,6 +70,8 @@ logger.error( In this example, the error record carries structured context without falling back to the generic `log(...)` form. +And any shared context fields already stored on the facade are still prepended before these per-call fields. + ### Error Case e.g.: @@ -76,8 +79,12 @@ e.g.: - If callers need to inspect worker failure rather than emit an error record, `has_failed()` and `last_error()` are the relevant APIs on the full async logger. +- If callers need a per-call target override, they should use `log(...)` instead of this fixed-level shortcut. + ### Notes 1. Use this helper for high-severity async application failures. 2. Emitting an error record is separate from the logger worker itself entering failure state. + +3. Use `to_async_logger()` first when later code needs queue or failure inspection rather than another write shortcut. diff --git a/docs/api/library-async-logger-info.md b/docs/api/library-async-logger-info.md index ff047c0..b26d6c1 100644 --- a/docs/api/library-async-logger-info.md +++ b/docs/api/library-async-logger-info.md @@ -3,7 +3,7 @@ name: library-async-logger-info group: api category: facade update-time: 20260614 -description: Enqueue an info-level record through a LibraryAsyncLogger facade using the informational severity shortcut and the repo's direct async call style. +description: Enqueue an info-level record through a LibraryAsyncLogger facade by delegating to the wrapped async logger's info shortcut. key-word: - async - library @@ -39,10 +39,11 @@ pub async fn[S] LibraryAsyncLogger::info( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Info, ...)` on the wrapped async logger. -- The record is still subject to min-level gating, patching, filtering, and overflow policy. +- This helper delegates to `info(...)` on the wrapped async logger, which in turn uses `log(Level::Info, ...)`. +- The record is still subject to min-level gating, stored shared context fields, patching, filtering, and overflow policy. - `Info` is often the default operational logging level for async application events. - Use this helper when explicit info intent is clearer than a raw `log(...)` call. +- Async state helpers remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first. ### How to Use @@ -69,6 +70,8 @@ logger.info( In this example, the record remains concise while still carrying useful metadata. +And any shared context fields already stored on the facade are still prepended before these per-call fields. + ### Error Case e.g.: @@ -76,8 +79,12 @@ e.g.: - If the logger is closed or overflow policy prevents acceptance, the write may not become a normal queued record. +- If callers need a per-call target override, they should use `log(...)` instead of this fixed-level shortcut. + ### Notes 1. This is often the most common convenience method for normal async library events. 2. Use `log(...)` when the call site needs a dynamic level or target override. + +3. Use `to_async_logger()` first when later code needs queue or failure inspection rather than another write shortcut. diff --git a/docs/api/library-async-logger-log.md b/docs/api/library-async-logger-log.md index 20dfbc2..3ed71d8 100644 --- a/docs/api/library-async-logger-log.md +++ b/docs/api/library-async-logger-log.md @@ -3,7 +3,7 @@ name: library-async-logger-log group: api category: facade update-time: 20260614 -description: Enqueue a record through a LibraryAsyncLogger facade with explicit level, message, fields, and optional target override, using the repo's direct async call style. +description: Enqueue a record through a LibraryAsyncLogger facade with explicit level, message, fields, and optional target override by delegating to the wrapped async logger. key-word: - async - library @@ -45,8 +45,10 @@ Detailed rules explaining key parameters and behaviors - This method delegates directly to the wrapped async logger's `log(...)` behavior. - The logger checks `is_enabled(level)` before building a record. -- Context fields, patch logic, and filter logic are applied before enqueue. -- The narrower library facade does not change enqueue semantics; it only limits the visible API surface. +- Stored shared context fields are prepended ahead of per-call `fields`, then patch and filter logic are applied before enqueue. +- If `target` is empty, the logger uses its current default target; otherwise the provided per-call target overrides that default for this one write. +- The narrower library facade does not change enqueue semantics, overflow handling, or runtime-dependent closed-on-log behavior; it only limits the visible API surface. +- Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `has_failed()`, and `last_error()` remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first. ### How to Use @@ -75,6 +77,20 @@ logger.log(@bitlogger.Level::Warn, "slow request") 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 metadata but a single write needs additional detail: +```moonbit +let logger = base.with_context_fields([@bitlogger.field("service", "cache")]) +logger.log( + @bitlogger.Level::Info, + "entry refreshed", + fields=[@bitlogger.field("key", "user:42")], +) +``` + +In this example, the stored shared fields remain in front of the per-call fields when the record is built. + ### Error Case e.g.: @@ -82,8 +98,12 @@ e.g.: - If the logger is closed or overflow policy rejects the record, enqueue may not proceed as a normal accepted write. +- If callers need to inspect queue or failure state after writing, they must unwrap first with `to_async_logger()`. + ### Notes 1. Use this API when the call site needs full control instead of a fixed severity helper. 2. Prefer `info()`, `warn()`, `error()`, and the other shortcuts when only the level differs. + +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-async-logger-warn.md b/docs/api/library-async-logger-warn.md index a17a523..04d18bc 100644 --- a/docs/api/library-async-logger-warn.md +++ b/docs/api/library-async-logger-warn.md @@ -3,7 +3,7 @@ name: library-async-logger-warn group: api category: facade update-time: 20260614 -description: Enqueue a warning-level record through a LibraryAsyncLogger facade using the built-in severity shortcut and the repo's direct async call style. +description: Enqueue a warning-level record through a LibraryAsyncLogger facade by delegating to the wrapped async logger's warn shortcut. key-word: - async - library @@ -39,10 +39,11 @@ pub async fn[S] LibraryAsyncLogger::warn( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Warn, ...)` on the wrapped async logger. -- The record is still subject to min-level gating, patching, filtering, and overflow policy. +- This helper delegates to `warn(...)` on the wrapped async logger, which in turn uses `log(Level::Warn, ...)`. +- The record is still subject to min-level gating, stored shared context fields, patching, filtering, and overflow policy. - Warning records are useful for degraded but non-fatal runtime conditions. - Use this helper when a named warning call is clearer than a raw `log(...)` call. +- Async state helpers remain on the underlying `AsyncLogger[S]` and require `to_async_logger()` first. ### How to Use @@ -69,6 +70,8 @@ logger.warn( In this example, the warning carries structured operational detail. +And any shared context fields already stored on the facade are still prepended before these per-call fields. + ### Error Case e.g.: @@ -76,8 +79,12 @@ e.g.: - If the logger is closed or overflow policy prevents acceptance, the write may not become a normal queued record. +- If callers need a per-call target override, they should use `log(...)` instead of this fixed-level shortcut. + ### Notes 1. Use this helper for notable but non-fatal async runtime conditions. 2. Pair warnings with structured fields when operators need quick context. + +3. Use `to_async_logger()` first when later code needs queue or failure inspection rather than another write shortcut.