diff --git a/docs/api/async-logger-child.md b/docs/api/async-logger-child.md index 866290c..c2f8113 100644 --- a/docs/api/async-logger-child.md +++ b/docs/api/async-logger-child.md @@ -28,17 +28,18 @@ pub fn[S] AsyncLogger::child(self : AsyncLogger[S], target : String) -> AsyncLog #### output -- `AsyncLogger[S]` - A new async logger whose default target is the composed child path. +- `AsyncLogger[S]` - A new async 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 async 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 `.`. -- Queue settings, sink wiring, and runtime behavior are preserved in the returned logger. -- In the current direct async coverage, other flags such as `timestamp` and the enabled-level gate are preserved on the derived child logger while the original logger keeps its parent target unchanged. +- Only the stored target changes. Queue settings, sink wiring, flush policy, level gating, and lifecycle state remain shared with the same underlying async logger setup. +- In the current direct async coverage, `timestamp` is also preserved on the derived child logger while the source logger keeps its previous parent target. ### How to Use @@ -54,6 +55,8 @@ let worker = logger.child("worker") In this example, `worker` emits under `service.worker` while keeping the same async queue behavior. +And `logger` still keeps its original stored target, because `child(...)` returns a derived async logger value instead of mutating the parent. + #### When Build Deep Async Scopes Step By Step When deeper target composition should remain readable: @@ -78,4 +81,6 @@ e.g.: 2. Composition changes the target only and does not rebuild the queue or sink. -3. Use `child("")` when code should keep the current target while still following a target-composition code path. +3. State helpers such as `pending_count()`, `dropped_count()`, `is_closed()`, and `has_failed()` still operate on the same async logger state after derivation. + +4. Use `child("")` when code should keep the current target while still following a target-composition code path.