bug: timeline span `seq` names a different event per span kind, and all five are undocumented

未关闭
#1,859 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
35/100
Issue 类型
重构
描述清晰度
基本清楚
活跃度
活跃
技术栈
go
领域
api, backend

调研方向

Start in core/session/timeline/timeline.go, where the five span structs declare a bare Seq field, then check agents.go (around lines 125-202) and hosts.go (lines 54 and 63) to confirm which event each one sets. The issue leaves open whether to rename the field with a deprecation period or only add doc comments, so settle that with a maintainer first. Done means each span's seq meaning is stated in code and in docs/session-api.md.

由索引模型根据 Issue 内容生成。

描述

bug documentation

Summary

GET /v1/sessions/{id}/timeline returns five span kinds, each with a seq. Four name the request event; one names the response. All five fields are undocumented, in a package where every other field carries a paragraph.

A consumer joining timeline spans to event data on seq therefore matches nothing for four of the five kinds — and gets no error, just an empty result, which is the failure mode that costs the most time to diagnose.

The actual mapping

On main (core/session/timeline/):

Span Declared Set at seq is the
Turn timeline.go:88 agents.go:176 — Seq: c.req.Seq request event
Tool timeline.go:105 agents.go:202 — Seq: c.resp.Seq response event
Job timeline.go:118 agents.go:125 — Seq: c.req.Seq request event
Return timeline.go:126 agents.go:161 — Seq: c.req.Seq request event
Host timeline.go:138 hosts.go:54, :63 — Seq: e.Seq the event it came from

Every one of those five declarations is a bare Seq uint64 \json:"seq"`with no comment. Compare the fields around them —Resent, Error, Model, ToolUseID` all have one, several of them a full paragraph.

How it bites

Token counts live on the response event (inference.inputTokens and friends). So the natural query — "show me each model call's latency beside its tokens" — joins turns[].seq to a response event and silently returns nothing:

# Returns a header and zero rows. No error.
jq -n --slurpfile tl tl.json --slurpfile ev ev.json '
  ($ev[0].events | map(select(.phase=="response")) | INDEX(.seq|tostring)) as $byseq
  | $tl[0].turns[] | select($byseq[(.seq|tostring)] != null)'

Measured on a 2,911-event session: 0 of 509 turns[].seq values in the paged range matched a response event. Switching to tools[].seq matched 458 of 592 immediately.

It cost two people on #1854 — once writing the query, once a reviewer who went to core/sessionapi/timeline.go (a real, different file) chasing the bare timeline.go:88 citation and found cache internals.

Proposed fix

Rename, do not just document. The names are the trap: identical field name, identical type, different referent, and nothing at the call site to warn you.

type Turn struct {
    // RequestSeq is the seq of the REQUEST event this turn began at. Token counts and
    // the status live on the matching RESPONSE event — pair by requestId, not by this.
    RequestSeq uint64 `json:"requestSeq"`
}

type Tool struct {
    // ResponseSeq is the seq of the RESPONSE event that asked for this tool, so it joins
    // directly to that event's inference fields.
    ResponseSeq uint64 `json:"responseSeq"`
}

That is a wire change, so it needs the usual skew handling: emit both keys for a release (seq plus the new name), with seq documented as deprecated, then drop it. agentop is the only in-tree consumer.

If a rename is too invasive, the minimum is a doc comment on each of the five saying which event it names, plus the mapping table above in docs/session-api.md. That is already done on the docs side in #1854, but the struct fields themselves remain bare — and a consumer reads the struct, not someone else's spec.

Also worth fixing alongside

/timeline reads up to 50,000 events; GET /v1/sessions/{id} caps ?limit at 2,000. Both numbers are documented, 70 lines apart in session-api.md, and never related to each other. On the same 2,911-event session a single-page join covers only the newest 2,000 events, so 134 of 592 tool spans have no matching event row unless the consumer pages with ?before=. #1854 documents this; the asymmetry itself may still be worth closing.

Scope note

Found while writing the queries in #1854's §9.3, against one developer's laptop archive (66 sessions, 29,606 events). The mapping generalises — it follows the code, not this traffic. The match counts above are from one 2,911-event session.

Refs #1854, #1810

主要语言
Go
星标
26
派生
46
平均合并
9 小时 55 分钟
30 天内合并 PR
257

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

rossoctl/cortex 的其他 Issue

查看 rossoctl/cortex 的全部 Issue

相似的 Issue

更多 Go Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。