📝 clarify async helper combinator docs

This commit is contained in:
Nanaloveyuki
2026-06-14 07:25:15 +08:00
parent f636c2df60
commit 38a5b056b8
3 changed files with 9 additions and 0 deletions
+3
View File
@@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors
- Existing filter logic is preserved and combined with the new predicate using logical `and`. - Existing filter logic is preserved and combined with the new predicate using logical `and`.
- The original async logger is not mutated. - The original async logger is not mutated.
- Filtering avoids unnecessary queue pressure for records that should never be delivered. - Filtering avoids unnecessary queue pressure for records that should never be delivered.
- In the current direct async coverage, derived filters can compose target, level, and message predicates together while the original logger still accepts writes according to its previous filter state.
### How to Use ### How to Use
@@ -80,3 +81,5 @@ e.g.:
1. Use this API for selection logic, not record mutation. 1. Use this API for selection logic, not record mutation.
2. Async filtering is especially useful when queue capacity should be reserved for high-value records. 2. Async filtering is especially useful when queue capacity should be reserved for high-value records.
3. Use a derived logger value when one branch should enforce extra filter rules and the base async logger should stay unchanged.
+3
View File
@@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors
- Lower-severity records below `min_level` are skipped before enqueue. - Lower-severity records below `min_level` are skipped before enqueue.
- This API replaces the logger threshold and does not alter queue configuration. - This API replaces the logger threshold and does not alter queue configuration.
- The returned logger keeps the same sink, target, and timestamp settings. - The returned logger keeps the same sink, target, and timestamp settings.
- In the current direct async coverage, the derived logger reports the new threshold through `is_enabled(...)`, while the original logger keeps its previous minimum level and still accepts records that remain enabled there.
### How to Use ### How to Use
@@ -78,3 +79,5 @@ e.g.:
1. This API reduces async queue pressure by dropping disabled levels before enqueue. 1. This API reduces async queue pressure by dropping disabled levels before enqueue.
2. Use it before adding more complex async filtering rules. 2. Use it before adding more complex async filtering rules.
3. Use a derived logger value when one branch should tighten the threshold and the base async logger should keep its broader level gate.
+3
View File
@@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors
- Existing patch logic is preserved and composed so the new patch wraps the current one. - Existing patch logic is preserved and composed so the new patch wraps the current one.
- The original async logger is not mutated. - The original async logger is not mutated.
- Patching can normalize, redact, or enrich records before they consume queue capacity. - Patching can normalize, redact, or enrich records before they consume queue capacity.
- In the current direct async coverage, patched target/message/field changes are visible to later filter logic, and the original async logger still emits unpatched records when used separately.
### How to Use ### How to Use
@@ -80,3 +81,5 @@ e.g.:
1. Use patches for transformation, not filtering decisions. 1. Use patches for transformation, not filtering decisions.
2. Redaction before enqueue helps keep sensitive data out of the queued pipeline. 2. Redaction before enqueue helps keep sensitive data out of the queued pipeline.
3. Derive a patched logger when one path needs rewritten records and another should keep the original async record shape.