diff --git a/docs/api/build-logger.md b/docs/api/build-logger.md index beea3b1..056965e 100644 --- a/docs/api/build-logger.md +++ b/docs/api/build-logger.md @@ -35,6 +35,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(...)`. - 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. @@ -58,7 +59,7 @@ let logger = build_logger( In this example, no JSON parsing is required because config objects were built directly. -And the runtime logger is ready immediately. +And the runtime logger is ready immediately, with the same ordinary logger target semantics as any other `Logger` value. #### When Need Config-built Queue Or File Runtime Helpers diff --git a/docs/api/configured-logger.md b/docs/api/configured-logger.md index 44fea3e..e38928f 100644 --- a/docs/api/configured-logger.md +++ b/docs/api/configured-logger.md @@ -31,6 +31,7 @@ Detailed rules explaining key parameters and behaviors - This is a type alias, not a separate wrapper implementation. - It preserves normal logger methods such as `info(...)`, `warn(...)`, `error(...)`, and the other `Logger` APIs. +- Because it is `Logger[RuntimeSink]`, it also keeps ordinary logger composition and target behavior such as `with_target(...)`, `child(...)`, and per-call `log(..., target=...)` overrides. - It also exposes configured runtime helpers such as `flush()`, `drain()`, `pending_count()`, `dropped_count()`, and file-specific controls when the runtime sink supports them. - Builders such as `build_logger(...)` and `parse_and_build_logger(...)` return this alias as the main sync config-to-runtime result. - `ApplicationLogger` is another direct alias-oriented name for this same configured runtime surface, while `LibraryLogger[RuntimeSink]` is the narrowing facade variant that intentionally hides these runtime helpers until `to_logger()` is used. @@ -58,6 +59,8 @@ ignore(logger.pending_count()) In this example, the alias keeps ordinary logging calls while still exposing runtime diagnostics. +And the inherited logger target rules stay unchanged: `log(..., target=...)` can override the target per call, while `with_target(...)` and `child(...)` derive new logger values with changed default targets. + ### Error Case e.g.: @@ -69,6 +72,8 @@ e.g.: 1. Use `build_logger(...)` or `parse_and_build_logger(...)` when you need a value of this type. -2. Use `ApplicationLogger` when application code wants the same full configured-runtime helper surface under an app-facing name. +2. Inherited `Logger` behavior stays unchanged on this alias, including target overrides on `log(...)` and derived target composition through `with_target(...)` and `child(...)`. -3. Use `LibraryLogger[RuntimeSink]` when a library boundary should intentionally hide configured-runtime helper methods behind a narrower facade. +3. Use `ApplicationLogger` when application code wants the same full configured-runtime helper surface under an app-facing name. + +4. Use `LibraryLogger[RuntimeSink]` when a library boundary should intentionally hide configured-runtime helper methods behind a narrower facade. diff --git a/docs/api/parse-and-build-logger.md b/docs/api/parse-and-build-logger.md index 45b09ff..f6fd5c7 100644 --- a/docs/api/parse-and-build-logger.md +++ b/docs/api/parse-and-build-logger.md @@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors - Parsing and building are done in one step by calling `parse_logger_config_text(input)` first and then passing the resulting `LoggerConfig` into `build_logger(...)`. - The returned `ConfiguredLogger` is just `Logger[RuntimeSink]`, so it still supports regular logging calls. +- The returned logger also keeps inherited logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - Queue wrapping and file control helpers remain available after config assembly. - `parse_and_build_application_logger(...)` only re-exports this same configured runtime logger result under the `ApplicationLogger` alias, while `parse_and_build_library_logger(...)` wraps the same result in `LibraryLogger[RuntimeSink]`. - Errors are surfaced as `ConfigError` rather than silent fallback. @@ -59,7 +60,7 @@ let logger = parse_and_build_logger( In this example, config parsing and logger construction happen in one place. -And the resulting value can immediately emit logs. +And the resulting value can immediately emit logs with the same ordinary logger target semantics as any other `Logger` value. #### When Need Config-built File Or Queue Controls