diff --git a/docs/api/build-application-logger.md b/docs/api/build-application-logger.md index e511016..b8b75e5 100644 --- a/docs/api/build-application-logger.md +++ b/docs/api/build-application-logger.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application. - Because the result is only the `ApplicationLogger` alias over `ConfiguredLogger`, this builder does not hide any queue, drain, flush, or file runtime helper methods. - The returned alias also keeps inherited `Logger` behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. +- That means `log(..., target=...)` can override the target for one write, while severity helpers such as `info(...)`, `warn(...)`, and `error(...)` continue to use the stored logger target unless a derived logger was created first with `with_target(...)` or `child(...)`. - Use this alias-oriented entrypoint when application boot code wants an app-specific name without changing the underlying configured runtime logger surface. ### How to Use @@ -58,6 +59,18 @@ And any queue/file/runtime helpers selected by the config remain directly availa The returned value also keeps the ordinary logger target semantics because the facade does not wrap or narrow the underlying `ConfiguredLogger`. +#### When Need A Per-call Target Override After App-oriented Build + +When typed app config should still build a logger that supports a one-write target override: +```moonbit +let logger = build_application_logger(config) +logger.log(Level::Error, "boom", target="app.audit") +``` + +In this example, the emitted record uses `app.audit` for that write. + +And later `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-logger.md b/docs/api/build-library-logger.md index 9d8d3f5..f2e72e3 100644 --- a/docs/api/build-library-logger.md +++ b/docs/api/build-library-logger.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application. - The returned facade wraps the same underlying `ConfiguredLogger` value that `build_logger(...)` would produce directly. - The facade intentionally exposes a smaller logging surface than the full configured runtime logger. +- The facade still preserves the underlying logger target rules on its exposed write methods: `log(..., target=...)` can override the target for one write, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`. - Queue metrics, flush and drain helpers, and file runtime controls remain on the underlying `ConfiguredLogger`, not on the returned facade itself. - Call `to_logger()` if a caller must recover the underlying full logger object. - Use this builder when the boundary should preserve the configured runtime logger path but still hide broader runtime helper methods from downstream callers. @@ -69,6 +70,18 @@ In this example, the library facade is unwrapped before using runtime-specific h And the unwrapped value still carries the same `RuntimeSink` pipeline built from the original config. +#### When Need A Per-call Target Override Through The Library Builder Facade + +When typed library config should still build a facade that allows a one-write target override without unwrapping first: +```moonbit +let logger = build_library_logger(config) +logger.log(Level::Error, "boom", target="lib.audit") +``` + +In this example, the emitted record uses `lib.audit` for that write. + +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.: diff --git a/docs/api/build-logger.md b/docs/api/build-logger.md index 056965e..f371518 100644 --- a/docs/api/build-logger.md +++ b/docs/api/build-logger.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - `build_logger(...)` first constructs a base `RuntimeSink` from `config.sink`, then applies `config.queue` when present, and finally builds `Logger::new(...)` with `config.min_level`, `config.target`, and `config.timestamp`. - The returned logger still supports normal logging methods because `ConfiguredLogger` is `Logger[RuntimeSink]`. - The returned logger also keeps inherited logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. +- That means `log(..., target=...)` can override the target for one write, while severity helpers such as `info(...)`, `warn(...)`, and `error(...)` continue to use the stored logger target unless a derived logger was created first with `with_target(...)` or `child(...)`. - Queue metrics and file controls remain available through forwarding helpers on the configured logger. - `build_application_logger(...)` only re-exports this same configured runtime logger result under the `ApplicationLogger` alias, while `build_library_logger(...)` wraps the same result in `LibraryLogger[RuntimeSink]`. - This API is deterministic and data-driven, making it suitable for bootstrapping from parsed config. @@ -61,6 +62,18 @@ In this example, no JSON parsing is required because config objects were built d And the runtime logger is ready immediately, with the same ordinary logger target semantics as any other `Logger` value. +#### When Need A Per-call Target Override After Typed Config Build + +When typed config should still build a logger that supports a one-write target override: +```moonbit +let logger = build_logger(config) +logger.log(Level::Error, "boom", target="svc.audit") +``` + +In this example, the emitted record uses `svc.audit` for that write. + +And later `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 Config-built Queue Or File Runtime Helpers When the sink shape comes from config but runtime controls still matter: