📝 clarify async logger child contract

This commit is contained in:
Nanaloveyuki
2026-06-14 11:35:29 +08:00
parent fe7665b9f6
commit c800042e46
+9 -4
View File
@@ -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.