From 33f71af500c690792a03aebe6599020d003d7d7c Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 02:42:37 +0800 Subject: [PATCH] :memo: clarify queued file failure docs --- docs/api/configured-logger-file-flush.md | 3 ++- docs/api/configured-logger-file-reset-failure-counters.md | 2 +- docs/api/configured-logger-file-write-failures.md | 3 ++- docs/api/runtime-sink-file-flush.md | 3 ++- docs/api/runtime-sink-file-reset-failure-counters.md | 2 +- docs/api/runtime-sink-file-write-failures.md | 3 ++- 6 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/api/configured-logger-file-flush.md b/docs/api/configured-logger-file-flush.md index 42b26f4..dadbd5f 100644 --- a/docs/api/configured-logger-file-flush.md +++ b/docs/api/configured-logger-file-flush.md @@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors - Plain file sinks forward directly to file flush behavior through the wrapped `RuntimeSink`. - Queued file sinks first flush queued records, then flush the wrapped inner file sink. +- For queued file sinks, this step may also be the point where queued records finally hit the inner file sink, so write-failure counters can change here even if earlier log calls only queued records. - Non-file sinks return `false`. - This helper is narrower than generic `flush()` because it targets file sink behavior specifically. @@ -71,4 +72,4 @@ e.g.: 1. Prefer this helper when the configured sink is known to be file-backed. -2. Queued file sinks may perform both queue flush and file flush work here. +2. Queued file sinks may perform both queue flush and file flush work here, including surfacing delayed write failures from previously queued records. diff --git a/docs/api/configured-logger-file-reset-failure-counters.md b/docs/api/configured-logger-file-reset-failure-counters.md index 8722375..f5cf60f 100644 --- a/docs/api/configured-logger-file-reset-failure-counters.md +++ b/docs/api/configured-logger-file-reset-failure-counters.md @@ -72,4 +72,4 @@ e.g.: 1. Use this helper after diagnostics or recovery, not before capturing needed evidence. -2. It is the reset companion for the file failure-counter helpers. +2. For queued file sinks, it resets the inner file counters only; it does not clear still-pending queued records that may produce new failures on a later `file_flush()`. diff --git a/docs/api/configured-logger-file-write-failures.md b/docs/api/configured-logger-file-write-failures.md index 58e27c9..235f778 100644 --- a/docs/api/configured-logger-file-write-failures.md +++ b/docs/api/configured-logger-file-write-failures.md @@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors - File-backed sinks report their recorded write-failure count through the wrapped `RuntimeSink`. - Queued file sinks forward the metric from the wrapped inner file sink. +- For queued file sinks, enqueueing a record does not increment this counter by itself. The counter changes only when queued records are drained into the inner file sink, such as through `file_flush()`. - Non-file sinks return `0`. - The counter is cumulative until reset. @@ -71,4 +72,4 @@ e.g.: 1. Use this helper for focused write-failure visibility. -2. Pair it with `file_flush_failures()` when diagnosing output-path instability. +2. Pair it with `file_flush()` and `file_flush_failures()` when diagnosing queued output-path instability. diff --git a/docs/api/runtime-sink-file-flush.md b/docs/api/runtime-sink-file-flush.md index 6565445..1e81469 100644 --- a/docs/api/runtime-sink-file-flush.md +++ b/docs/api/runtime-sink-file-flush.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants forward directly to `FileSink::flush()`. - `QueuedFile` runtime variants first attempt `sink.flush()` on the queue wrapper, then call `sink.sink.flush()` on the wrapped file sink. - For `QueuedFile`, the queue flush result is ignored and the returned `Bool` comes from the inner file flush. +- For `QueuedFile`, this step may also be the point where queued records finally reach the inner file sink, so write-failure counters can change here even if earlier `log(...)` calls only enqueued records. - Non-file runtime variants return `false`. ### How to Use @@ -71,4 +72,4 @@ e.g.: 1. Prefer this helper when direct runtime code specifically cares about file flush behavior. -2. Queued file sinks may perform both queue flush work and file flush work here. +2. Queued file sinks may perform both queue flush work and file flush work here, including surfacing delayed write failures from previously queued records. diff --git a/docs/api/runtime-sink-file-reset-failure-counters.md b/docs/api/runtime-sink-file-reset-failure-counters.md index 838547d..092133f 100644 --- a/docs/api/runtime-sink-file-reset-failure-counters.md +++ b/docs/api/runtime-sink-file-reset-failure-counters.md @@ -72,4 +72,4 @@ e.g.: 1. Use this helper after diagnostics or recovery, not before capturing needed evidence. -2. It is the reset companion for the direct runtime file failure-counter helpers. +2. For queued file sinks, it resets the inner file counters only; it does not clear still-pending queued records that may produce new failures on a later `file_flush()`. diff --git a/docs/api/runtime-sink-file-write-failures.md b/docs/api/runtime-sink-file-write-failures.md index da965fb..a573cf1 100644 --- a/docs/api/runtime-sink-file-write-failures.md +++ b/docs/api/runtime-sink-file-write-failures.md @@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors - Plain `File` runtime variants report the wrapped `FileSink` write-failure count. - `QueuedFile` runtime variants forward the metric from the wrapped inner `FileSink`. +- For `QueuedFile`, enqueueing a record does not increment this counter by itself. The counter changes only when queued records are actually drained into the inner file sink, such as through `file_flush()`. - Non-file runtime variants return `0`. - The counter is cumulative until `file_reset_failure_counters()` clears it. @@ -71,4 +72,4 @@ e.g.: 1. Use this helper for focused direct runtime write-failure visibility. -2. Pair it with `file_flush_failures()` when diagnosing output-path instability. +2. Pair it with `file_flush()` and `file_flush_failures()` when diagnosing queued output-path instability.