]> git.hungrycats.org Git - bees/commitdiff
docs: document the refs_pending and pending_ref_* counters
authorZygo Blaxell <bees@furryterror.org>
Wed, 23 Sep 2026 04:15:14 +0000 (00:15 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sun, 11 Oct 2026 00:48:00 +0000 (20:48 -0400)
Commit 8f596c838d5be453734c5ecd2dea309a792a8057
("verification: carry pending references in the verification ring")
added these counters without an entry in docs/event-counters.md.

Assisted-by: Claude-Code:claude-opus-5-5
docs/event-counters.md

index b75fe54422e56689d70d3a4d804b84f24d8c1265..815ab7a1a653bd50056710ab5b9598e2f8e99687 100644 (file)
@@ -346,6 +346,14 @@ The `pairforward` event group consists of events related to extending matching b
  * `pairforward_try`: Started extending a pair of matching block ranges forward.
  * `pairforward_zero`: A pair of matching block ranges could not be extended backward by one block because the src block contained all zeros and was not compressed.
 
+pending
+-------
+
+The `pending` event group tracks references created by bees's own dedupes.  A `LOGICAL_INO` walk of the commit root cannot report such a reference until its transaction commits, so bees carries it in the verification ring and merges it into the extent layer's reference lists until then.
+
+ * `pending_ref_add`: A reference created by a dedupe was recorded as pending.
+ * `pending_ref_expire`: Total number of pending references dropped because their transaction has committed and the kernel now reports them.
+
 plan
 ----
 
@@ -444,6 +452,7 @@ the calls made by the extent layer.
  * `refs_ms`: Total wallclock time spent in the `LOGICAL_INO` ioctl.
  * `refs_ok`: A `LOGICAL_INO` ioctl call completed successfully.
  * `refs_overflow`: An extent had at least `rewrite.refs-max` references, so its reference list was suppressed and the extent reported as having none.  Such an extent cannot take another reference and cannot be enumerated in full by a `LOGICAL_INO` buffer sized to `rewrite.refs-max`, so it is left inert as a permanent canonical source.
+ * `refs_pending`: Total number of pending references (see the `pending` group) merged into `LOGICAL_INO` results because the kernel could not report them yet.
  * `refs_try`: A `LOGICAL_INO` ioctl call was attempted.
  * `refs_zero`: A `LOGICAL_INO` ioctl call returned no refs.