From 5514009abe8b97c11799620854eb1c2b3d84ba29 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 11:54:18 +0800 Subject: [PATCH] :memo: clarify sync patch wrapper contract --- docs/api/logger-with-patch.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/api/logger-with-patch.md b/docs/api/logger-with-patch.md index 57c6666..3d76c8f 100644 --- a/docs/api/logger-with-patch.md +++ b/docs/api/logger-with-patch.md @@ -28,13 +28,16 @@ pub fn[S] Logger::with_patch(self : Logger[S], patch : RecordPatch) -> Logger[Pa #### output -- `Logger[PatchSink[S]]` - A new logger that rewrites emitted records. +- `Logger[PatchSink[S]]` - A new logger value whose visible sink type becomes `PatchSink[S]` and rewrites emitted records. ### Explanation Detailed rules explaining key parameters and behaviors - Patches can rewrite `target`, `message`, and `fields` because they receive the full `Record`. +- The original logger is not mutated; a derived wrapped logger is returned. +- The returned logger changes visible type from `Logger[S]` to `Logger[PatchSink[S]]` because the sink pipeline is extended with record transformation. +- Stored target, minimum level, and timestamp behavior are preserved while the sink pipeline changes. - This API does not change logging level gating; level checks still happen at the logger level. - `compose_patches(...)` can be used to build ordered patch pipelines. - This is the correct place for redaction, enrichment, and message prefixing. @@ -55,6 +58,8 @@ In this example, matching field values are replaced before the sink sees them. And caller code does not need custom redaction logic per log call. +The returned logger still uses the same ordinary synchronous logging calls; only the sink path now includes patching. + #### When Need Combined Enrichment And Message Rewrite When you want several transformations in a stable order: @@ -81,3 +86,5 @@ e.g.: 2. Prefer helper patches such as `prefix_message(...)`, `append_fields(...)`, and `redact_fields(...)` for common cases. +3. Use a derived logger value when one path should rewrite records and another should keep the original sink behavior unchanged. +