Repository navigation
feat(tracing): session lifecycle spans: open, close, reset, compaction, switch, adopt (6, #1643) - #36830
feat(tracing): session lifecycle spans: open, close, reset, compaction, switch, adopt (6, #1643)#36830kyleseaman wants to merge 2 commits into
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns. Every hook returns at its first line while tracing is off and swallows its own errors, nothing is taken away, and no user-visible surface changes, so no screenshot is needed. Notes
[DESIGN-REVIEWED] ca28bed Description read[DESCRIPTION-READ] 5e1e3c50223706baadf13f759ae6346f42736c6b909794acc794f55fe4a4bd77 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Phase 6 of the tracing RFC is accepted and listed as What this change shipsInventory (9 items) — 8 justifiedIntent: let an operator see a session's opens, compactions, switches, adoptions and its close or reset in a trace backend, beside its turn traces. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] ca28bed Description read[DESCRIPTION-READ] 931c38ed6df18113670f46b8f742fecbc93b63ba8ce938de82af0ce8f6dc76db That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 14% chance that this change introduces a defect, above the 12% limit for approving on its own. This PR adds session lifecycle spans (open, close, reset, compaction, switch, adopt) by hooking existing funnels. Tracing is off by default. Every hook returns early or swallows its own errors, and the always-evaluated arguments ( Tier: 3, held for a person: merge conflict. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
ad007d0 to
61aca79
Compare
|
|
|
|
61aca79 to
7734c16
Compare
7734c16 to
4f8b53b
Compare
|
Rebased: main moved in src/kiro_crew/tracing/correlation.py, src/kiro_crew/dashboard/trace_binding.py, test/tracing/test_tracing_ids_attrs.py and docs/system-specs/modules/metrics.md (#36833, OTel phase 5), which left this PR CONFLICTING (7734c16 on ac4062d -> 4f8b53b on c275f70). Conflicts resolved by keeping both sides; CI re-running. |
…n, switch, adopt (6, #1643) Review fixes on the rebase: session state kept from before tracing was last switched off is dropped (provider.off_epoch), and a fork's parent key is folded through registry_key before note_lineage.
4f8b53b to
5f062e0
Compare
|
Hi @kyleseaman, this is part of a cleanup of older open PRs. I rebased this on main and pushed 5f062e0 (one commit, your authorship kept). It folds in fixes for the two upheld findings on 4f8b53b:
Two new tests cover these. They fail on the old code, and Opus now has no findings. GPT raised a new finding in the same place, so I am stopping here and leaving the next step to you. After a toggle, Also, |
|
Thanks @iamwhatever for the rebase, and for the
|
cff02b2 to
76b19c3
Compare
…tches A generation recorded again after tracing is switched off and on, the unknown fallback or a real one rebuilt by a reset, restarted its event counters at 1 under the same trace, so two compactions, switches or adopts could export the same trace and span id. The repeatable events' counter now carries the generation's off epoch; epoch 0 is unchanged. provider.reset_for_testing() also resets the off epoch, so the per-test id assertions do not depend on which tests ran first. _reset_slot_session_or_warn recorded kirocrew.session.switch as soon as the reset landed, before its callers could still roll the switch back. The model, effort and workspace handlers roll back only at their rebind guard, the next statement, so the helper records only while the slot still resolves to the session it reset. The agent switch can also roll back after that (the metadata write's 503, the second rebind guard, the owner checks), so it asks the helper not to record and records the span itself once past its last rollback point. Also black-formats test/tracing/test_tracing_sessions.py.
76b19c3 to
ca28bed
Compare
Problem / Motivation
Goal: With tracing on, each live session's lifecycle (opened, compacted between turns, switched, adopted, closed or reset) shows up as a short trace that sits beside its turn traces under the same
session.id, and a worker, fork or linked session names its parent.Today only model turns have spans. Nothing records when a session opened, when Crew compacted it between turns, when its agent, conductor or model was switched, or why it ended. A worker session's traces do not say which session created it.
Why it matters
The tracing RFC's phase 6 (§10) and Kyle's "track all the steps/sessions/turns" both need the session itself on the timeline. An operator debugging a slow or costly chat cannot tell from turn traces alone that the session was recycled after a compaction, reset by a model switch, or moved onto a new conductor, and cannot find a worker's parent session.
Not a goal
kirocrew.compactionstep span)./compactslash command or the in-turn model fallback swap.What changed (motivation → approach → change)
With tracing on, a trace backend now shows each session's opens, between-turn compactions, switches, adoptions and its close or reset as a short trace under the session's own
session.id, beside its turn traces.Design record: the native tracing RFC §5.8 (session lifecycle row) and §10 row 6.
Approach: hook the few funnels every surface already passes, so one small module covers them all. A generation is one stay of a session key in the session registry, from
record_session_startedto its end record; it gets one trace.kirocrew.session.open(root)metrics/sessions.py::record_session_started, every surfacekirocrew.session.close/.resetrecord_session_endedandrecord_sessions_ended, with the end reasonkirocrew.session.compactionsession_parts/turn_context.py::_compact_session, the funnel of both automatic triggers, with the coordinator's answerkirocrew.session.switchchat_api/slot_guards.py::_reset_slot_session_or_warnonce a switch's reset lands, plus a live model switch inslot_model.py;conductorwhen the Crew Mode migration switches a root (agent_switch.py)kirocrew.session.adoptsession_tree.pyandsession_handoff.pyonce their tree edge landstracing/sessions.py. Every span carries the samesession.idandkirocrew.session_key_hashas the session's turns, so an ACP recycle keeps one session. Children parent to the open span by id, as run anchors do.H(trace.session, session_key, generation), spanH(session.<event>, session_key, generation, n). The generation is the registry start time in microseconds, so a session resumed after a restart (same ACP session id) gets a new trace instead of reusing span ids. Two conformance vectors are added.trace_binding.py::note_slot_lineagenotes the parent before either dashboard allocation can register a session, the first turn's claim (turn_admission.py) and the eager spawn's prefetch (eager_spawn.py): a creator only when this process minted the lineage, thenforked_from, then the dashboard slot a channel session is linked to. Lineage stamps and the session tree name bare slot keys, soslot_session_keymaps them to the registry key a session is traced under. The open span carries the hashed parent key andkirocrew.session.relation, and links to the parent's open span when it is live in this process.set_modelRPC, and under the key the registry folds onto (trace_binding.py::registry_key), so a successor registered mid-teardown keeps its own trace and an alias key still finds the session. A live switch records only once its caller's rebind check passes. The ACP session id is kept only within the sharedbounded_session_idlimit.kirocrew.session.*. No titles, prompts or message text; session keys are hashed.Rejected: hooking the crew-log emitters (they only run with the crew log on, and are keyed by ACP session id), and keying ids on the ACP session id as the RFC table sketched (a resume after restart would reuse every span id).
Backwards compatibility
Compatible: tracing is off by default, and off every hook returns at its first check. The only behaviour change outside tracing is the log text of a failed teardown during a Crew Mode migration switch, which now says
conductor switchinstead ofagent switch.Removes nothing: the diff adds spans, five allowlisted attributes and two conformance vectors.
Tests
test/tracing/test_tracing_sessions.py(new, 25 tests):session.idacross an ACP recycle, and each generation is its own trace with open, compaction, switch, close, then open, reset._spawn_admitted_prefetch) has noted a worker's creator when its allocation runs.MAX_ACP_SESSION_ID_LENis not retained or put on a span.other; an unknown switch kind is dropped.record_session_started/record_session_ended/record_sessions_endeddrive open, close and reset.test_the_attribute_allowlist_is_pinnedgains the five keys; the conformance fixture gains two vectors. The tests use no sleeps; the metrics-record test pinsmetrics/sessions.py's own clock binding to distinct readings.Determinism: the file passed repeated runs, a run in reversed test order, and a run under
-n 4, each 25/25. The prefetch, switch-generation, live-switch, folded-key and id-bound tests each fail on the production code without their fix.Manual verification
N/A for manual steps: the tests drive the real metrics records, compaction funnel and switch funnel with an in-memory exporter; no UI changes.
Related Issues
Part of #1643 (phase 6).
Overlap with #37088
#37088 adds a
kirocrew.session.parent_changespan in the acting turn's trace. This PR'skirocrew.session.adoptspan sits in the adopted session's own lifecycle trace. So one adoption gives one span in each trace, by design: the turn that made the change shows it, and so does the session it changed.Merge order: #37088 first. This PR then rebases onto it once the re-sync reset comment lands.
Checklist