]> git.hungrycats.org Git - bees/commitdiff
scan_next: count planner coverage-search and plan decisions
authorZygo Blaxell <bees@furryterror.org>
Tue, 14 Jul 2026 21:58:31 +0000 (17:58 -0400)
committerZygo Blaxell <bees@furryterror.org>
Sat, 10 Oct 2026 19:00:03 +0000 (15:00 -0400)
The planner made several branch decisions that were invisible in the event
counters. The existing plan_* counters track only the plan lifecycle
(plan_start / plan_execute / plan_empty / plan_dst_executed), not which
path was taken or why a plan was declined, so a workload where the planner
constantly bails looked identical in the stats to one sailing through.

Add three families of counters, all in the plan group:

  - coverage search (bees-plan.cc): plan_cover_exact / plan_cover_greedy
    record which algorithm ran, so the rate at which rewrite.plan-max-vertices
    trips is now visible; plan_cover_none_{compressed,hole,limit} record why a
    search produced no covering. The whole file was previously uninstrumented.

  - reject reasons (scan_next_reject_reason): plan_reject_* — one per enumerated
    rejection string, which were logged at DEBUG but never counted. Knowing
    which limit binds (dedupe/copy/hole/total or a compressed-dst rule) is the
    actionable signal.

  - accept by plan type: a new pure-virtual BeesPlan::count_accepted(), called
    once on the winning plan, so plan_accept_{start_as_dst,start_as_src,null}
    record which strategy won each ballot. Pure virtual so a future plan type
    cannot be silently uncounted.

Document the whole plan group in docs/event-counters.md (the pre-existing
plan_* counters were undocumented too).

bees-plan.cc was deliberately kept linkable without the bees daemon so the
coverage search can be unit-tested against a brute-force oracle; BEESCOUNT
pulls in BeesStats::s_global / add_count, which test-bees-plan has to resolve
from somewhere.  Link a test-local, function-sectioned rebuild of
bees-util.cc (test-bees-util-lib.o, mirroring test-bees-plan-lib.o) rather
than the stock ../src/bees-util.o: that object is built without
-ffunction-sections, so GNU ld cannot prune within it and would keep the
whole translation unit once add_count is referenced, dragging in unresolved
bees-side symbols it also defines (BeesNote, bees_log_emit, bees_log_cat_level,
pretty, BeesFileRange::fid).  With per-function sections --gc-sections keeps
only BeesStats on both toolchains.

Assisted-by: Claude-Code:claude-opus-4-8
Assisted-by: Claude-Code:claude-opus-5
Assisted-by: Claude-Code:claude-opus-5-5
docs/event-counters.md
src/bees-plan.cc
src/bees-plan.h
src/bees-scan-next.cc
test/Makefile

index 1b91fbf197626853b83e710030afd3242d41528e..ba051044eecb5f6c75161c349e656b9aabe0291b 100644 (file)
@@ -305,6 +305,34 @@ 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.
 
+plan
+----
+
+The `plan` event group consists of events within the `scan_next` planner: choosing a rewrite plan for a start extent, the coverage search that builds each plan, and executing the winning plan.  Selection is a ballot over strategy objects (Plan A = start-extent-as-dst, Plan B = start-extent-as-src, and the do-nothing null floor); the lowest space-debt plan wins.
+
+ * `plan_accept_null`: The do-nothing null floor won selection (no real plan beat leaving the start extent untouched).
+ * `plan_accept_start_as_dst`: A Plan A (start extent as the single dst, one-dst-many-src) won selection.  Also counts the forced FullRewrite floor, which is structurally a Plan A.
+ * `plan_accept_start_as_src`: A Plan B (start extent as the src, many-dst-one-src) won selection.
+ * `plan_copy_bytes`: Total bytes copied to a tempfile across executed dst plans (unique data that had to be rewritten rather than deduped).
+ * `plan_cover_exact`: The coverage search ran the exact O(V²) shortest-path DP (boundary-vertex count V within `rewrite.plan-max-vertices`).
+ * `plan_cover_greedy`: The coverage search ran the linear-time greedy fallback because V exceeded `rewrite.plan-max-vertices`.
+ * `plan_cover_none_compressed`: The coverage search produced no plan because a compressed dst had an interior gap no dedupe could cover (copies are forbidden on a compressed dst).
+ * `plan_cover_none_hole`: The coverage search produced no plan because the fixed hole operations alone exceeded `hole-max` or `total-max`.
+ * `plan_cover_none_limit`: The coverage search produced no plan because every covering exceeded the operation limits (all paths pruned during the walk).
+ * `plan_dedupe_bytes`: Total bytes matched (deduped) across executed dst plans.
+ * `plan_dst_executed`: One dst plan was executed (data materialized to a tempfile if needed, then deduped) and its extent handed to the verification tracker.
+ * `plan_empty`: The winning plan had no dst plans, so execution was a no-op (the do-nothing outcome).
+ * `plan_execute`: A non-empty winning plan was executed.
+ * `plan_force_rewrite`: The forced FullRewrite floor won selection for a force-marked start extent (the whole extent is rewritten regardless of dedupe benefit).
+ * `plan_reject_compressed_copy`: A composed plan was rejected because it would copy part of a compressed dst (which fragments compression).
+ * `plan_reject_compressed_dedupe`: A composed plan was rejected because it piled more than `compressed-dedupe-max` dedupe ops onto a compressed dst.
+ * `plan_reject_copy_max`: A composed plan was rejected because its copy operation count exceeded `copy-max`.
+ * `plan_reject_dedupe_max`: A composed plan was rejected because its dedupe operation count exceeded `dedupe-max`.
+ * `plan_reject_hole_max`: A composed plan was rejected because its hole-punch operation count exceeded `hole-max`.
+ * `plan_reject_total_max`: A composed plan was rejected because its total operation count exceeded `total-max`.
+ * `plan_start`: A planner pass over one start extent began.
+ * `plan_worse_than_null`: The winning plan had a space debt above the do-nothing floor — an invariant violation guard; for a non-forced start the null floor should always win in that case.
+
 pread
 -----
 
index cf2141a4d30ebab5c7fbb7ca047fce1d995c11be..9fbd8bcb36310186b8a5827b1bc9851442cf62a6 100644 (file)
@@ -212,7 +212,10 @@ scan_next_plan_greedy(const PlanSearchInputs &in,
                                pos = best_end;
                        } else {
                                // Gap: no match covers pos.  A compressed dst forbids copies.
-                               if (in.m_dst_compressed) return nullopt;
+                               if (in.m_dst_compressed) {
+                                       BEESCOUNT(plan_cover_none_compressed);
+                                       return nullopt;
+                               }
                                uint64_t gap_end = region.m_end;
                                if (mp < by_begin.size()) {
                                        const uint64_t nb = in.m_matches[by_begin[mp]].m_dst_begin;
@@ -230,7 +233,10 @@ scan_next_plan_greedy(const PlanSearchInputs &in,
        // caps are scan_next_rewrite_acceptable's authority, and hole_ops was
        // already bounded by the caller's pre-check.  This only keeps the fallback
        // honest against the total limit.
-       if (dedupe_ops + copy_ops + in.m_hole_ops > policy.m_total_max) return nullopt;
+       if (dedupe_ops + copy_ops + in.m_hole_ops > policy.m_total_max) {
+               BEESCOUNT(plan_cover_none_limit);
+               return nullopt;
+       }
 
        result.m_matched_blocks = matched_blocks;
        result.m_debt = scan_next_covering_debt(in, policy,
@@ -256,6 +262,7 @@ scan_next_plan_shortest_path(const PlanSearchInputs &in,
        // walking anything.
        if (in.m_hole_ops > policy.m_hole_max
            || in.m_hole_ops > policy.m_total_max) {
+               BEESCOUNT(plan_cover_none_hole);
                return nullopt;
        }
 
@@ -266,8 +273,10 @@ scan_next_plan_shortest_path(const PlanSearchInputs &in,
        // UINT64_MAX (rewrite.plan-max-vertices = unlimited) can never be exceeded
        // and disables the fallback.
        if (scan_next_plan_boundary_count(in) > policy.m_plan_max_vertices) {
+               BEESCOUNT(plan_cover_greedy);
                return scan_next_plan_greedy(in, policy);
        }
+       BEESCOUNT(plan_cover_exact);
 
        // Per-edge ref debit shared by every dedupe and copy edge.
        const double K = static_cast<double>(in.m_dst_ref_count)
@@ -673,6 +682,15 @@ scan_next_plan_shortest_path(const PlanSearchInputs &in,
                // a compressed dst with uncovered data has no non-floor path.
                frontier = std::move(at.back());
                if (frontier.empty()) {
+                       // A compressed dst forbids copy edges, so an uncoverable
+                       // interior gap empties the bucket; an uncompressed dst
+                       // always gets a copy edge across a gap, so an empty bucket
+                       // here can only mean every path was pruned over the op limit.
+                       if (in.m_dst_compressed) {
+                               BEESCOUNT(plan_cover_none_compressed);
+                       } else {
+                               BEESCOUNT(plan_cover_none_limit);
+                       }
                        return nullopt;
                }
        }
@@ -694,6 +712,7 @@ scan_next_plan_shortest_path(const PlanSearchInputs &in,
                }
        }
        if (!best) {
+               BEESCOUNT(plan_cover_none_limit);
                return nullopt;
        }
 
index d77a32023b473ff794f99314cf8127ea6866f318..74002402160c1d7403b6cc05be518d99fffd0668 100644 (file)
@@ -322,6 +322,13 @@ public:
        /// whose refs the executor should invalidate post-execution.
        virtual std::list<BeesExtent> srcs() const = 0;
 
+       /// Increment this plan type's acceptance event counter.  The Planner
+       /// calls it exactly once, on the winning plan, after selection — so the
+       /// per-type counters record which strategy won each ballot.  Pure
+       /// virtual so every subclass must name its own counter (a new plan type
+       /// cannot be silently uncounted).
+       virtual void count_accepted() const = 0;
+
        /// Dump plan state for debug logging.  Subclasses extend the
        /// base output — see operator<< below.
        virtual std::ostream &print(std::ostream &os) const;
@@ -385,6 +392,7 @@ public:
 
        std::list<BeesExtent> dsts() const override;
        std::list<BeesExtent> srcs() const override;
+       void count_accepted() const override;
        std::ostream &print(std::ostream &os) const override;
 
        /// Run the deferred shortest-path selection if a candidate has been
@@ -457,6 +465,7 @@ public:
 
        std::list<BeesExtent> dsts() const override;
        std::list<BeesExtent> srcs() const override;
+       void count_accepted() const override;
        std::ostream &print(std::ostream &os) const override;
 
        /// Re-center the dedupe star on the highest-reference whole-extent
@@ -499,5 +508,6 @@ public:
 
        std::list<BeesExtent> dsts() const override { return {}; }
        std::list<BeesExtent> srcs() const override { return {}; }
+       void count_accepted() const override;
        std::ostream &print(std::ostream &os) const override;
 };
index 21cd8849721ab995cfd44a1d67bff32878742245..60273157796dc64fdddf1699b2f35095dfa469ae 100644 (file)
@@ -1298,6 +1298,7 @@ scan_next_reject_reason(BeesExtentLayer *layerp, const PlanCost &cost,
        // only PreCopy (which splits the extent) is forbidden.
        if (cost.m_copy_ops &&
            dst_tree.compress_type(*layerp) != BTRFS_COMPRESS_NONE) {
+               BEESCOUNT(plan_reject_compressed_copy);
                return "compressed dst with copy";
        }
        // Compressed destination rule: a compressed extent can be
@@ -1308,6 +1309,7 @@ scan_next_reject_reason(BeesExtentLayer *layerp, const PlanCost &cost,
        // op, so no general/uncompressed gate is needed.
        if (cost.m_dedupe_ops > policy.m_compressed_dedupe_max &&
            dst_tree.compress_type(*layerp) != BTRFS_COMPRESS_NONE) {
+               BEESCOUNT(plan_reject_compressed_dedupe);
                return "compressed dst with too many dedupes";
        }
        // Respect per-type and total operation limits.  Hole ops
@@ -1316,15 +1318,19 @@ scan_next_reject_reason(BeesExtentLayer *layerp, const PlanCost &cost,
        // the total.
        const auto total_ops = cost.m_dedupe_ops + cost.m_copy_ops + cost.m_hole_ops;
        if (cost.m_dedupe_ops > policy.m_dedupe_max) {
+               BEESCOUNT(plan_reject_dedupe_max);
                return "dedupe_max exceeded";
        }
        if (cost.m_copy_ops > policy.m_copy_max) {
+               BEESCOUNT(plan_reject_copy_max);
                return "copy_max exceeded";
        }
        if (cost.m_hole_ops > policy.m_hole_max) {
+               BEESCOUNT(plan_reject_hole_max);
                return "hole_max exceeded";
        }
        if (total_ops > policy.m_total_max) {
+               BEESCOUNT(plan_reject_total_max);
                return "total_max exceeded";
        }
        return nullptr;
@@ -2319,6 +2325,12 @@ BeesStartAsDstPlan::dsts() const
        return { m_start };
 }
 
+void
+BeesStartAsDstPlan::count_accepted() const
+{
+       BEESCOUNT(plan_accept_start_as_dst);
+}
+
 list<BeesExtent>
 BeesStartAsDstPlan::srcs() const
 {
@@ -2600,6 +2612,12 @@ BeesStartAsSrcPlan::dsts() const
        return rv;
 }
 
+void
+BeesStartAsSrcPlan::count_accepted() const
+{
+       BEESCOUNT(plan_accept_start_as_src);
+}
+
 list<BeesExtent>
 BeesStartAsSrcPlan::srcs() const
 {
@@ -2650,6 +2668,12 @@ BeesNullPlan::process_candidate(
        // Do-nothing consumes nothing and never changes state.
 }
 
+void
+BeesNullPlan::count_accepted() const
+{
+       BEESCOUNT(plan_accept_null);
+}
+
 std::ostream &
 BeesNullPlan::print(std::ostream &os) const
 {
@@ -3759,6 +3783,8 @@ Planner::run(const BtrfsTreeItem &bti,
                   const shared_ptr<BeesPlan> &b) {
                        return a->cost().cheaper_than(b->cost());
                });
+       // Record which plan type won the ballot (Plan A / Plan B / do-nothing).
+       (*winner_it)->count_accepted();
        plan = scan_next_build_extent_plan(m_ctx, **winner_it,
                *m_filter_cache, m_rewrite_policy);
 
index be7d04d801b8cb76ebdb242e65b6defe1276e061..0ad0781e1309204fd76984ec6fb07bbb7f1c0802 100644 (file)
@@ -176,8 +176,22 @@ test-bees-plan-lib.dep: ../src/bees-plan.cc ../makeflags Makefile
        $(CXX) $(BEES_CXXFLAGS) -I../src -M -MF $@ -MT test-bees-plan-lib.o $<
 -include test-bees-plan-lib.dep
 
-test-bees-plan: test-bees-plan.o test-bees-plan-lib.o ../makeflags Makefile ../lib/libcrucible.a
-       $(CXX) $(BEES_CXXFLAGS) $(SECTION_FLAGS) $(BEES_LDFLAGS) -Wl,--gc-sections -o $@ test-bees-plan.o test-bees-plan-lib.o $(LIBS)
+# test-bees-plan-lib.o (../src/bees-plan.cc) now emits BEESCOUNT event counters,
+# which reference BeesStats::s_global / add_count defined in bees-util.cc.  Link
+# a test-local, --ffunction-sections rebuild of bees-util.cc (not ../src/bees-util.o)
+# so --gc-sections can drop the rest of the TU: the stock ../src/bees-util.o is
+# built without function-sections, so GNU ld (unlike clang's) cannot prune within
+# it and pulls in unresolved bees-side deps (BeesNote, bees_log_emit, pretty,
+# BeesFileRange::fid) — breaking the gcc build.  The sectioned rebuild keeps only
+# BeesStats on both toolchains.  Mirrors test-bees-plan-lib.o's header-dep rule.
+test-bees-util-lib.o: ../src/bees-util.cc ../makeflags Makefile
+       $(CXX) $(BEES_CXXFLAGS) -I../src $(SECTION_FLAGS) -o $@ -c $<
+test-bees-util-lib.dep: ../src/bees-util.cc ../makeflags Makefile
+       $(CXX) $(BEES_CXXFLAGS) -I../src -M -MF $@ -MT test-bees-util-lib.o $<
+-include test-bees-util-lib.dep
+
+test-bees-plan: test-bees-plan.o test-bees-plan-lib.o test-bees-util-lib.o ../makeflags Makefile ../lib/libcrucible.a
+       $(CXX) $(BEES_CXXFLAGS) $(SECTION_FLAGS) $(BEES_LDFLAGS) -Wl,--gc-sections -o $@ test-bees-plan.o test-bees-plan-lib.o test-bees-util-lib.o $(LIBS)
 
 # bench-bees-plan is a manual scaling/timing harness for the shortest-path
 # coverage search (not a pass/fail test, so deliberately NOT in PROGRAMS and
@@ -202,4 +216,5 @@ $(REPL_TESTS): %: %.o $(REPL_OBJS) ../makeflags Makefile ../lib/libcrucible.a
 clean:
        rm -fv $(PROGRAMS:%=%.o) $(PROGRAMS:%=%.txt) $(PROGRAMS) \
                test-bees-plan-lib.o test-bees-plan-lib.dep \
+               test-bees-util-lib.o test-bees-util-lib.dep \
                bench-bees-plan.o bench-bees-plan bench-bees-plan.dep