From 4b68ae27f1ea6c354c9b75d784fe57b4e97c7a5b Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 07:34:31 +0800 Subject: [PATCH] :memo: clarify async target override docs --- docs/api/async-logger-debug.md | 5 +++-- docs/api/async-logger-error.md | 7 +++++-- docs/api/async-logger-info.md | 5 +++-- docs/api/async-logger-log.md | 18 ++++++++++++++---- docs/api/async-logger-trace.md | 7 +++++-- docs/api/async-logger-warn.md | 5 +++-- 6 files changed, 33 insertions(+), 14 deletions(-) diff --git a/docs/api/async-logger-debug.md b/docs/api/async-logger-debug.md index c8f07d6..deef8dc 100644 --- a/docs/api/async-logger-debug.md +++ b/docs/api/async-logger-debug.md @@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::debug( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Debug, ...)`. +- This helper delegates to `log(Level::Debug, ..., fields=fields)`. - The record is still subject to min-level gating, patching, filtering, and overflow policy. +- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`. - Debug records are useful for development and targeted diagnostics. - Use this helper when a named debug call is clearer than a raw `log(...)` call. @@ -80,4 +81,4 @@ e.g.: 1. Prefer this helper when the event is semantically debug-level. -2. Use `log(...)` when the level must be chosen dynamically. +2. Use `log(...)` when the level must be chosen dynamically or one call needs a target override. diff --git a/docs/api/async-logger-error.md b/docs/api/async-logger-error.md index a649313..bfcc03a 100644 --- a/docs/api/async-logger-error.md +++ b/docs/api/async-logger-error.md @@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::error( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Error, ...)`. +- This helper delegates to `log(Level::Error, ..., fields=fields)`. - The record is still subject to patching, filtering, and overflow policy. +- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`. - Error records represent the highest built-in severity in this logger API. - Use this helper when a named error call is clearer than a raw `log(...)` call. @@ -80,4 +81,6 @@ e.g.: 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. +2. Use `log(...)` instead when an error call needs a one-off target override. + +3. Emitting an error record is separate from the logger worker itself entering failure state. diff --git a/docs/api/async-logger-info.md b/docs/api/async-logger-info.md index ea66033..d80e432 100644 --- a/docs/api/async-logger-info.md +++ b/docs/api/async-logger-info.md @@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::info( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Info, ...)`. +- This helper delegates to `log(Level::Info, ..., fields=fields)`. - The record is still subject to min-level gating, patching, filtering, and overflow policy. +- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`. - 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. @@ -80,4 +81,4 @@ e.g.: 1. This is often the most common convenience method for normal async application events. -2. Use `log(...)` when the call site needs a dynamic level or target override. +2. Use `log(...)` when the call site needs a dynamic level or a one-off target override. diff --git a/docs/api/async-logger-log.md b/docs/api/async-logger-log.md index d5df8f4..622f697 100644 --- a/docs/api/async-logger-log.md +++ b/docs/api/async-logger-log.md @@ -3,7 +3,7 @@ name: async-logger-log group: api category: async update-time: 20260614 -description: Enqueue a record into the async logger with an explicit level, message, optional fields, and optional target override, using the repo's direct async call style. +description: Enqueue a record into the async logger with an explicit level, message, optional fields, and optional target override. key-word: - async - logger @@ -13,7 +13,7 @@ key-word: ## Async-logger-log -Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods. +Enqueue a record into the async logger with an explicit level and message. This is the core write API behind all async level-specific convenience methods and the only built-in async write API that accepts a per-call target override. ### Interface @@ -44,6 +44,7 @@ pub async fn[S] AsyncLogger::log( Detailed rules explaining key parameters and behaviors - The logger checks `is_enabled(level)` before building a record. +- If `target` is empty, the logger uses its stored default target. If `target` is non-empty, that value overrides the stored target for this call only. - Context fields, patch logic, and filter logic are applied before enqueue. - If timestamping is enabled, `@env.now()` is captured before the record enters the queue. - Overflow behavior depends on the configured `AsyncOverflowPolicy`. @@ -65,7 +66,16 @@ logger.log( ) ``` -In this example, all per-record inputs are supplied explicitly. +In this example, the record overrides the logger's stored target only for this call. + +#### When Reuse The Stored Async Target + +When a call should keep the logger's existing target: +```moonbit +logger.log(@bitlogger.Level::Warn, "slow request") +``` + +In this example, the logger falls back to its stored target because no `target=` override is provided. #### When Build Higher-level Async Logging Helpers @@ -89,4 +99,4 @@ e.g.: 1. Use this API when the call site needs full control instead of a fixed severity helper. -2. Prefer `info()`, `warn()`, and the other shortcuts when only the level differs. +2. Prefer `info()`, `warn()`, and the other shortcuts when only the level differs and no per-call target override is needed. diff --git a/docs/api/async-logger-trace.md b/docs/api/async-logger-trace.md index a370067..7e0403b 100644 --- a/docs/api/async-logger-trace.md +++ b/docs/api/async-logger-trace.md @@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::trace( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Trace, ...)`. +- This helper delegates to `log(Level::Trace, ..., fields=fields)`. - The record is still subject to min-level gating, patching, filtering, and overflow policy. +- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`. - Trace records are often skipped in production because they are the lowest built-in severity. - Use this helper when explicit trace intent is clearer than a raw `log(...)` call. @@ -80,4 +81,6 @@ e.g.: 1. Prefer this helper when trace intent is more readable than `log(Level::Trace, ...)`. -2. Trace-level async logging can increase queue pressure quickly under verbose workloads. +2. Use `log(...)` instead when one trace call needs a one-off target override. + +3. Trace-level async logging can increase queue pressure quickly under verbose workloads. diff --git a/docs/api/async-logger-warn.md b/docs/api/async-logger-warn.md index adc8f4d..5c9da43 100644 --- a/docs/api/async-logger-warn.md +++ b/docs/api/async-logger-warn.md @@ -39,8 +39,9 @@ pub async fn[S] AsyncLogger::warn( Detailed rules explaining key parameters and behaviors -- This helper delegates to `log(Level::Warn, ...)`. +- This helper delegates to `log(Level::Warn, ..., fields=fields)`. - The record is still subject to min-level gating, patching, filtering, and overflow policy. +- This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with `with_target(...)` or `child(...)`. - 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. @@ -80,4 +81,4 @@ e.g.: 1. Use this helper for notable but non-fatal async runtime conditions. -2. Pair warnings with structured fields when operators need quick context. +2. Use `log(...)` instead when one warning call must override the target without deriving a new logger value.