From feb786298fcf3dc21622a1903c0946c170345095 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 08:29:26 +0800 Subject: [PATCH] :memo: clarify built async text target behavior --- docs/api/build-application-text-async-logger.md | 13 +++++++++++++ docs/api/build-async-text-logger.md | 13 +++++++++++++ docs/api/build-library-async-text-logger.md | 13 +++++++++++++ 3 files changed, 39 insertions(+) diff --git a/docs/api/build-application-text-async-logger.md b/docs/api/build-application-text-async-logger.md index 4b5a1da..8aaed05 100644 --- a/docs/api/build-application-text-async-logger.md +++ b/docs/api/build-application-text-async-logger.md @@ -43,6 +43,7 @@ Detailed rules explaining key parameters and behaviors - A sync queue configured on `LoggerConfig.queue` is therefore ignored by this builder instead of being preserved under the returned async logger. - Because the result is only the `ApplicationTextAsyncLogger` alias over `AsyncLogger[@bitlogger.FormattedConsoleSink]`, this builder returns the same underlying async logger value as `build_async_text_logger(...)` and does not hide any async helpers or introduce a wrapper layer. - The returned alias also keeps inherited async logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. +- In particular, `log(..., target=...)` can override the target for one call, while severity helpers such as `debug(...)`, `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless code derives another logger first with `with_target(...)` or `child(...)`. - The returned logger keeps the full async lifecycle and state helper surface directly, including helpers such as `run()`, `shutdown()`, `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, and `last_error()`. - It also keeps the same close, queue, and failure-state semantics as the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. - In the current direct text-builder coverage, this alias matches `build_async_text_logger(config)` through serialized state snapshots, formatter behavior, queue counters, lifecycle flags, and later failure fields after worker execution. @@ -70,6 +71,18 @@ In this example, the async logger is built for text-console output specifically. And the returned value keeps the ordinary async logger target semantics because this facade does not wrap or narrow the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. +#### When Need A Per-call Target Override After App Text Construction + +When typed app async text config should still build a logger that supports a one-call target override: +```moonbit +let logger = build_application_text_async_logger(config) +logger.log(@bitlogger.Level::Error, "boom", target="app.text.audit") +``` + +In this example, the emitted record uses `app.text.audit` for that call. + +And later `debug(...)`, `info(...)`, `warn(...)`, or `error(...)` calls still use the logger's stored target unless code derives another logger first with `with_target(...)` or `child(...)`. + #### When Need Async State Helpers Immediately After Text App Construction When application code should keep the ordinary async helper surface directly on the text-console variant: diff --git a/docs/api/build-async-text-logger.md b/docs/api/build-async-text-logger.md index 2f00991..33f0146 100644 --- a/docs/api/build-async-text-logger.md +++ b/docs/api/build-async-text-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - Unlike `build_async_logger(...)`, this helper does not run the full synchronous `build_logger(config.logger)` path first. - That means it uses `config.logger.sink.text_formatter`, `min_level`, `target`, and `timestamp` directly, but it does not apply `LoggerConfig.queue` or preserve other sync runtime sink controls. - This builder returns the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value directly. `build_application_text_async_logger(...)` only re-exports that same result under the `ApplicationTextAsyncLogger` alias, while `build_library_async_text_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`. +- The returned async logger also keeps ordinary target rules unchanged: `log(..., target=...)` can override the target for one call, while severity helpers such as `debug(...)`, `info(...)`, `warn(...)`, and `error(...)` continue to use the stored logger target unless a derived logger was created first with `with_target(...)` or `child(...)`. - In the current direct text-builder coverage, the returned logger exposes the expected serialized async state snapshot, formatter behavior, queue counters, lifecycle flags, and later failure fields after worker execution. - The async `flush_policy` still comes from `config.async_config`, but this text-specific builder does not supply the explicit `flush=fn(sink) { sink.flush() }` callback used by `build_async_logger(...)`. - In practice, `Batch` and `Shutdown` therefore only trigger the default no-op async flush callback on this path, while each record write still follows whatever immediate behavior `FormattedConsoleSink` already has on its own. @@ -63,6 +64,18 @@ let logger = build_async_text_logger( In this example, the async logger is built around a text console sink rather than the generic runtime sink enum. +#### When Need A Per-call Target Override After Built Async Text Construction + +When typed async text config should still build a logger that supports a one-call target override: +```moonbit +let logger = build_async_text_logger(config) +logger.log(@bitlogger.Level::Error, "boom", target="async.text.audit") +``` + +In this example, the emitted record uses `async.text.audit` for that call. + +And later `debug(...)`, `info(...)`, `warn(...)`, or `error(...)` calls still use the logger's stored target unless code derives another logger first with `with_target(...)` or `child(...)`. + ### Error Case e.g.: diff --git a/docs/api/build-library-async-text-logger.md b/docs/api/build-library-async-text-logger.md index a2eef7a..b077aaa 100644 --- a/docs/api/build-library-async-text-logger.md +++ b/docs/api/build-library-async-text-logger.md @@ -44,6 +44,7 @@ Detailed rules explaining key parameters and behaviors - In the current direct text-builder coverage, unwrapping this facade yields the same async state snapshot, formatter behavior, queue counters, lifecycle flags, and later failure fields as calling `build_async_text_logger(config)` directly. - The configured `flush_policy` is still carried by that underlying async logger, but this text-specific builder path does not provide the explicit sink flush callback used by `build_library_async_logger(...)` through `build_async_logger(...)`. - As a result, `Batch` and `Shutdown` only invoke the default no-op async flush callback on this text-console path unless downstream code unwraps and adds different behavior elsewhere. +- The facade still preserves the underlying async target rules on its exposed write methods: `log(..., target=...)` can override the target for one call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`, not on the returned facade itself. - `to_async_logger()` can recover the underlying full async logger if needed. - Use this builder when the boundary should preserve the concrete text-console sink type while still hiding broader async inspection and helper APIs from downstream callers. @@ -77,6 +78,18 @@ ignore(full.pending_count()) In this example, the facade is unwrapped before using async state helpers. +#### When Need A Per-call Target Override Through The Library Async Text Builder Facade + +When typed library async text config should still build a facade that allows a one-call target override without unwrapping first: +```moonbit +let logger = build_library_async_text_logger(config) +logger.log(@bitlogger.Level::Error, "boom", target="lib.text.audit") +``` + +In this example, the emitted record uses `lib.text.audit` for that call. + +And later `info(...)`, `warn(...)`, or `error(...)` calls still use the facade's stored target unless code derives another facade first with `with_target(...)` or `child(...)`. + ### Error Case e.g.: