Skip to content

feat(trace): add agk trace watch to live-tail a run#21

Open
kunalkushwaha wants to merge 1 commit into
mainfrom
feat/trace-watch
Open

feat(trace): add agk trace watch to live-tail a run#21
kunalkushwaha wants to merge 1 commit into
mainfrom
feat/trace-watch

Conversation

@kunalkushwaha

Copy link
Copy Markdown
Member

What

Adds agk trace watch — a lightweight, scriptable live-tail of a run's spans as they execute. It's the tail -f counterpart to the hot-reloading trace show TUI, and pairs naturally with agk run: run the agent in one terminal, watch the trace populate in another.

This is feature B5 (watch) from the FEATURES.md roadmap.

Behavior

$ agk trace watch
👀 Watching run-1782...  (Ctrl+C to stop)
────────────────────────────────────────────────────────────────
10:00:00  👤  agk.agent.run                                  2000ms
10:00:00  🤖  agk.llm.generate                               1000ms
10:00:01  🔧  agk.tool.call                                     0ms
────────────────────────────────────────────────────────────────
✅ Run complete — 3 spans, 1 LLM calls, 900 tokens, $0.0090, 2.00s
→ Inspect: agk trace view run-1782...
  • No run ID → follows the live run if one is running; otherwise waits for the next run to start (e.g. from agk run).
  • Ends when the run completes (its manifest.json is written) or on Ctrl+C.
  • Per-span line with icons (agent / LLM / tool / workflow) + duration; final summary + trace view hint on completion.
  • traceTailer reads only newly-appended complete lines, buffering any trailing partial line (so it never prints a half-written JSON record).

Testing

  • go build, go vet, go test ./..., gofmt all green.
  • Unit tests: tailer offset/partial-line handling, span formatting, icons, truncation.
  • Verified end-to-end against a simulated live run: a background writer appended spans over ~2s then wrote the manifest; watch streamed each span and exited cleanly on completion.

Independent branch off main. Touches the README commands table / trace section (trivial conflict with the other trace PRs).

🤖 Generated with Claude Code

Streams each span as it is appended to trace.jsonl — a lightweight, scriptable
counterpart to the hot-reloading `trace show` TUI. Pairs with `agk run` (run in
one terminal, watch in another).

- With no run ID, follows the live run if one is running, otherwise waits for the
  next run to start; ends when the run completes (manifest.json) or on Ctrl+C.
- Per-span line with icons (agent/LLM/tool/workflow) + duration; prints a final
  summary and a `trace view` hint on completion.
- traceTailer reads only newly-appended complete lines, buffering partial lines.

Tests: tailer offset/partial-line handling, span formatting, icons/truncation.
Verified end-to-end against a simulated live run (spans streamed, completion
detected, clean exit).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.

1 participant