📝 consolidate logger API and async lifecycle guidance

This commit is contained in:
Nanaloveyuki
2026-06-14 14:00:00 +08:00
parent 4f2ad097af
commit 265cd69ea9
154 changed files with 2419 additions and 396 deletions
+10 -2
View File
@@ -28,16 +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.
- 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
@@ -53,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:
@@ -76,3 +80,7 @@ e.g.:
1. This is the preferred API for hierarchical async logger naming.
2. Composition changes the target only and does not rebuild the queue or sink.
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.