Skip to content

feat(otel): session tree depth and child counters + root-count gauge (#21273) - #21308

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/21273-otel-session-tree
Oct 20, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/21273-otel-session-tree

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record how deep delegated session trees get, and how many trees actually branch, and export both to OpenTelemetry -- off the append path and behind the existing telemetry consent gate.

Maintainers cannot say how deep delegated session trees run or how many roots have children. The crew log records who created whom (session/opened.parent), but nothing turns that into a shape a maintainer can read. This is the session-tree story on the crew-log OTel epic (#21270), built on the export skeleton from #21272.

Builds on #21342 (the OTel export skeleton), which is now merged into main. This branch is rebased onto main, so the diff contains only the session-tree change below.

Why it matters

Delegation depth and branching are the clearest signal of how much work is actually delegated in practice -- the question the whole crew-log-to-OTel effort exists to answer a module at a time. Without it, the maintainers tuning subagent concurrency, staleness windows and dispatch policy are guessing at the shape of what they tune. The metrics are distribution-only: a depth histogram and a root count across an install, never a per-person timeline.

Not a goal

  • Not the work-ledger, crewmate, or dashboard metrics -- those are later stories on this epic.
  • Not any per-person or per-session detail: both metrics are attribute-free aggregates.
  • Not a change to what the append path costs beyond one depth field whose value is already known when session/opened is written.

What changed (motivation -> approach -> change)

Goal: get the two measurements out without a join and without slowing the append path.

Approach: record depth at write time, and read branching from the folded tree at collect time. session/opened gains a depth field -- how many creators stand above a session -- resolved by the caller from the in-memory tree and passed in, never derived on the writer thread. A session-keyed counting fold (otel_session_tree) renders this session's own depth; the export skeleton's subscriber turns it into one counter add per session, labelled by depth bucket. The same fold counts the session/spawned entries on a creator's own log, which gives each child its ordinal among its creator's children without walking any parent link. The root count is a property of the whole tree, so it is an observable gauge read on the SDK's collect thread (register_session_tree_gauge in provider.py, the same meter.create_observable_gauge path the inventory and process gauges take), counting depth-0 sessions that have children off the folded tree.

Change:

  • kirocrew.crew.session.tree.depth (counter, attr depth in 0 / 1 / 2 / 3+): one add per opened session carrying a depth. A counter per bucket label rather than a histogram, so the distribution survives backends that do not keep explicit histogram buckets. Entries written before this change carry no depth and contribute no add.
  • kirocrew.crew.session.tree.child (counter, attrs parent_kind and nth): one add per child session a creator makes. parent_kind is the creator session's closed agent_kind; nth is the child's ordinal among its creator's children, in 1 / 2 / 3 / 4-7 / 8+. Creators with at least k children is the sum of the adds at nth >= k, so the width distribution is read without waiting for a creator to end. The fold keeps one more integer (the child count) and the creator's closed kind; no child identity, raw agent name or slot is stored. Same never-over-count rule: a creator this process cannot prove is new is baselined on first sight, and because the count resumes from the savepoint, its next child is still counted at its true ordinal.
  • kirocrew.crew.session.tree.roots (observable gauge, no attribute): the current count of depth-0 sessions with children. A gauge, not a counter, because the quantity rises and falls (a forgotten child drops a root) and is read off the folded tree.
  • session/opened.depth (declared JSON_INT): birth depth, absent when not establishable, never inferred. slot_depth walks the folded tree to resolve a child's; root_depth answers a root's.
  • docs/system-specs/modules/metrics.md gains a row per new instrument in its Instrumented signals table.
  • metrics/provider.py registers the roots gauge. Touching it meant the file had to pass black, so the whole file is black-reformatted (formatting only, no behaviour change) and its row is dropped from .github/black-baseline.txt.

Depth is censored on both sides, never just one

A depth is only written against a tree that can place sessions: seeded for the store being read, and a reading not reported incomplete. incomplete holds when the projection is unseeded, when a unit's bytes faulted, or when the population passed TREE_UNIT_CAP.

How common is that, honestly. An earlier draft of this section called the over-cap case the permanent state of a busy install, and that overstated it against the cap's own declaration: session_tree.py says 4096 admitted units is far above any real population because retention keeps the store far smaller, and that a store reaching it usually has retention disabled. So over-cap is the rare arm. The arms that are not rare are the other two -- an unseeded projection (every reader before the first seed completes) and a faulted unit -- and they produce exactly the same missing edges. The censoring is therefore a correctness guard for a reading that cannot place a child, not a resignation about busy installs, and it is worth having whichever arm fires.

What the censoring deliberately does NOT do is report its own extent. A maintainer reading thin depth counts cannot currently tell "few sessions" from "the tree could not be read", and a censored-opens counter beside them is the obvious way to close that. It is a new instrument rather than a fix to this one, so it is noted for the epic rather than added here.

A child's depth already refused in that state, because it needs the walk. A root's did not -- zero needs no walk, so it was written unconditionally. That combination is the one way this field can bias its own distribution: on exactly the installs with the most delegation, every child would be withheld and every root still recorded, so the depth counter would report almost all sessions at depth 0 while the roots gauge reported nothing. The answer to "how deep does delegation go" would come back backwards, with no second metric showing the gap.

So both sides now go through one readable-tree check (session_tree_projection._depth_readable_nodes, used by slot_depth and by the new root_depth). A tree the fold cannot read produces no observation at all rather than a root-only distribution, which is the honest reading of "absent, never inferred": a session left out of a distribution, not an invented tree.

Bucket labels

The depth labels (0 / 1 / 2 / 3+) and the nth labels (1 / 2 / 3 / 4-7 / 8+) are closed sets, so neither attribute's cardinality grows with the deepest or widest tree. 0 is its own label, so "no delegation" and "one level" never share a bucket.

Backwards compatibility

This PR adds a new fold, a new field, and three metrics; reads only already-declared entry types and changes no existing record, validator or public function. An entry written before this change simply carries no depth and contributes no depth add. The fold-catalogue and dashboard_types additions only add; they hide and remove nothing.

Tests

  • The depth field: stored when valid, absent when unresolved, refused for a bool/negative, the entry still validates, an old (no-depth) entry replays with no observation.
  • slot_depth, root_depth and count_roots_with_children: driven over roots, chains, citations and cycles. root_depth answers 0 on a readable tree and None when the projection is unseeded or its seed faulted; an over-cap tree withholds a child's depth AND the root's, so it cannot produce a root-only distribution. The writer-side resolver (_crew_log_tree_depth) is driven over both.
  • The depth diff emits one bucketed add per new session (silent on null/redelivery/malformed/resumed); the child diff emits one add per child at its ordinal bucket, splits a jump across buckets with arithmetic, attributes by the creator's closed kind (other outside the set), baselines a resumed creator and then counts its next child at its true ordinal, and a real crew log + eager worker + bus path drives three session/spawned entries to nth 1, 2, 3; the roots read folds each collect, reports None (no observation) when unseeded/incomplete, a real 0 for a seeded empty tree, and never raises into collect; its bus-free callback is proven; the gauge registers through provider.py.
  • The entry-types golden table + render digest, the fold catalogue (FOLDS.md/folds.json), and the dashboard_types nullable-driver were regenerated for the new field and fold.

Manual verification

N/A -- unit coverage exercises the real fold, the real tree projection, and the gauge callback; there is no UI or external service in this change.

Related Issues

Part of #21270.
Closes #21273.

Builds on #21342 (the OTel export skeleton, merged); the boot-time install helper (_kick_otel_crew_log_subscriber) lives there. Not for merge until the design in #21271 is agreed and the data scope is confirmed.

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 16, 2026 16:40
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 16, 2026
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 936555851d79c34883e10bc19dafb94a6971447c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 936555851d79c34883e10bc19dafb94a6971447c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the session-tree projection is seeded before the first turns after boot. Until it is, depths are silently left out with no counter showing the gap.

[DESIGN-REVIEWED] 9365558

Description read

[DESCRIPTION-READ] a7c9ac6a3c5feb6f765744e3677e45c73160cfa9565590ec89aa12bb042d6f04

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 936555851d79c34883e10bc19dafb94a6971447c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The Goal asks for two measurements, but the PR ships three instruments: the per-ordinal tree.child counter goes beyond it, and depth is persisted to the log when the in-memory tree already holds it.

Not justified as shipped

  • Item 3 — oversized: the Goal is "how deep … and how many trees actually branch … export both". The roots gauge (item 4) already answers branching. tree.child adds session/spawned counting, children/agent_kind fold state and the nth/parent_kind buckets, and none of that is in the Goal.
    Subtraction: delete SESSION_TREE_CHILD_METRIC, nth_bucket_counts, NTH_BUCKETS, the session/spawned arm of _otel_session_tree_step, the children/agent_kind state, and _child_total, which duplicates _tree_count byte-for-byte.
    Clears when: the mechanism is removed, or a human amends the Goal.
  • Item 2 — inherited: the PR adds a permanent append-only field because "a fold that derived depth instead would have to join". It never considers reading depth at collect time from the tree slot_depth already walks, which is how the roots gauge works.
    Subtraction: drop the session/opened.depth field, _crew_log_tree_depth, root_depth and the two writer arguments. Derive depth from reading.nodes in the same collect callback.
    Clears when: a stated reason, with evidence, why an opens-rate counter needs a persisted field instead of a tree read.

What this change ships

Inventory (7 items) — 4 justified

Intent: let maintainers see how deep delegated session trees go and how many branch, via OTel behind consent — ADDITION.

  1. New session.tree.depth counter bucketed 0/1/2/3+ — justified
  2. New persisted depth key on every session/opened entry — oversized; write-time field where a collect-time tree read exists
  3. New session.tree.child counter by parent_kind × nth — oversized; beyond the two-measurement Goal
  4. New session.tree.roots gauge read at collect time — justified
  5. New internal otel_session_tree fold in the catalogue/folds.json — justified
  6. Both opener paths (dashboard, channel) now state depth — justified
  7. provider.py black-reformatted and dropped from the baseline — rides along

[FIRST-PRINCIPLES-REVIEWED] 9365558

Description read

[DESCRIPTION-READ] 89aef110c262259ebfe8813fdc59d795278504bbfb47855b6002ec30722c9dbd

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 936555851d79c34883e10bc19dafb94a6971447c — this comment is updated in place on each push.

Review details

No findings. Nothing here blocks the merge; one advisory finding remains.

FINDING — src/kiro_crew/messaging/dispatch_crew_log.py:235 — depth=crew_log_tree.root_depth() returns None whenever the session-tree projection is unseeded. Only a dashboard slots frame (slots_frame._request_lineage_seed), the dashboard memory sampler, or a turn on a slot with _created_by (_crew_log_seed_tree) seeds it. So on a gateway serving only messaging channels with no dashboard tab open, every channel root's session/opened is written without depth, permanently, while children (which seed before their turn) still get one. That leaves roots out of kirocrew.crew.session.tree.depth and skews the distribution toward children, which is the one-sided censoring this code says it prevents → Fix: kick the same off-loop seed (ensure_seeded on the maintenance pool) from open_turn_crew_log before reading root_depth(), or seed the projection when the OTel subscriber is installed. (origin: validation)

[OPUS-REVIEWED] 9365558

Verdict parsed from the review's SHA-scoped output markers for commit 936555851d79c34883e10bc19dafb94a6971447c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 936555851d79c34883e10bc19dafb94a6971447c: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 936555851d79c34883e10bc19dafb94a6971447c and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/crew_log/otel_session_tree_fold.py:32 -- Summing adds at nth >= k reports three creators for one creator with three children at k=1 -> Fix: correct this formula here, in the exporter comment, and in the metrics spec: exact nth=k counts creators reaching k for k=1..3; grouped buckets cannot recover exact creator thresholds.
[GPT-REVIEWED] 9365558

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 936555851d79c34883e10bc19dafb94a6971447c: <one-sentence reason>

@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch from 2de446e to fef1f8a Compare October 16, 2026 16:56
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch from fef1f8a to 0a02558 Compare October 16, 2026 17:04
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch from 0a02558 to f625224 Compare October 16, 2026 17:48
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Thanks for the first-principles pass. Addressed on head f625224650:

Item 6 (dirty-flag cache) -- accepted, removed. otel_session_tree_roots no longer keeps _dirty, _cached_count, _lock, or a TREE_ADVANCED subscription. read_roots_with_children() folds the tree once on the SDK's own collection thread each cycle. The tree is bounded by TREE_UNIT_CAP (4096) and the read is already off the writer thread, so there was no measured cost to cache against.

Item 7 (second gauge-registration path) -- accepted, removed. The roots gauge is now registered through one meter.create_observable_gauge call, via register_session_tree_gauge(meter) invoked from provider.py right beside register_inventory_gauges / register_process_gauges -- the same path every other gauge takes. The code stays in its own crew-log module (otel_session_tree_roots.py) because its source is crew_log's session-tree projection, not the install inventory, but the registration path is the shared one. The separate observable channel is gone.

Item 4 (the depth field) -- kept, and here is why it is not derivable at collect. The field records depth AS THE SESSION WAS OPENED -- its birth depth. The collect-time tree read gives CURRENT depth, which is a different quantity once a session is adopted or released (those move a session in the tree). The depth histogram wants one observation per opened session at its birth depth, which only a write-time field captures; a collect-time read would re-measure every live session's current depth on every collect, which is a different metric. This also matches the issue's own "Done when: session/opened carries depth". The field note already states the join-vs-read distinction; the roots gauge reading the tree at collect is a different question (current branching, not birth depth), so there is no contradiction.

Items 8 and 10 -- not this change. Those belong to the export-skeleton commits from #21272 (the slot-scope loop, the on_session_fold alias, the eager.py docstring). #21272's latest commit already dropped the dead multi-scope plumbing and the observable channel; this PR is stacked on it, so those lines leave my attribution once #21272 merges.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch 2 times, most recently from 6af4019 to aa8e99f Compare October 16, 2026 18:11
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch from aa8e99f to 0ca9402 Compare October 16, 2026 18:36
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 16, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch 2 times, most recently from 725ca61 to d799b6f Compare October 16, 2026 18:45
@chenmingwei23
chenmingwei23 force-pushed the feat/21273-otel-session-tree branch from 9e2f2e6 to e4f5f82 Compare October 17, 2026 14:30
@github-actions

Copy link
Copy Markdown
Contributor

AI-review override not recorded: e4f5f82083ba2bff5e2f86e19d0a6cd5bb06a9d1 is not the current PR head. Re-run the command with e4f5f82083916413511b17d5698d64e44d2772af.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles e4f5f82: The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for e4f5f82083916413511b17d5698d64e44d2772af.

The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at e4f5f82. The branch conflicts with main and needs a rebase. It also stacks on #21342, which waits on the maintainer agreement on design and data scope that #21271 requires (RFC #21288 is still a draft). Before the next review, please also:

  • answer the three Opus advisories on this head. Each is prose that contradicts the code: the bucket comment (crew_log_export.py L405), the fold docstring (projection_otel_session_tree.py L29), and 'at or after export install' (L358);
  • reply to the Design punchline about depth being withheld during the unseeded boot window;
  • open and link an issue for the deferred creator.depth + 1 follow-up.
    I will re-review the rebased head; this does not approve it in advance. — crew-pr-reviewer (r109)

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 4c1b678: The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 4c1b6781dcab57ccd8c1ea216abb112ab1dabe68.

The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

This decision applies only to this commit. A new push requires a new judgment.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 0b4cbc2: The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 0b4cbc24a28077a145356f9f7276b45cf9f6197f.

The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

This decision applies only to this commit. A new push requires a new judgment.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles c834de5: The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for c834de5df91cdd1219f3979bef594b9241fd6978.

The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

This decision applies only to this commit. A new push requires a new judgment.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles ac74b08: The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for ac74b087cb04f2357eb56b65c0931d851b0566c4.

The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

This decision applies only to this commit. A new push requires a new judgment.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles ce06ecf: The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for ce06ecfb47e2b6e054cf786ab87e9bbc8b4779f8.

The crew log is the declared source for session-tree telemetry (design #21271); emitting from the write path would add work to the append path and lose the restart baseline. The write-path change is one integer field known at session creation; all aggregation stays in the fold.

This decision applies only to this commit. A new push requires a new judgment.

buluoray
buluoray previously approved these changes Oct 19, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve the code at ce06ecf. Merge only after #21342 lands and the #22180 / #21271 design is agreed.

Both r108 items are fixed. A root depth now goes through the same readable-tree check as a child depth (_depth_readable_nodes and root_depth, session_tree_projection.py L2131 and L2175), and both writers use it (crew_log_attribution.py L282, dispatch_crew_log.py L235). The over-cap test is there. Labels are bounded: depth is 0, 1, 2 or 3+, nth is 1, 2, 3, 4-7 or 8+, and parent_kind goes through the closed agent_kind check. The roots gauge is recalculated from the folded tree on every collect, keeps no running state, and reports nothing when the tree is unseeded or incomplete. Mutating any of these bounds fails a named test.

Follow-ups, not blocking:

  1. The GPT point is right: the sum of adds at nth >= k counts creators only for the single-value buckets, so please fix that sentence in the fold docstring, the exporter and metrics.md.
  2. The subscriber is installed only in start_dashboard, so an API-only gateway emits the roots gauge but no depth, child or usage counters.
  3. The comment at crew_log_export.py L648 says at or after install, but the code uses strictly greater than.
  4. Please open and link the issue for the creator.depth + 1 follow-up that r109 asked for.
  5. The Design scope concern and the provider.py black reformat need a disposition.

CI is green, and the related tests pass locally (455).

@chenmingwei23

chenmingwei23 commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor Author

Rebased onto the new #21342 head a29f54000c. New head 4239a3a117.

_kick_otel_crew_log_subscriber and its composition-contract entries moved into #21342, so this PR no longer adds them; it keeps only the wording change to the install comment for the second fold. The session-tree diff and its tests now build Metric without an instrument kind, following #21342 dropping that field. Restart exact-once counting for these counters is tracked in #22297.

@chenmingwei23

chenmingwei23 commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor Author

New head: c97f4ad. Still stacked on the #21342 commit, unchanged. Since the last head: removed the unused session-tree row counter, the second SESSION_OPENED_TYPE constant (now imported from projection_otel_usage, and the facade is back to excluded=()) and the _read_for_tests helper. The description now says what the #21342 part of the diff contains, and declares the provider.py black reformat. The raising-subscriber test still skips the bus.subscriber_error counter, which depends on test order.

buluoray
buluoray previously approved these changes Oct 20, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve the code at c97f4ad. Merge only after #21342 lands, this PR is rebased onto it, and the #21271 design is agreed.

The install helper is no longer duplicated: its one definition is server_runtime/maintenance.py L392, and this PR only rewords the comment beside the call in server.py. The tree depth and width code is unchanged in substance since my earlier approve; the related tests passed locally on 105416d (453), and this push only removes code.

First Principles items 8 to 10 are gone on this head: _otel_session_tree_rows and its count_rows entry, the second SESSION_OPENED_TYPE and its excluded entry, and the test-only _read_for_tests.

Before merge:

  1. This head is still stacked on 7ded32a, not on the current #21342 head 95c52b9. Those two differ only in test_a_raising_subscriber_does_not_silence_this_one, which this PR also edits in a different way, so the rebase will conflict there. Please rebase onto 95c52b9 and keep one fix for that test.
  2. The First Principles blocker (the diff against main carries all of #21342) clears once #21342 merges and this PR is rebased; until then it needs an override that names the stack.

Follow-ups still open from my earlier approve:

  1. The sentence that creators with at least k children equals the sum of adds at nth >= k is still wrong (otel_session_tree_fold.py L32-L33, crew_log_export.py L222, metrics.md L451, and the description). That sum counts children at ordinal k or higher. For k of 1, 2 and 3 the adds at nth equal to k give the creators with at least k children; the 4-7 and 8+ buckets cannot give that.
  2. The subscriber is installed only in start_dashboard, so an API-only gateway exports the roots gauge but no depth or child counters.
  3. Please open and link an issue for the creator.depth + 1 follow-up.
  4. The provider.py black reformat (and the black-baseline row it drops) still has no disposition in the description.
  5. A leftover fragment, ONE ROW PER FOLD -- a later story, still sits at crew_log_export.py L393.

…21273)

Record session-tree depth on session/opened and export three OTel
metrics from the crew log, all riding the crew-log export skeleton.

session/opened gains a depth field: how many creators stand above a
session in the session tree, resolved by the caller from the in-memory
tree and passed in, never derived on the writer thread. depth is a
declared JSON_INT; absent means not established, never zero; 0 is
written only when the caller knows the session has no creator (a
channel conversation). slot_depth walks the folded tree to resolve it,
returning None on every unresolvable case (unseeded, wrong store,
incomplete, missing node, cycle, unplaceable ancestor).

kirocrew.crew.session.tree.depth (counter, attr depth in 0 / 1 / 2 /
3+): a SESSION-keyed counting fold (otel_session_tree) renders this
session's own depth, and one add is recorded per session this process
can prove is new. A counter per bucket label rather than a histogram,
so the distribution survives backends that do not keep explicit
histogram buckets. Entries written before this change carry no depth
and contribute no add.

kirocrew.crew.session.tree.child (counter, attrs parent_kind and nth):
one add per child session a creator makes. parent_kind is the creator
session's closed agent_kind; nth is the child's ordinal among its
creator's children, in 1 / 2 / 3 / 4-7 / 8+. Creators with at least k
children is the sum of the adds at nth >= k, so the width distribution
is read without waiting for a creator to end. The ordinal comes from
the creator's own log: session/spawned is written there once per child
at creation time, so the same fold adds one per entry and keeps one
more integer plus the creator's closed kind (folded in step with the
classifier otel_usage uses). No child identity, raw agent name or slot
is stored and no parent link is walked. A creator this process cannot
prove is new is baselined on first sight; the count resumes from the
savepoint, so its next child is still counted at its true ordinal.

kirocrew.crew.session.tree.roots (observable GAUGE, no attribute): the
count of depth-0 sessions with children is a level of the whole tree
that rises and falls, so it is a gauge, not a counter. The O(n) count
over the folded tree runs on the OTel SDK collect thread, bounded by
TREE_UNIT_CAP.

All are gated by telemetry.enabled (default false); no attribute
carries a session id, name or path.

Registered in the fold catalogue (INTERNAL_PROJECTION_NAMES, _FOLDS,
the generated FOLDS.md/folds.json, a nullable depth leaf) and in the
export's _EXPORTERS table and the provider's gauge registration. The
entry-types golden table and render digest are regenerated for the new
field.

Part of #21270.
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto main now that #21342 is merged. The branch carries only this PR's own commit; new head 9365558. No code change beyond dropping a test-flake fix that main already has in the same form.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OTel: session tree depth and root counts

3 participants