Repository navigation
feat(tracing): kirocrew trace show prints one turn as a waterfall from the local span files - #37537
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: it adds a read-only CLI reader for span files that are already written, takes nothing away, and changes no UI. Notes
[DESIGN-REVIEWED] ff77066 Description read[DESCRIPTION-READ] e202964155e3e7ce2d771bd5968105afc3d5df500d0977c3e440e7589b898769 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 Nothing to check. What this change shipsInventory (8 items) — 8 justifiedIntent: a developer can read one traced turn's timing locally, with no collector. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] ff77066 Description read[DESCRIPTION-READ] 52f5c886478faee89e999c65cb52621e773c21bc03e432ee5c7fa30ba19a26e1 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings. Notes:
[OPUS-REVIEWED] ff77066 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. Adds a read-only 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 |
7d40432 to
f6f51e3
Compare
|
Rebased onto 2e56b3b as f6f51e3 with no change to this PR's code. The failures in backend shard 6 (Linux and Windows) were |
…m the local span files
f6f51e3 to
ff77066
Compare
|
Row cap under-reports what was cut (Opus, blocking, Design lane (PASS, note). The handler First-principles lane (PASS). Its remark is that nothing else reads the span files yet. That is the reason for the PR: GPT lane. No findings. |
|
This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/). This PR is part of the tracing work in #1643, which waits on a maintainer decision. The new top-level Review result on ff77066: no blocking findings. The parser matches what JsonlSpanExporter writes. Shards are picked with the exporter's own Optional:
|
bolichen97
left a comment
There was a problem hiding this comment.
Approve (no auto; the author holds it).
kirocrew trace show <key> is a new, read-only CLI command that prints one trace from the local span files as a waterfall.
What I checked:
- Read-only: it lists and reads
traces/spans-*.jsonlthrough the existingsafe_read_fileand writes nothing (tested by comparing size and mtime before and after). No gateway, no SDK. - Output: only the span name, timing and
error.type; every name goes throughsafe_terminal_line. A non-hex trace or span id is not a span, so it never reaches the terminal. Tests cover control sequences and an attribute that must stay out. - Bounds: shard size, line length, span count, rows and depth are all capped, and a line nested past the JSON parser's limit is skipped like any bad line. The tree walk uses an explicit stack, so a deep trace cannot recurse.
- Errors: an unreadable shard or folder stops with the file name and the exception class only, never a full path; a missing folder reads as "nothing matched".
- No new refusal: it is a new command, nothing on main changes. The shard filter reuses the existing
shard_name_refrommetrics/local_exporter.py; no new regex in product code.
I read the whole diff on ff77066, including the 286-line test file.
Not checked: I did not run it locally against a real span folder.
Problem / Motivation
Goal: a developer can read one traced turn, its model calls, tool calls, sub-agents and the waits between them, without a collector.
With
telemetry.traces_enabledon, every turn already writes spans to<data home>/traces/spans-YYYY-MM-DD-<pid>.jsonl(tracing/exporter.py). Nothing in Kiro Crew reads those files back. To see why one turn took 40 seconds, a developer has to set up an OTLP backend or read raw JSON lines, where parent links, times and ids are spread over hundreds of records and sorted by finish time.Why it matters
The local files are the only trace output that needs no account, no network and no extra install. They are also the first thing someone checks when a turn feels slow or stuck. Without a reader they can only be inspected by hand.
Not a goal
What changed (motivation → approach → change)
Symptom → cause: spans are written and never read.
src/kiro_crew/tracing/render.py(new): reads the shards, picks the most recent trace holding the key, and prints it as an indented tree. Each row has the span's start offset, duration and a proportional bar. Agaprow marks a stretch under a parent where no child ran, which is where "the turn felt slow" usually hides. A failed span shows itserror.type. Imports no OpenTelemetry SDK and no regular expression.src/kiro_crew/cli_parser_agent.py,src/kiro_crew/cli_help.py,src/kiro_crew/cli.py: thetrace show <key>verb, its help entry and its dispatch. The key is a turn id, a session key or id, an ACP session id or a trace id.docs/guides/telemetry-otlp-traces.md,docs/system-specs/modules/cli.md: the command, with what it prints.test/tracing/test_trace_render.py(new),test/test_cli_split_dispatch.py: the tests below.Reading is bounded and read-only:
safe_read_file; a shard over 50 MB is skipped with a warning, a line over 256 KB, one nested past the JSON parser's limit, or one that is not a span (an id that is not hex counts) is skipped, and one warning per shard counts them. At most 100,000 spans are kept, newest shards first; at most 500 rows print, and a cut trace ends with the exact number of spans never shown (the trace's span count minus the span rows printed, so the subtrees under a cut-off span are counted).Error: cannot read <file name>: <exception class>, so a lookup never answers "nothing matched" for data it could not read. The text of the exception, which quotes the resolved path, is not printed.error.typeare printed, each throughsafe_terminal_line. Span attributes are allowlisted intracing/correlation.pyand never hold prompt or tool content; the command prints none of them anyway.No trace matches <key>.) and exits 0, asmemory searchdoes for no hits.Backwards compatibility
A new command; no existing command, setting, file or span changes. With tracing off, the directory is absent and the command prints the one-line no-match answer.
Tests
4c530d0bd2,test_a_command_hands_its_namespace_to_its_handler[trace]fails (the parser has notracecommand) andtest/tracing/test_trace_render.pyfails to import.flake8,isort,mypy, the black gate, the comment-history gate, the sync-I/O gate and the lane CI checks pass.python -m pytest test/tracing/test_trace_render.py -n0Manual verification
A turn of 10 s with two overlapping tool calls (one failed), read back through the command:
Sibling sweep
Sibling:
src/kiro_crew/tracing/exporter.py-- not affected -- the writer is unchanged; the reader uses its shard-name rule (shard_name_re("spans")) so a stray file in the folder is left outSibling:
src/kiro_crew/tracing/provider.py-- not affected --traces_dir()is the one place the folder is named, and the command uses itSibling:
src/kiro_crew/cli_commands_memory.py-- not affected -- the no-match answer followsmemory searchPattern harvest
Rule candidate: review-prompt
Pattern: a local log written for one purpose has no reader in the product, so the only way to use it is to open the raw file.
Related Issues
Part of the tracing work tracked in #1643 (the local-sink reader; no open pull request or assigned issue covers a trace viewer).
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement