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

Đang mở
#1,859 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
35/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
go
Lĩnh vực
api, backend

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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

Ngôn ngữ chính
Go
Star
26
Fork
46
Merge trung bình
9 giờ 55 phút
Pull request đã merge (30 ngày)
257

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của rossoctl/cortex

Tất cả issue của rossoctl/cortex

Issue tương tự

Thêm issue về Go

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.