From fe7665b9f61ad4a803381e55f46861232e54542a Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 11:33:49 +0800 Subject: [PATCH] :memo: clarify logger child composition contract --- docs/api/logger-child.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/api/logger-child.md b/docs/api/logger-child.md index 872f2be..1657fd8 100644 --- a/docs/api/logger-child.md +++ b/docs/api/logger-child.md @@ -28,16 +28,18 @@ pub fn[S] Logger::child(self : Logger[S], target : String) -> Logger[S] {} #### output -- `Logger[S]` - A new logger whose default target is the composed child path. +- `Logger[S]` - A new logger value whose default target is the composed child path. ### Explanation Detailed rules explaining key parameters and behaviors +- The returned logger is derived from `self`; the original logger value is not mutated. - If the parent target is empty, the child target becomes the full target. - If the child target is empty, the parent target is preserved. - If both are non-empty, they are joined with `.`. -- Sink, min level, and timestamp settings are preserved in the returned logger. +- Only the stored target changes. Sink, min level, and timestamp settings are preserved in the returned logger. +- The wider composition surface stays available on the derived logger, so follow-up calls such as `with_timestamp()` or log writes continue to work with the composed target. ### How to Use @@ -53,6 +55,8 @@ let worker = logger.child("worker") In this example, `worker` emits records under `service.worker`. +And `logger` still keeps its original stored target, because `child(...)` returns a derived logger value instead of mutating the parent. + #### When Build Deeply Scoped Loggers Step By Step When deeper target composition should remain readable: @@ -77,3 +81,5 @@ e.g.: 2. Composition uses `.` as the separator between parent and child segments. +3. The same compose-and-preserve contract is exercised through the library, configured, and application logger surfaces, not only on the base `Logger[S]` value. +