📝 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
+12 -3
View File
@@ -2,8 +2,8 @@
name: library-async-logger-child
group: api
category: facade
update-time: 20260613
description: Derive a child LibraryAsyncLogger facade by composing the current target with a child segment.
update-time: 20260614
description: Derive a child LibraryAsyncLogger facade by composing the current target with a child segment while rewrapping the derived async logger state behind the same library-facing surface.
key-word:
- async
- library
@@ -37,10 +37,13 @@ pub fn[S] LibraryAsyncLogger::child(
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped async logger's `child(...)` behavior and then re-wraps the result.
- This API delegates to the wrapped async logger's `child(...)` behavior and then re-wraps the result as another `LibraryAsyncLogger[S]`.
- 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 `.`.
- The original facade is not mutated. The returned facade stores the derived child target while the source facade keeps its previous parent target.
- Timestamp behavior, enabled-level gating, sink type, queue state, async config, and failure/lifecycle state remain the same because only the derived default target changes.
- Async state helpers remain hidden behind the narrower facade after rewrapping; use `to_async_logger()` if later code needs them.
### How to Use
@@ -68,6 +71,10 @@ let client = LibraryAsyncLogger::new(@bitlogger.console_sink(), target="sdk")
In this example, the final facade emits under `sdk.http.client`.
And the target derivation does not rebuild or reset the wrapped async logger state.
The derived facade still uses the same timestamp and level-gating behavior as the source facade.
### Error Case
e.g.:
@@ -80,3 +87,5 @@ e.g.:
1. This is the preferred library-facing API for hierarchical async target naming.
2. Composition changes the target only and does not rebuild the queue or sink.
3. Use `with_target(...)` instead when the new target should replace the current target rather than extend it.