From 0a9bcd696b203832cc20ae2f6c5127b7c03ee42b Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 11:59:01 +0800 Subject: [PATCH] :memo: clarify sync level threshold derivation --- docs/api/logger-with-min-level.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/api/logger-with-min-level.md b/docs/api/logger-with-min-level.md index 266dcfe..50bcdf2 100644 --- a/docs/api/logger-with-min-level.md +++ b/docs/api/logger-with-min-level.md @@ -36,8 +36,9 @@ Detailed rules explaining key parameters and behaviors - `log(...)` checks `is_enabled(level)` before constructing and writing a record. - Lower-severity records below `min_level` are skipped without reaching the sink. -- This API replaces the logger threshold and does not add a wrapper sink. -- The returned logger keeps the same sink, target, and timestamp settings. +- The returned logger is derived from `self`; the original logger value is not mutated. +- This API replaces the stored threshold and does not add a wrapper sink. +- Only `min_level` changes. Sink, target, and timestamp behavior stay on the same `Logger[S]` surface. ### How to Use @@ -53,6 +54,8 @@ let logger = Logger::new(console_sink()) In this example, `trace`, `debug`, and `info` calls are skipped. +The returned logger still uses the same ordinary synchronous logging calls; only the severity gate changes. + #### When Derive A More Verbose Local Logger When one branch of code should keep a different threshold: @@ -70,3 +73,11 @@ e.g.: - If callers need richer predicate logic than a simple threshold, `with_filter(...)` should be used instead. +### Notes + +1. This API skips disabled levels before any sink write happens. + +2. Use it before adding more complex predicate-based filtering rules. + +3. Use a derived logger value when one branch should tighten the threshold and the base logger should keep its broader level gate. +