From 958a7fd26f39a7a60af5394271b12cec647035e3 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 11:39:38 +0800 Subject: [PATCH] :memo: clarify async context field storage --- docs/api/async-logger-with-context-fields.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/api/async-logger-with-context-fields.md b/docs/api/async-logger-with-context-fields.md index 864b36b..be98b66 100644 --- a/docs/api/async-logger-with-context-fields.md +++ b/docs/api/async-logger-with-context-fields.md @@ -31,7 +31,7 @@ pub fn[S] AsyncLogger::with_context_fields( #### output -- `AsyncLogger[S]` - A new async logger carrying the shared field set. +- `AsyncLogger[S]` - A new async logger value carrying the shared field set. ### Explanation @@ -42,6 +42,7 @@ Detailed rules explaining key parameters and behaviors - This API returns a new logger value; it does not mutate the original async logger. - The provided `fields` array replaces the previously stored shared field set on the returned async logger; it does not append onto whatever `context_fields` the source logger already had. - Unlike synchronous `Logger::with_context_fields(...)`, this async variant stores fields directly on `AsyncLogger` instead of changing the visible sink type. +- Only the stored `context_fields` value changes. Target, minimum level, timestamp flag, queue configuration, and lifecycle/failure state stay on the same `AsyncLogger[S]` surface. - In the current direct async coverage, the original logger keeps its previous `context_fields`, while the derived logger prepends the stored shared fields ahead of per-call fields exactly once when records are built. ### How to Use @@ -61,6 +62,8 @@ let logger = async_logger(console_sink(), target="billing") In this example, both fields are attached before each record enters the queue. +And the returned async logger still keeps the same queue-facing API surface as the source logger. + #### When Build Child Async Loggers For Subsystems When a subsystem has both a target and fixed fields: @@ -87,6 +90,8 @@ e.g.: 2. This async variant preserves the visible `AsyncLogger[S]` type while still injecting shared fields. -3. Use a fresh derived logger when one code path needs shared metadata and another should stay unchanged. +3. State helpers such as `pending_count()`, `dropped_count()`, `is_closed()`, and `has_failed()` remain available on the returned logger because the visible async logger surface is preserved. -4. If you need to combine two shared field sets, combine them in the `fields` argument yourself instead of expecting repeated `with_context_fields(...)` calls to accumulate them. +4. Use a fresh derived logger when one code path needs shared metadata and another should stay unchanged. + +5. If you need to combine two shared field sets, combine them in the `fields` argument yourself instead of expecting repeated `with_context_fields(...)` calls to accumulate them.