Skip to content

The only tool you need to know what is happening and how to fix it.

feat: cli perf updates + cli tests (#236)

narrow-adventured5b74f5385d3
diff --git a/.github/workflows/cli-contract.yml b/.github/workflows/cli-contract.yml
new file mode 100644
index 00000000..10456cb1
--- /dev/null
+++ b/.github/workflows/cli-contract.yml
@@ -0,0 +1,41 @@
+name: CLI Contract
+
+# Boots the backend in SQLite mode and asserts the wire contract of every
+# endpoint the CLI calls (cli/test/contract). Runs on backend changes too,
+# since the point is to catch backend drift the CLI's mock-based unit tests
+# cannot. Equivalent local command: cd cli && just contract-test
+on:
+ push:
+ branches: [main]
+ paths:
+ - "cli/**"
+ - "backend/**"
+ - ".github/workflows/cli-contract.yml"
+ pull_request:
+ paths:
+ - "cli/**"
+ - "backend/**"
+ - ".github/workflows/cli-contract.yml"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ contract:
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: cli/test/contract
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Go
+ uses: actions/setup-go@v5
+ with:
+ go-version-file: cli/test/contract/go.mod
+ cache-dependency-path: cli/test/contract/go.sum
+
+ - name: Contract test
+ run: go test ./...
diff --git a/backend/app/models/dashboard.model.go b/backend/app/models/dashboard.model.go
index 36b7ca94..8c8feb5e 100644
--- a/backend/app/models/dashboard.model.go
+++ b/backend/app/models/dashboard.model.go
@@ -31,8 +31,9 @@ type DashboardResponse struct {
LastUpdated time.Time `json:"lastUpdated"`
}
-// TimeSeriesPoint is used internally for querying time-bucketed data
+// TimeSeriesPoint is used internally for querying time-bucketed data and is
+// serialized directly in the /api/metrics/query response.
type TimeSeriesPoint struct {
- Timestamp time.Time
- Value float64
+ Timestamp time.Time `json:"timestamp"`
+ Value float64 `json:"value"`
}
diff --git a/cli/.claude/skills/integration-test/SKILL.md b/cli/.claude/skills/integration-test/SKILL.md
index 89a41f64..78a1acd9 100644
--- a/cli/.claude/skills/integration-test/SKILL.md
+++ b/cli/.claude/skills/integration-test/SKILL.md
@@ -113,6 +113,23 @@ JSON shape: `{results: [{name, unit, series: {<tag-key>: [{timestamp, value}, ..
If a real trace id was captured above, run `logs query --trace-id $TRACE --since 720h`. Assert exit 0 and `{data, pagination}` shape.
+### By-id detail commands (captured id + recordedAt)
+
+These all **require** a timestamp flag; capture the id and its `recordedAt` together from `exceptions show`, then exercise them. All read-only.
+
+1. Capture one occurrence's id + recordedAt (+ optional trace/session ids):
+ ```bash
+ OCC=$(./bin/traceway exceptions show "$HASH" --output json | jq -c '.occurrences[0]')
+ OID=$(jq -r '.id' <<<"$OCC")
+ OTS=$(jq -r '.recordedAt' <<<"$OCC")
+ DT=$(jq -r '.distributedTraceId // empty' <<<"$OCC")
+ SID=$(jq -r '.sessionId // empty' <<<"$OCC")
+ ```
+2. `exceptions occurrence $OID --recorded-at $OTS` — assert exit 0 and `.exception.id == $OID`.
+3. **Required-flag enforcement** (no live data needed): `exceptions occurrence $OID` with no `--recorded-at` → exit 2 `usage_error`; `--recorded-at notadate` → exit 2 `invalid_timestamp`; `endpoints show not-a-uuid --recorded-at $OTS` → exit 2 `usage_error`.
+4. If `$DT` is non-empty: `traces show $DT --recorded-at $OTS` → exit 0, `.nodes` is an array. If `$SID` is non-empty: `sessions show $SID --started-at $OTS` → exit 0, `.session` present.
+5. `endpoints show` / `tasks show` / `ai-traces show` need an id of their own type — capture one from a `traces show` node when available (`.nodes[].endpoint.id` + `.endpoint.recordedAt`, etc.); otherwise skip with reason `no <type> id captured`.
+
## TTY-vs-pipe default
If `script` is available:
@@ -127,7 +144,7 @@ Mutating (skip with reason `forbidden verb`):
`exceptions archive`, `exceptions unarchive`, `login`, `logout`, `profiles use` (local mutation), `projects use` (local mutation of `state.json`).
Not in the CLI (skip with reason `subcommand not in CLI`) — kept so the report shows the gap if they ship:
-`endpoints show`, `sessions list`, `sessions show`, `traces show`, `ai-traces list`, `ai-traces show`.
+`tasks list`, `sessions list`, `ai-traces list`, `traces list`, `metrics discover`.
## Observation and reporting
diff --git a/cli/.claude/skills/traceway-cli.md b/cli/.claude/skills/traceway-cli.md
index 3224e83a..eefa6c27 100644
--- a/cli/.claude/skills/traceway-cli.md
+++ b/cli/.claude/skills/traceway-cli.md
@@ -117,6 +117,14 @@ traceway exceptions show <exceptionHash> [--page 1] [--page-size 20]
Returns the exception group plus an array of recent `occurrences`. Each occurrence has at least `recordedAt`, `attributes`, and optional `distributedTraceId` / `sessionId` (verify the exact shape against your build — schema is still settling). A bogus hash exits with code `5` and `not_found`.
+```
+traceway exceptions occurrence <exceptionId> --recorded-at <RFC3339>
+```
+
+Resolves **one occurrence by its UUID** directly (vs. paging through `show`'s occurrences), and additionally returns its linked `sessionId` and an inline `sessionRecording`. Result shape: `{exception: {...}, sessionId?, sessionRecording?}`.
+
+`--recorded-at` is **required** — occurrences live in a daily-partitioned table, so the timestamp bounds the lookup and lets ClickHouse prune partitions instead of scanning all of them. Source it from the dashboard URL's `t=` param (`/issues/<hash>/<id>?t=...`), a notification's `Occurred at` (convert `2006-01-02 15:04:05 UTC` → `2006-01-02T15:04:05Z`), or an `exceptions show` occurrence's `recordedAt`. Omitting it exits 2 `usage_error`; a non-RFC3339 value exits 2 `invalid_timestamp`.
+
**Forbidden without explicit instruction:** `exceptions archive` and `exceptions unarchive`. These are the only mutating exception subcommands in the current CLI — there is no `resolve` / `mute` yet.
### `logs`
@@ -168,7 +176,13 @@ traceway endpoints list [--since 24h]
Returns endpoints with latency percentiles and request counts. Best for "what's slow?" questions.
-There is **no `endpoints show` subcommand** in the current CLI — only `list`. If a user asks for a per-endpoint breakdown, use `--search "<endpoint-name>"` against `list`.
+`endpoints list` returns **groups** (one row per route, no id). For a per-route breakdown, use `--search "<endpoint-name>"` against `list`.
+
+```
+traceway endpoints show <endpointId> --recorded-at <RFC3339>
+```
+
+For **one request (transaction)** by its UUID — the detail behind `/endpoints/<name>/<endpointId>`. Returns `{endpoint, spans, hasSpans, exception?, messages}`: the request row, its span waterfall, and any linked exception/messages. `--recorded-at` is **required** (same daily-partition reason as above); take it from the URL's `t=` param.
Note `--order-by` does not include `p99`, `errorRate`, or `requests` as choices — the only sort fields right now are `impact`, `count`, `p95`, `lastSeen`. The default (`impact`) is usually what you want.
@@ -218,14 +232,26 @@ Result shape — `series` is a **map keyed by group tag**, not an array:
With `--group-by direction` on a network metric, the `series` keys become `"receive"` and `"transmit"` instead of `"__all__"`.
+### `tasks`, `ai-traces`, `sessions`, `traces` — by-id detail
+
+These resources currently expose only a by-id `show` (no `list` verb). The id comes from a dashboard URL, a notification, or an `exceptions show` occurrence — not from the CLI itself. Each `show` **requires** the record's timestamp for a partition-pruned lookup.
+
+```
+traceway tasks show <taskId> --recorded-at <RFC3339> # {task, spans, hasSpans, exception?, messages}
+traceway ai-traces show <traceId> --recorded-at <RFC3339> # {aiTrace, conversation?} (token/cost stats + stored conversation)
+traceway sessions show <sessionId> --started-at <RFC3339> # {session, exceptions} (uses --started-at, not --recorded-at)
+traceway traces show <distributedTraceId> --recorded-at <RFC3339> # {distributedTraceId, nodes:[...]}
+```
+
+`traces show` is the cross-service waterfall: every endpoint/task/ai-trace/exception node sharing a `distributedTraceId`, across all projects you can see (the route scopes by your JWT, so it ignores the active project). It's the highest-value RCA call — feed it an occurrence's `distributedTraceId` plus that occurrence's `recordedAt`.
+
+`sessions show` takes `--started-at` because the sessions table is partitioned on `started_at`. The session URL carries no `t=`; use the session's start, the URL's `from=`, or a linked occurrence's `recordedAt` (it falls inside the ±24h window).
+
### Subcommands the CLI does not currently have
-These are commonly requested but **not implemented** in the current binary. If a user asks for them, say so — don't fabricate flags.
+Commonly requested but **not implemented**. If a user asks, say so — don't fabricate flags.
-- `traces show <traceId>` — span waterfall view. Trace IDs in `logs query` / `exceptions show` output are currently link-only.
-- `sessions list` / `sessions show` — session replay listings.
-- `ai-traces list` / `ai-traces show` — LLM observability.
-- `endpoints show <name>` — per-endpoint detail (use `endpoints list --search`).
+- `tasks list` / `sessions list` / `ai-traces list` / `traces list` — no list verbs; only by-id `show` (get the id from a URL, notification, or `exceptions show` occurrence).
- `metrics list` / `metrics discover` — metric-name enumeration.
### `login` / `logout`
@@ -269,7 +295,7 @@ traceway logs query --since 15m --service api --min-severity 13 \
--page 1 --output json | jq '.data[]? | {timestamp, body, traceId}'
```
-There is no `traces show` subcommand yet — once a trace ID is captured, the waterfall view has to be inspected via the web UI.
+Once you have a `distributedTraceId` from an occurrence or endpoint/task, pull the cross-service waterfall directly: `traceway traces show <distributedTraceId> --recorded-at <that node's recordedAt>` (see the by-id detail section above). It stitches every endpoint/task/ai-trace/exception node sharing the id into one timeline — usually the highest-value RCA call.
### "Show me errors for service X in the last hour"
@@ -323,7 +349,7 @@ If you see a panic, stack trace, or unhandled error in stderr, **stop** and repo
1. **Bound your time windows.** Default to `--since 1h`. Never run a query without a time window — Traceway can fall back to all-time and return huge results.
2. **Keep `--page-size` small.** 10–20 is usually enough for first-pass triage. Don't pull 500 rows into context.
-3. **Capture identifiers, don't repeat list calls.** When you find a useful hash / trace id / session id, save it to a shell variable and reuse.
+3. **Capture identifiers *with their timestamp*.** When you find a useful id (occurrence / endpoint / task / trace / session), save its `recordedAt` (or `startedAt`) alongside it. The by-id `show`/`occurrence` commands **require** that timestamp (`--recorded-at` / `--started-at`) — it bounds the ClickHouse lookup to a few daily partitions instead of a full scan, so the lookup stays fast. Sources: a dashboard URL's `?t=` param, a list/`show` row's `recordedAt`, or a notification's `Occurred at` (convert `2006-01-02 15:04:05 UTC` → `2006-01-02T15:04:05Z`). **No timestamp to hand?** It can be approximate — the server windows ±24h (±48h for `traces show`) and falls back to a full scan if the record isn't in the window, so within a day stays fast and a wrong guess still resolves (slower). Recover it (`exceptions show <hash>` lists occurrences with `recordedAt`; a group's `lastSeen`/`firstSeen` bound the time), estimate it from context (notification time, the issue's `lastSeen`, the URL's `from`/`preset`), or **ask the user** roughly when it happened. Don't pass "now" for an old issue — that misses the window.
4. **Use `jq` aggressively.** Pull only the fields you need. A full exception group can be many KB; you usually want just `exceptionHash`, `count`, `lastSeen`, and the first line of the stack trace.
5. **Read before you act.** When the user describes a problem, read several signals (exceptions + endpoints + recent logs) before forming a hypothesis. Single-source diagnoses are usually wrong.
6. **Don't infer write actions.** "Look at this error" means show it, not archive it.
diff --git a/cli/README.md b/cli/README.md
index ec0e7821..f226ea40 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -52,14 +52,30 @@ traceway metrics query --name http.server.duration --aggregation avg --since 1h
| `traceway projects {list,use}` | List or select the active project |
| `traceway exceptions list` | Recent grouped exceptions |
| `traceway exceptions show <hash>` | A single exception group + occurrences |
+| `traceway exceptions occurrence <id> --recorded-at <t>` | A single occurrence by id (+ `sessionId` and recording) |
| `traceway exceptions archive <hash>...` | Archive one or more groups (mutating; needs `--yes` non-interactively) |
| `traceway exceptions unarchive <hash>...` | Unarchive (mutating; needs `--yes` non-interactively) |
| `traceway logs query` | Query logs with severity / service / search filters |
| `traceway endpoints list` | Per-endpoint p50/p95/p99 stats |
+| `traceway endpoints show <id> --recorded-at <t>` | A single request (transaction) by id: spans + linked errors |
+| `traceway tasks show <id> --recorded-at <t>` | A single background task run by id |
+| `traceway ai-traces show <id> --recorded-at <t>` | A single AI trace by id + its conversation |
+| `traceway sessions show <id> --started-at <t>` | A single session by id + the exceptions that fired in it |
+| `traceway traces show <id> --recorded-at <t>` | A distributed trace: every service node sharing the id |
| `traceway metrics query` | Time-series metric queries |
Run `traceway <command> --help` for full per-command flags.
+### By-id detail lookups are time-bounded
+
+The `show` / `occurrence` commands take a UUID plus a **required** timestamp flag
+(`--recorded-at`, or `--started-at` for `sessions`). Telemetry tables are
+partitioned by day; the timestamp bounds the query to a window around the record
+so the lookup prunes partitions instead of scanning all of them. Get the id and
+its timestamp together — from a dashboard URL's `?t=` param, a notification's
+`Occurred at`, or a list/`exceptions show` row's `recordedAt`. Omitting the flag
+exits 2 (`usage_error`); a non-RFC3339 value exits 2 (`invalid_timestamp`).
+
## Profiles
Multiple Traceway instances or accounts coexist via profiles. Configuration (URL, username) lives in `$XDG_CONFIG_HOME/traceway/config.json` so it can be checked in or managed declaratively (e.g. NixOS); credentials and the active project live in `$XDG_STATE_HOME/traceway/state.json`.
diff --git a/cli/cmd/traceway/aitraces.go b/cli/cmd/traceway/aitraces.go
new file mode 100644
index 00000000..f8f4e7ed
--- /dev/null
+++ b/cli/cmd/traceway/aitraces.go
@@ -0,0 +1,88 @@
+package main
+
+import (
+ "fmt"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tracewayapp/traceway/cli/internal/output"
+ "github.com/tracewayapp/traceway/cli/pkg/client"
+)
+
+func newAiTracesCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "ai-traces",
+ Short: "Inspect AI / LLM traces",
+ }
+ cmd.AddCommand(newAiTracesShowCmd())
+ return cmd
+}
+
+func newAiTracesShowCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "show <traceId>",
+ Short: "Show one AI trace by id with its conversation",
+ Long: `Show a single AI/LLM trace by its UUID, including token/cost stats and the
+stored conversation. This is the detail behind /ai-traces/<name>/<traceId>.
+
+--recorded-at is REQUIRED. The ai_traces table is daily-partitioned; the
+timestamp bounds the lookup to a window around it so ClickHouse prunes
+partitions instead of scanning all of them. Source it from the dashboard URL's
+t= param (/ai-traces/<name>/<id>?t=...) or a distributed-trace node's
+recordedAt.`,
+ Args: cobra.ExactArgs(1),
+ RunE: runAiTracesShow,
+ }
+ addTimestampFlag(cmd, "recorded-at", "Trace timestamp, RFC3339 (required; from the URL t= param)")
+ return cmd
+}
+
+func runAiTracesShow(cmd *cobra.Command, args []string) error {
+ ctx := cmd.Context()
+ mode := output.ResolveMode(flagOutput, output.StdoutIsTerminal())
+
+ sess, err := loadSession()
+ if err != nil {
+ return renderSessionError(cmd.ErrOrStderr(), mode, err)
+ }
+ if err := validateUUIDArg(cmd, mode, args[0], "trace id"); err != nil {
+ return err
+ }
+ recordedAt, err := resolveTimestamp(cmd, "recorded-at")
+ if err != nil {
+ return renderTimestampError(cmd.ErrOrStderr(), mode, "recorded-at", err)
+ }
+
+ c := client.New(sess.URL, client.WithJWT(sess.JWT))
+ resp, err := c.GetAiTrace(ctx, sess.ProjectID, args[0], recordedAt)
+ if err != nil {
+ return renderAPIError(cmd.ErrOrStderr(), mode, err, false)
+ }
+
+ switch mode {
+ case output.ModeJSON:
+ return output.RenderJSON(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ case output.ModeYAML:
+ return output.RenderYAML(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ default:
+ out := cmd.OutOrStdout()
+ if resp.AiTrace != nil {
+ a := resp.AiTrace
+ _, _ = fmt.Fprintf(out,
+ "ID: %s\nTRACE: %s\nRECORDED AT: %s\nMODEL: %s\nPROVIDER: %s\nOPERATION: %s\nTOKENS: %d in / %d out / %d total\nCOST: %.6f\nDURATION: %s\n",
+ a.Id, a.TraceName,
+ a.RecordedAt.Format("2006-01-02 15:04:05"),
+ pickStr(a.Model, "-"), pickStr(a.Provider, "-"), pickStr(a.Operation, "-"),
+ a.InputTokens, a.OutputTokens, a.TotalTokens,
+ a.TotalCost, formatDuration(a.Duration),
+ )
+ if a.DistributedTraceId != nil {
+ _, _ = fmt.Fprintf(out, "TRACE ID: %s\n", a.DistributedTraceId.String())
+ }
+ }
+ if len(resp.Conversation) > 0 {
+ _, _ = fmt.Fprintln(out, "\nCONVERSATION available (use --output json to view).")
+ }
+ return nil
+ }
+}
diff --git a/cli/cmd/traceway/detail_test.go b/cli/cmd/traceway/detail_test.go
new file mode 100644
index 00000000..6e68b3d1
--- /dev/null
+++ b/cli/cmd/traceway/detail_test.go
@@ -0,0 +1,256 @@
+package main
+
+import (
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+)
+
+func TestEndpointsShow_postsRecordedAtAndRendersJSON(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"endpoint":{"id":"00000000-0000-0000-0000-000000000002","endpoint":"GET /x","recordedAt":"2026-06-23T14:30:00Z"},"spans":[],"hasSpans":false,"messages":[]}`))
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ stdout, _, err := runCmd(t, "", "endpoints", "show",
+ "00000000-0000-0000-0000-000000000002",
+ "--recorded-at", "2026-06-23T14:30:00Z", "--output", "json")
+ if err != nil {
+ t.Fatalf("endpoints show: %v", err)
+ }
+ if gotPath != "/api/endpoints/00000000-0000-0000-0000-000000000002" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt body = %v", gotBody["recordedAt"])
+ }
+ if !strings.Contains(stdout.String(), `"GET /x"`) {
+ t.Errorf("expected endpoint in output: %s", stdout.String())
+ }
+}
+
+func TestEndpointsShow_missingRecordedAt_writesUsageEnvelope(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+ t.Fatal("server should not be called when --recorded-at is missing")
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, stderr, err := runCmd(t, "", "endpoints", "show",
+ "00000000-0000-0000-0000-000000000002", "--output", "json")
+ if err == nil {
+ t.Fatal("expected error")
+ }
+ if !strings.Contains(stderr.String(), `"usage_error"`) {
+ t.Errorf("expected usage_error envelope, got: %s", stderr.String())
+ }
+}
+
+func TestEndpointsShow_badTimestamp_writesInvalidTimestampEnvelope(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+ t.Fatal("server should not be called when --recorded-at is malformed")
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, stderr, err := runCmd(t, "", "endpoints", "show",
+ "00000000-0000-0000-0000-000000000002", "--recorded-at", "yesterday", "--output", "json")
+ if err == nil {
+ t.Fatal("expected error")
+ }
+ if !strings.Contains(stderr.String(), `"invalid_timestamp"`) {
+ t.Errorf("expected invalid_timestamp envelope, got: %s", stderr.String())
+ }
+}
+
+func TestEndpointsShow_badUUID_writesUsageEnvelope(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+ t.Fatal("server should not be called for a bad UUID")
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, stderr, err := runCmd(t, "", "endpoints", "show", "not-a-uuid",
+ "--recorded-at", "2026-06-23T14:30:00Z", "--output", "json")
+ if err == nil {
+ t.Fatal("expected error")
+ }
+ if !strings.Contains(stderr.String(), `"usage_error"`) {
+ t.Errorf("expected usage_error envelope, got: %s", stderr.String())
+ }
+}
+
+func TestExceptionsOccurrence_postsRecordedAt(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"exception":{"id":"00000000-0000-0000-0000-000000000001","exceptionHash":"abc","stackTrace":"boom","recordedAt":"2026-06-23T14:30:00Z"},"sessionId":"00000000-0000-0000-0000-0000000000aa"}`))
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ stdout, _, err := runCmd(t, "", "exceptions", "occurrence",
+ "00000000-0000-0000-0000-000000000001",
+ "--recorded-at", "2026-06-23T14:30:00Z", "--output", "json")
+ if err != nil {
+ t.Fatalf("exceptions occurrence: %v", err)
+ }
+ if gotPath != "/api/exception-stack-traces/by-id/00000000-0000-0000-0000-000000000001" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt body = %v", gotBody["recordedAt"])
+ }
+ if !strings.Contains(stdout.String(), `"abc"`) {
+ t.Errorf("expected hash in output: %s", stdout.String())
+ }
+}
+
+func TestTracesShow_rendersNodesAndNoProjectId(t *testing.T) {
+ var gotRawQuery string
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotRawQuery = r.URL.RawQuery
+ _, _ = w.Write([]byte(`{"distributedTraceId":"00000000-0000-0000-0000-000000000006","nodes":[{"projectName":"api","traceType":"endpoint","endpoint":{"id":"00000000-0000-0000-0000-0000000000d1","endpoint":"GET /x"},"spans":[]}]}`))
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ stdout, _, err := runCmd(t, "", "traces", "show",
+ "00000000-0000-0000-0000-000000000006",
+ "--recorded-at", "2026-06-23T14:30:00Z", "--output", "table")
+ if err != nil {
+ t.Fatalf("traces show: %v", err)
+ }
+ if gotRawQuery != "" {
+ t.Errorf("traces show must not send a query string, got %q", gotRawQuery)
+ }
+ out := stdout.String()
+ if !strings.Contains(out, "GET /x") || !strings.Contains(out, "endpoint") {
+ t.Errorf("expected node row in table: %s", out)
+ }
+}
+
+func TestSessionsShow_postsStartedAt(t *testing.T) {
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"session":{"id":"00000000-0000-0000-0000-000000000005","startedAt":"2026-06-23T14:30:00Z"},"exceptions":[]}`))
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, _, err := runCmd(t, "", "sessions", "show",
+ "00000000-0000-0000-0000-000000000005",
+ "--started-at", "2026-06-23T14:30:00Z", "--output", "json")
+ if err != nil {
+ t.Fatalf("sessions show: %v", err)
+ }
+ if gotBody["startedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("startedAt body = %v", gotBody["startedAt"])
+ }
+}
+
+func TestTasksShow_postsRecordedAtAndRendersTable(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"task":{"id":"00000000-0000-0000-0000-000000000003","taskName":"nightly","recordedAt":"2026-06-23T14:30:00Z","duration":1500000000},"spans":[{"id":"00000000-0000-0000-0000-0000000000b1","name":"db.query","startTime":"2026-06-23T14:30:00Z","duration":50000000}],"hasSpans":true,"exception":{"exceptionHash":"deadbeef","stackTrace":"boom\nat foo"},"messages":[]}`))
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ stdout, _, err := runCmd(t, "", "tasks", "show",
+ "00000000-0000-0000-0000-000000000003",
+ "--recorded-at", "2026-06-23T14:30:00Z", "--output", "table")
+ if err != nil {
+ t.Fatalf("tasks show: %v", err)
+ }
+ if gotPath != "/api/tasks/00000000-0000-0000-0000-000000000003" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt body = %v", gotBody["recordedAt"])
+ }
+ out := stdout.String()
+ for _, want := range []string{"nightly", "db.query", "deadbeef"} {
+ if !strings.Contains(out, want) {
+ t.Errorf("expected %q in table output: %s", want, out)
+ }
+ }
+}
+
+func TestTasksShow_missingRecordedAt_writesUsageEnvelope(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+ t.Fatal("server should not be called when --recorded-at is missing")
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, stderr, err := runCmd(t, "", "tasks", "show",
+ "00000000-0000-0000-0000-000000000003", "--output", "json")
+ if err == nil {
+ t.Fatal("expected error")
+ }
+ if !strings.Contains(stderr.String(), `"usage_error"`) {
+ t.Errorf("expected usage_error envelope, got: %s", stderr.String())
+ }
+}
+
+func TestAiTracesShow_postsRecordedAtAndRendersTable(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"aiTrace":{"id":"00000000-0000-0000-0000-000000000004","traceName":"chat","model":"claude","provider":"anthropic","operation":"messages","inputTokens":100,"outputTokens":50,"totalTokens":150,"totalCost":0.0123,"recordedAt":"2026-06-23T14:30:00Z","duration":2000000000},"conversation":[{"role":"user"}]}`))
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ stdout, _, err := runCmd(t, "", "ai-traces", "show",
+ "00000000-0000-0000-0000-000000000004",
+ "--recorded-at", "2026-06-23T14:30:00Z", "--output", "table")
+ if err != nil {
+ t.Fatalf("ai-traces show: %v", err)
+ }
+ if gotPath != "/api/ai-traces/00000000-0000-0000-0000-000000000004" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt body = %v", gotBody["recordedAt"])
+ }
+ out := stdout.String()
+ for _, want := range []string{"claude", "100 in / 50 out / 150 total", "CONVERSATION available"} {
+ if !strings.Contains(out, want) {
+ t.Errorf("expected %q in table output: %s", want, out)
+ }
+ }
+}
+
+func TestAiTracesShow_missingRecordedAt_writesUsageEnvelope(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+ t.Fatal("server should not be called when --recorded-at is missing")
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, stderr, err := runCmd(t, "", "ai-traces", "show",
+ "00000000-0000-0000-0000-000000000004", "--output", "json")
+ if err == nil {
+ t.Fatal("expected error")
+ }
+ if !strings.Contains(stderr.String(), `"usage_error"`) {
+ t.Errorf("expected usage_error envelope, got: %s", stderr.String())
+ }
+}
diff --git a/cli/cmd/traceway/endpoints.go b/cli/cmd/traceway/endpoints.go
index 0c38ce3b..4d2d33a9 100644
--- a/cli/cmd/traceway/endpoints.go
+++ b/cli/cmd/traceway/endpoints.go
@@ -2,6 +2,7 @@ package main
import (
"fmt"
+ "io"
"time"
"github.com/spf13/cobra"
@@ -18,6 +19,7 @@ func newEndpointsCmd() *cobra.Command {
Short: "Query HTTP endpoint performance",
}
cmd.AddCommand(newEndpointsListCmd())
+ cmd.AddCommand(newEndpointsShowCmd())
return cmd
}
@@ -47,6 +49,10 @@ func runEndpointsList(cmd *cobra.Command, _ []string) error {
if err != nil {
return renderTimeRangeError(cmd.ErrOrStderr(), mode, err)
}
+ if err := validatePaginationFlags(cmd); err != nil {
+ return renderUsageError(cmd.ErrOrStderr(), mode, err.Error(),
+ paginationHint("traceway endpoints list"))
+ }
page := resolvePagination(cmd)
search, _ := cmd.Flags().GetString("search")
orderBy, _ := cmd.Flags().GetString("order-by")
@@ -94,6 +100,107 @@ func runEndpointsList(cmd *cobra.Command, _ []string) error {
}
}
+func newEndpointsShowCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "show <endpointId>",
+ Short: "Show one request (transaction) by id with spans and linked errors",
+ Long: `Show a single endpoint request (transaction) by its UUID, with its span
+waterfall and any linked exception/messages.
+
+This is the per-request detail behind /endpoints/<name>/<endpointId>. For grouped
+p50/p95/p99 stats by route, use "endpoints list --search <name>" instead.
+
+--recorded-at is REQUIRED. The endpoints table is daily-partitioned; the
+timestamp bounds the lookup to a window around it so ClickHouse prunes
+partitions instead of scanning all of them. Source it from the dashboard URL's
+t= param (/endpoints/<name>/<id>?t=...) or a distributed-trace node's
+recordedAt.`,
+ Args: cobra.ExactArgs(1),
+ RunE: runEndpointsShow,
+ }
+ addTimestampFlag(cmd, "recorded-at", "Transaction timestamp, RFC3339 (required; from the URL t= param)")
+ return cmd
+}
+
+func runEndpointsShow(cmd *cobra.Command, args []string) error {
+ ctx := cmd.Context()
+ mode := output.ResolveMode(flagOutput, output.StdoutIsTerminal())
+
+ sess, err := loadSession()
+ if err != nil {
+ return renderSessionError(cmd.ErrOrStderr(), mode, err)
+ }
+ if err := validateUUIDArg(cmd, mode, args[0], "endpoint id"); err != nil {
+ return err
+ }
+ recordedAt, err := resolveTimestamp(cmd, "recorded-at")
+ if err != nil {
+ return renderTimestampError(cmd.ErrOrStderr(), mode, "recorded-at", err)
+ }
+
+ c := client.New(sess.URL, client.WithJWT(sess.JWT))
+ resp, err := c.GetEndpoint(ctx, sess.ProjectID, args[0], recordedAt)
+ if err != nil {
+ return renderAPIError(cmd.ErrOrStderr(), mode, err, false)
+ }
+
+ switch mode {
+ case output.ModeJSON:
+ return output.RenderJSON(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ case output.ModeYAML:
+ return output.RenderYAML(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ default:
+ out := cmd.OutOrStdout()
+ if resp.Endpoint != nil {
+ e := resp.Endpoint
+ _, _ = fmt.Fprintf(out,
+ "ID: %s\nENDPOINT: %s\nRECORDED AT: %s\nDURATION: %s\nSTATUS: %d\nSERVER: %s\nAPP VERSION: %s\n",
+ e.Id, e.Endpoint,
+ e.RecordedAt.Format("2006-01-02 15:04:05"),
+ formatDuration(e.Duration), e.StatusCode,
+ pickStr(e.ServerName, "-"), pickStr(e.AppVersion, "-"),
+ )
+ if e.DistributedTraceId != nil {
+ _, _ = fmt.Fprintf(out, "TRACE ID: %s\n", e.DistributedTraceId.String())
+ }
+ }
+ renderSpansTable(out, resp.Spans)
+ renderLinkedErrors(out, resp.Exception, resp.Messages)
+ return nil
+ }
+}
+
+// renderSpansTable prints a span waterfall (name + duration), or a count line
+// when there are none. Shared by endpoints show and tasks show.
+func renderSpansTable(out io.Writer, spans []client.Span) {
+ if len(spans) == 0 {
+ _, _ = fmt.Fprintln(out, "\nSPANS: none")
+ return
+ }
+ _, _ = fmt.Fprintf(out, "\nSPANS (%d):\n", len(spans))
+ tw := output.NewTabWriter(out)
+ _, _ = fmt.Fprintln(tw, "NAME\tSTART\tDURATION")
+ for _, s := range spans {
+ _, _ = fmt.Fprintf(tw, "%s\t%s\t%s\n",
+ s.Name, s.StartTime.Format("15:04:05.000"), formatDuration(s.Duration))
+ }
+ _ = tw.Flush()
+}
+
+// renderLinkedErrors prints the exception and message summaries attached to an
+// endpoint or task detail. Shared by endpoints show and tasks show.
+func renderLinkedErrors(out io.Writer, exc *client.LinkedException, messages []client.LinkedMessage) {
+ if exc != nil {
+ _, _ = fmt.Fprintf(out, "\nLINKED EXCEPTION (%s):\n%s\n", exc.ExceptionHash, firstLine(exc.StackTrace))
+ }
+ if len(messages) > 0 {
+ _, _ = fmt.Fprintf(out, "\nMESSAGES (%d):\n", len(messages))
+ for _, m := range messages {
+ _, _ = fmt.Fprintf(out, " - %s\n", firstLine(m.StackTrace))
+ }
+ }
+}
+
// formatDuration renders a Duration as a human-readable string.
// time.Duration's String() does this already (e.g. "50ms"); we just shorten
// for very small values.
diff --git a/cli/cmd/traceway/exceptions.go b/cli/cmd/traceway/exceptions.go
index 96753ab4..90b7f4ef 100644
--- a/cli/cmd/traceway/exceptions.go
+++ b/cli/cmd/traceway/exceptions.go
@@ -11,7 +11,7 @@ import (
)
var (
- exceptionsOrderBy = []string{"lastSeen", "firstSeen", "count"}
+ exceptionsOrderBy = []string{"lastSeen", "firstSeen", "count"}
exceptionsSearchTypes = []string{"text", "regex"}
)
@@ -22,6 +22,7 @@ func newExceptionsCmd() *cobra.Command {
}
cmd.AddCommand(newExceptionsListCmd())
cmd.AddCommand(newExceptionsShowCmd())
+ cmd.AddCommand(newExceptionsOccurrenceCmd())
cmd.AddCommand(newExceptionsArchiveCmd())
cmd.AddCommand(newExceptionsUnarchiveCmd())
return cmd
@@ -55,6 +56,10 @@ func runExceptionsList(cmd *cobra.Command, _ []string) error {
if err != nil {
return renderTimeRangeError(cmd.ErrOrStderr(), mode, err)
}
+ if err := validatePaginationFlags(cmd); err != nil {
+ return renderUsageError(cmd.ErrOrStderr(), mode, err.Error(),
+ paginationHint("traceway exceptions list"))
+ }
page := resolvePagination(cmd)
search, _ := cmd.Flags().GetString("search")
searchType, _ := cmd.Flags().GetString("search-type")
@@ -125,6 +130,10 @@ func runExceptionsShow(cmd *cobra.Command, args []string) error {
if err != nil {
return renderSessionError(cmd.ErrOrStderr(), mode, err)
}
+ if err := validatePaginationFlags(cmd); err != nil {
+ return renderUsageError(cmd.ErrOrStderr(), mode, err.Error(),
+ paginationHint("traceway exceptions show"))
+ }
page := resolvePagination(cmd)
page.PageSize = pickDefault(page.PageSize, 20) // detail uses 20 by default
@@ -169,6 +178,86 @@ func runExceptionsShow(cmd *cobra.Command, args []string) error {
}
}
+func newExceptionsOccurrenceCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "occurrence <exceptionId>",
+ Short: "Show one exception occurrence by id (fast, time-bounded)",
+ Long: `Show a single exception occurrence by its UUID.
+
+Unlike "exceptions show <hash>" (which groups by stack-trace hash and paginates
+occurrences), this resolves one occurrence directly and additionally returns its
+linked sessionId and an inline session recording.
+
+--recorded-at is REQUIRED. Occurrences live in a daily-partitioned table; the
+timestamp bounds the lookup to a window around it so ClickHouse prunes
+partitions instead of scanning all of them. Source it from the dashboard URL's
+t= param (/issues/<hash>/<id>?t=...), an "exceptions show" occurrence's
+recordedAt, or a notification's "Occurred at" (convert "2006-01-02 15:04:05 UTC"
+to RFC3339, i.e. "2006-01-02T15:04:05Z").`,
+ Args: cobra.ExactArgs(1),
+ RunE: runExceptionsOccurrence,
+ }
+ addTimestampFlag(cmd, "recorded-at", "Occurrence timestamp, RFC3339 (required; from the URL t= param or a notification's Occurred at)")
+ return cmd
+}
+
+func runExceptionsOccurrence(cmd *cobra.Command, args []string) error {
+ ctx := cmd.Context()
+ mode := output.ResolveMode(flagOutput, output.StdoutIsTerminal())
+
+ sess, err := loadSession()
+ if err != nil {
+ return renderSessionError(cmd.ErrOrStderr(), mode, err)
+ }
+ if err := validateUUIDArg(cmd, mode, args[0], "exception id"); err != nil {
+ return err
+ }
+ recordedAt, err := resolveTimestamp(cmd, "recorded-at")
+ if err != nil {
+ return renderTimestampError(cmd.ErrOrStderr(), mode, "recorded-at", err)
+ }
+
+ c := client.New(sess.URL, client.WithJWT(sess.JWT))
+ resp, err := c.GetExceptionById(ctx, sess.ProjectID, args[0], recordedAt)
+ if err != nil {
+ return renderAPIError(cmd.ErrOrStderr(), mode, err, false)
+ }
+
+ switch mode {
+ case output.ModeJSON:
+ return output.RenderJSON(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ case output.ModeYAML:
+ return output.RenderYAML(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ default:
+ occ := resp.Exception
+ if occ == nil {
+ _, err := fmt.Fprintln(cmd.OutOrStdout(), "No occurrence returned.")
+ return err
+ }
+ out := cmd.OutOrStdout()
+ _, _ = fmt.Fprintf(out,
+ "ID: %s\nHASH: %s\nRECORDED AT: %s\nSERVER: %s\nAPP VERSION: %s\nTRACE TYPE: %s\n",
+ occ.Id, occ.ExceptionHash,
+ occ.RecordedAt.Format("2006-01-02 15:04:05"),
+ pickStr(occ.ServerName, "-"),
+ pickStr(occ.AppVersion, "-"),
+ pickStr(occ.TraceType, "-"),
+ )
+ if occ.DistributedTraceId != nil {
+ _, _ = fmt.Fprintf(out, "TRACE ID: %s\n", occ.DistributedTraceId.String())
+ }
+ sid := resp.SessionId
+ if sid == nil {
+ sid = occ.SessionId
+ }
+ if sid != nil {
+ _, _ = fmt.Fprintf(out, "SESSION ID: %s\n", sid.String())
+ }
+ _, _ = fmt.Fprintf(out, "\nSTACK TRACE:\n%s\n", occ.StackTrace)
+ return nil
+ }
+}
+
func newExceptionsArchiveCmd() *cobra.Command {
return &cobra.Command{
Use: "archive <hash> [<hash>...]",
@@ -253,4 +342,3 @@ func truncateHash(hash string, n int) string {
}
return hash[:n]
}
-
diff --git a/cli/cmd/traceway/exceptions_test.go b/cli/cmd/traceway/exceptions_test.go
index 72c6533b..9ce87502 100644
--- a/cli/cmd/traceway/exceptions_test.go
+++ b/cli/cmd/traceway/exceptions_test.go
@@ -125,6 +125,26 @@ func TestExceptionsList_invalidTimeRange_writesEnvelope(t *testing.T) {
}
}
+func TestExceptionsList_outOfRangePageSize_writesUsageError(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+ t.Error("server must not be hit when pagination is rejected locally")
+ }))
+ defer srv.Close()
+ seedSessionFor(t, srv.URL)
+
+ _, stderr, err := runCmd(t, "", "exceptions", "list", "--output", "json", "--page-size", "200")
+ if err == nil {
+ t.Fatal("expected error")
+ }
+ var ce *cliError
+ if !errors.As(err, &ce) || ce.code != exitcode.Usage {
+ t.Fatalf("expected *cliError with exitcode.Usage, got %v", err)
+ }
+ if !strings.Contains(stderr.String(), "usage_error") {
+ t.Errorf("expected usage_error envelope, got: %s", stderr.String())
+ }
+}
+
func TestExceptionsShow_passesHashInPath(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/api/exception-stack-traces/abc" {
diff --git a/cli/cmd/traceway/logs.go b/cli/cmd/traceway/logs.go
index 660310a5..a2a7226a 100644
--- a/cli/cmd/traceway/logs.go
+++ b/cli/cmd/traceway/logs.go
@@ -53,6 +53,10 @@ func runLogsQuery(cmd *cobra.Command, _ []string) error {
if err != nil {
return renderTimeRangeError(cmd.ErrOrStderr(), mode, err)
}
+ if err := validatePaginationFlags(cmd); err != nil {
+ return renderUsageError(cmd.ErrOrStderr(), mode, err.Error(),
+ paginationHint("traceway logs query"))
+ }
page := resolvePagination(cmd)
service, _ := cmd.Flags().GetString("service")
minSev, _ := cmd.Flags().GetUint8("min-severity")
diff --git a/cli/cmd/traceway/querycommon.go b/cli/cmd/traceway/querycommon.go
index 68833beb..96551b54 100644
--- a/cli/cmd/traceway/querycommon.go
+++ b/cli/cmd/traceway/querycommon.go
@@ -8,6 +8,7 @@ import (
"os"
"strings"
+ "github.com/google/uuid"
"github.com/spf13/cobra"
"golang.org/x/term"
@@ -32,6 +33,29 @@ func resolvePagination(cmd *cobra.Command) client.PaginationParams {
return client.PaginationParams{Page: page, PageSize: pageSize}
}
+// validatePaginationFlags rejects --page/--page-size values the backend would
+// refuse (it binds page min=1, pageSize min=1,max=100). On violation it returns
+// an error formatted for the usage_error envelope's Message field; callers pass
+// it to renderUsageError. Mirrors validateEnumFlag so out-of-range pagination
+// surfaces a local usage error instead of a raw backend 400.
+func validatePaginationFlags(cmd *cobra.Command) error {
+ page, _ := cmd.Flags().GetInt("page")
+ pageSize, _ := cmd.Flags().GetInt("page-size")
+ if page < 1 {
+ return fmt.Errorf("--page must be 1 or greater")
+ }
+ if pageSize < 1 || pageSize > 100 {
+ return fmt.Errorf("--page-size must be between 1 and 100")
+ }
+ return nil
+}
+
+// paginationHint returns a usage_error hint showing the valid pagination bounds
+// for a command, e.g. "traceway exceptions list --page <1+> --page-size <1-100>".
+func paginationHint(cmdPath string) string {
+ return fmt.Sprintf("%s --page <1+> --page-size <1-100>", cmdPath)
+}
+
// firstLine returns the first line of s, useful for fitting a stack trace
// into a table column.
func firstLine(s string) string {
@@ -59,6 +83,18 @@ func pickDefault(v, alt int) int {
return v
}
+// validateUUIDArg checks that id parses as a UUID. On failure it renders a
+// usage_error envelope to the command's stderr and returns the resulting
+// *cliError (callers should return it directly); on success it returns nil.
+// label names the argument in the message, e.g. "exception id" or "task id".
+func validateUUIDArg(cmd *cobra.Command, mode output.Mode, id, label string) error {
+ if _, err := uuid.Parse(id); err != nil {
+ return renderUsageError(cmd.ErrOrStderr(), mode,
+ fmt.Sprintf("invalid %s %q: must be a UUID", label, id), "")
+ }
+ return nil
+}
+
// renderUsageError writes a usage_error envelope and returns a *cliError
// with exitcode.Usage. Used when a command receives invalid flag combinations
// or values that aren't covered by other validators.
diff --git a/cli/cmd/traceway/querycommon_test.go b/cli/cmd/traceway/querycommon_test.go
index 7d899a9e..9942b6e4 100644
--- a/cli/cmd/traceway/querycommon_test.go
+++ b/cli/cmd/traceway/querycommon_test.go
@@ -114,3 +114,37 @@ func TestResolvePagination_explicit(t *testing.T) {
t.Errorf("PageSize = %d, want 100", p.PageSize)
}
}
+
+func TestValidatePaginationFlags(t *testing.T) {
+ cases := []struct {
+ name string
+ args []string
+ wantErr bool
+ }{
+ {"defaults", nil, false},
+ {"in-range", []string{"--page", "2", "--page-size", "50"}, false},
+ {"max-page-size", []string{"--page-size", "100"}, false},
+ {"min-page-size", []string{"--page-size", "1"}, false},
+ {"page-zero", []string{"--page", "0"}, true},
+ {"page-negative", []string{"--page", "-1"}, true},
+ {"page-size-zero", []string{"--page-size", "0"}, true},
+ {"page-size-over-max", []string{"--page-size", "101"}, true},
+ {"page-size-way-over", []string{"--page-size", "200"}, true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ cmd := &cobra.Command{Use: "fake"}
+ addPaginationFlags(cmd)
+ if err := cmd.ParseFlags(tc.args); err != nil {
+ t.Fatal(err)
+ }
+ err := validatePaginationFlags(cmd)
+ if tc.wantErr && err == nil {
+ t.Errorf("validatePaginationFlags(%v) = nil, want error", tc.args)
+ }
+ if !tc.wantErr && err != nil {
+ t.Errorf("validatePaginationFlags(%v) = %v, want nil", tc.args, err)
+ }
+ })
+ }
+}
diff --git a/cli/cmd/traceway/root.go b/cli/cmd/traceway/root.go
index 8f36da9d..c0609966 100644
--- a/cli/cmd/traceway/root.go
+++ b/cli/cmd/traceway/root.go
@@ -6,11 +6,11 @@ import (
// Global flag values, populated by Cobra at flag-parse time.
var (
- flagProfile string
- flagProject string
- flagOutput string
- flagFields string
- flagYes bool
+ flagProfile string
+ flagProject string
+ flagOutput string
+ flagFields string
+ flagYes bool
)
func newRootCmd() *cobra.Command {
@@ -36,6 +36,10 @@ func newRootCmd() *cobra.Command {
cmd.AddCommand(newExceptionsCmd())
cmd.AddCommand(newLogsCmd())
cmd.AddCommand(newEndpointsCmd())
+ cmd.AddCommand(newTasksCmd())
+ cmd.AddCommand(newAiTracesCmd())
+ cmd.AddCommand(newSessionsCmd())
+ cmd.AddCommand(newTracesCmd())
cmd.AddCommand(newMetricsCmd())
cmd.AddCommand(newVersionCmd())
diff --git a/cli/cmd/traceway/sessions.go b/cli/cmd/traceway/sessions.go
new file mode 100644
index 00000000..713de7db
--- /dev/null
+++ b/cli/cmd/traceway/sessions.go
@@ -0,0 +1,91 @@
+package main
+
+import (
+ "fmt"
+ "time"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tracewayapp/traceway/cli/internal/output"
+ "github.com/tracewayapp/traceway/cli/pkg/client"
+)
+
+func newSessionsCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "sessions",
+ Short: "Inspect user sessions",
+ }
+ cmd.AddCommand(newSessionsShowCmd())
+ return cmd
+}
+
+func newSessionsShowCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "show <sessionId>",
+ Short: "Show one session by id with the exceptions that fired during it",
+ Long: `Show a single user session by its UUID, plus the exceptions/messages that fired
+during it. This is the detail behind /sessions/<sessionId>.
+
+--started-at is REQUIRED (sessions are partitioned on started_at, not
+recorded_at). The timestamp bounds the lookup to a window around it so ClickHouse
+prunes partitions instead of scanning all of them. The session URL carries no t=
+param; source the time from the session's startedAt, the URL's from=, or the
+recordedAt of a linked exception occurrence (it falls inside the window).`,
+ Args: cobra.ExactArgs(1),
+ RunE: runSessionsShow,
+ }
+ addTimestampFlag(cmd, "started-at", "Session start timestamp, RFC3339 (required; from the session startedAt or a linked occurrence's recordedAt)")
+ return cmd
+}
+
+func runSessionsShow(cmd *cobra.Command, args []string) error {
+ ctx := cmd.Context()
+ mode := output.ResolveMode(flagOutput, output.StdoutIsTerminal())
+
+ sess, err := loadSession()
+ if err != nil {
+ return renderSessionError(cmd.ErrOrStderr(), mode, err)
+ }
+ if err := validateUUIDArg(cmd, mode, args[0], "session id"); err != nil {
+ return err
+ }
+ startedAt, err := resolveTimestamp(cmd, "started-at")
+ if err != nil {
+ return renderTimestampError(cmd.ErrOrStderr(), mode, "started-at", err)
+ }
+
+ c := client.New(sess.URL, client.WithJWT(sess.JWT))
+ resp, err := c.GetSession(ctx, sess.ProjectID, args[0], startedAt)
+ if err != nil {
+ return renderAPIError(cmd.ErrOrStderr(), mode, err, false)
+ }
+
+ switch mode {
+ case output.ModeJSON:
+ return output.RenderJSON(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ case output.ModeYAML:
+ return output.RenderYAML(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ default:
+ out := cmd.OutOrStdout()
+ if resp.Session != nil {
+ s := resp.Session
+ _, _ = fmt.Fprintf(out,
+ "ID: %s\nSTARTED AT: %s\nDURATION: %s\nSERVER: %s\nAPP VERSION: %s\n",
+ s.Id, s.StartedAt.Format("2006-01-02 15:04:05"),
+ formatDuration(time.Duration(s.Duration)), pickStr(s.ServerName, "-"), pickStr(s.AppVersion, "-"),
+ )
+ }
+ if len(resp.Exceptions) == 0 {
+ _, _ = fmt.Fprintln(out, "\nEXCEPTIONS: none")
+ return nil
+ }
+ _, _ = fmt.Fprintf(out, "\nEXCEPTIONS (%d):\n", len(resp.Exceptions))
+ tw := output.NewTabWriter(out)
+ _, _ = fmt.Fprintln(tw, "ID\tRECORDED AT\tHASH\tFIRST LINE")
+ for _, e := range resp.Exceptions {
+ _, _ = fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n",
+ e.Id, e.RecordedAt, truncateHash(e.ExceptionHash, 12), firstLine(e.StackTrace))
+ }
+ return tw.Flush()
+ }
+}
diff --git a/cli/cmd/traceway/tasks.go b/cli/cmd/traceway/tasks.go
new file mode 100644
index 00000000..11d56a9b
--- /dev/null
+++ b/cli/cmd/traceway/tasks.go
@@ -0,0 +1,85 @@
+package main
+
+import (
+ "fmt"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tracewayapp/traceway/cli/internal/output"
+ "github.com/tracewayapp/traceway/cli/pkg/client"
+)
+
+func newTasksCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "tasks",
+ Short: "Inspect background task runs",
+ }
+ cmd.AddCommand(newTasksShowCmd())
+ return cmd
+}
+
+func newTasksShowCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "show <taskId>",
+ Short: "Show one background task run by id with spans and linked errors",
+ Long: `Show a single background task run by its UUID, with its span waterfall and any
+linked exception/messages. This is the detail behind /tasks/<name>/<taskId>.
+
+--recorded-at is REQUIRED. The tasks table is daily-partitioned; the timestamp
+bounds the lookup to a window around it so ClickHouse prunes partitions instead
+of scanning all of them. Source it from the dashboard URL's t= param
+(/tasks/<name>/<id>?t=...) or a distributed-trace node's recordedAt.`,
+ Args: cobra.ExactArgs(1),
+ RunE: runTasksShow,
+ }
+ addTimestampFlag(cmd, "recorded-at", "Task timestamp, RFC3339 (required; from the URL t= param)")
+ return cmd
+}
+
+func runTasksShow(cmd *cobra.Command, args []string) error {
+ ctx := cmd.Context()
+ mode := output.ResolveMode(flagOutput, output.StdoutIsTerminal())
+
+ sess, err := loadSession()
+ if err != nil {
+ return renderSessionError(cmd.ErrOrStderr(), mode, err)
+ }
+ if err := validateUUIDArg(cmd, mode, args[0], "task id"); err != nil {
+ return err
+ }
+ recordedAt, err := resolveTimestamp(cmd, "recorded-at")
+ if err != nil {
+ return renderTimestampError(cmd.ErrOrStderr(), mode, "recorded-at", err)
+ }
+
+ c := client.New(sess.URL, client.WithJWT(sess.JWT))
+ resp, err := c.GetTask(ctx, sess.ProjectID, args[0], recordedAt)
+ if err != nil {
+ return renderAPIError(cmd.ErrOrStderr(), mode, err, false)
+ }
+
+ switch mode {
+ case output.ModeJSON:
+ return output.RenderJSON(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ case output.ModeYAML:
+ return output.RenderYAML(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ default:
+ out := cmd.OutOrStdout()
+ if resp.Task != nil {
+ t := resp.Task
+ _, _ = fmt.Fprintf(out,
+ "ID: %s\nTASK: %s\nRECORDED AT: %s\nDURATION: %s\nSERVER: %s\nAPP VERSION: %s\n",
+ t.Id, t.TaskName,
+ t.RecordedAt.Format("2006-01-02 15:04:05"),
+ formatDuration(t.Duration),
+ pickStr(t.ServerName, "-"), pickStr(t.AppVersion, "-"),
+ )
+ if t.DistributedTraceId != nil {
+ _, _ = fmt.Fprintf(out, "TRACE ID: %s\n", t.DistributedTraceId.String())
+ }
+ }
+ renderSpansTable(out, resp.Spans)
+ renderLinkedErrors(out, resp.Exception, resp.Messages)
+ return nil
+ }
+}
diff --git a/cli/cmd/traceway/timerange.go b/cli/cmd/traceway/timerange.go
index fdbbc949..7a8a2ba4 100644
--- a/cli/cmd/traceway/timerange.go
+++ b/cli/cmd/traceway/timerange.go
@@ -94,3 +94,52 @@ func renderTimeRangeError(errOut io.Writer, mode output.Mode, err error) error {
})
return newCLIError(exitcode.Usage, "invalid_time_range")
}
+
+// Sentinels for resolveTimestamp. errTimestampMissing means the required flag
+// was omitted; errTimestampInvalid means it wasn't RFC3339. renderTimestampError
+// maps them to the right envelope.
+var (
+ errTimestampMissing = errors.New("timestamp required")
+ errTimestampInvalid = errors.New("invalid timestamp")
+)
+
+// addTimestampFlag registers a single required RFC3339 timestamp flag (e.g.
+// --recorded-at, --started-at) on a by-id detail command. The flag is enforced
+// in resolveTimestamp rather than via MarkFlagRequired so a miss renders our
+// usage envelope (the root command silences cobra's own errors).
+func addTimestampFlag(cmd *cobra.Command, name, usage string) {
+ cmd.Flags().String(name, "", usage)
+}
+
+// resolveTimestamp reads the named flag and parses it as RFC3339. It is
+// mandatory: by-id lookups must bound their query to a window around the
+// record's timestamp so ClickHouse prunes daily partitions. Returns
+// errTimestampMissing when empty, errTimestampInvalid when malformed.
+func resolveTimestamp(cmd *cobra.Command, name string) (time.Time, error) {
+ raw, _ := cmd.Flags().GetString(name)
+ raw = strings.TrimSpace(raw)
+ if raw == "" {
+ return time.Time{}, fmt.Errorf("%w: --%s is required", errTimestampMissing, name)
+ }
+ t, err := time.Parse(time.RFC3339, raw)
+ if err != nil {
+ return time.Time{}, fmt.Errorf("%w: --%s: %v", errTimestampInvalid, name, err)
+ }
+ return t, nil
+}
+
+// renderTimestampError maps a resolveTimestamp failure to an envelope. A missing
+// flag is a usage_error; a malformed value is invalid_timestamp. Both exit 2.
+func renderTimestampError(errOut io.Writer, mode output.Mode, name string, err error) error {
+ code := "invalid_timestamp"
+ if errors.Is(err, errTimestampMissing) {
+ code = "usage_error"
+ }
+ _ = output.RenderError(errOut, mode, output.ErrorEnvelope{
+ Code: code,
+ Message: err.Error(),
+ Hint: "pass --" + name + " RFC3339 (e.g. 2026-06-23T14:30:00Z); copy it from the dashboard URL's t= param or a notification's \"Occurred at\"",
+ ExitCode: exitcode.Usage,
+ })
+ return newCLIError(exitcode.Usage, code)
+}
diff --git a/cli/cmd/traceway/traces.go b/cli/cmd/traceway/traces.go
new file mode 100644
index 00000000..0b157914
--- /dev/null
+++ b/cli/cmd/traceway/traces.go
@@ -0,0 +1,94 @@
+package main
+
+import (
+ "fmt"
+
+ "github.com/spf13/cobra"
+
+ "github.com/tracewayapp/traceway/cli/internal/output"
+ "github.com/tracewayapp/traceway/cli/pkg/client"
+)
+
+func newTracesCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "traces",
+ Short: "Inspect distributed traces across services",
+ }
+ cmd.AddCommand(newTracesShowCmd())
+ return cmd
+}
+
+func newTracesShowCmd() *cobra.Command {
+ cmd := &cobra.Command{
+ Use: "show <distributedTraceId>",
+ Short: "Show a distributed trace: every service node that shares the trace id",
+ Long: `Show the full cross-service timeline for a distributed trace id — every
+endpoint, task, ai-trace, and exception node that shares it, across all projects
+you can see. This is the highest-value root-cause view: it stitches one logical
+request together end to end.
+
+The distributed trace id comes from an occurrence's distributedTraceId (in
+"exceptions show" / "exceptions occurrence" output) or an endpoint/task's
+distributedTraceId.
+
+--recorded-at is REQUIRED. The lookup is bounded to a window around it so
+ClickHouse prunes partitions instead of scanning all of them. Use the recordedAt
+of the occurrence/node you got the trace id from.`,
+ Args: cobra.ExactArgs(1),
+ RunE: runTracesShow,
+ }
+ addTimestampFlag(cmd, "recorded-at", "A node's timestamp, RFC3339 (required; the recordedAt of the occurrence/node you got the trace id from)")
+ return cmd
+}
+
+func runTracesShow(cmd *cobra.Command, args []string) error {
+ ctx := cmd.Context()
+ mode := output.ResolveMode(flagOutput, output.StdoutIsTerminal())
+
+ sess, err := loadSession()
+ if err != nil {
+ return renderSessionError(cmd.ErrOrStderr(), mode, err)
+ }
+ if err := validateUUIDArg(cmd, mode, args[0], "distributed trace id"); err != nil {
+ return err
+ }
+ recordedAt, err := resolveTimestamp(cmd, "recorded-at")
+ if err != nil {
+ return renderTimestampError(cmd.ErrOrStderr(), mode, "recorded-at", err)
+ }
+
+ c := client.New(sess.URL, client.WithJWT(sess.JWT))
+ resp, err := c.GetDistributedTrace(ctx, args[0], recordedAt)
+ if err != nil {
+ return renderAPIError(cmd.ErrOrStderr(), mode, err, false)
+ }
+
+ switch mode {
+ case output.ModeJSON:
+ return output.RenderJSON(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ case output.ModeYAML:
+ return output.RenderYAML(cmd.OutOrStdout(), resp, output.ParseFieldsFlag(flagFields))
+ default:
+ out := cmd.OutOrStdout()
+ _, _ = fmt.Fprintf(out, "DISTRIBUTED TRACE: %s\nNODES (%d):\n", resp.DistributedTraceId, len(resp.Nodes))
+ tw := output.NewTabWriter(out)
+ _, _ = fmt.Fprintln(tw, "PROJECT\tTYPE\tNAME\tERROR")
+ for _, n := range resp.Nodes {
+ name := "-"
+ switch {
+ case n.Endpoint != nil:
+ name = n.Endpoint.Endpoint
+ case n.Task != nil:
+ name = n.Task.TaskName
+ case n.AiTrace != nil:
+ name = n.AiTrace.TraceName
+ }
+ errCol := "-"
+ if n.Exception != nil {
+ errCol = truncateHash(n.Exception.ExceptionHash, 12)
+ }
+ _, _ = fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n", pickStr(n.ProjectName, "-"), n.TraceType, name, errCol)
+ }
+ return tw.Flush()
+ }
+}
diff --git a/cli/justfile b/cli/justfile
index 2617682e..a48377f1 100644
--- a/cli/justfile
+++ b/cli/justfile
@@ -9,6 +9,11 @@ test:
smoke-test:
gotestsum --format pkgname -- -tags smoke ./test/smoke/...
+# Boot the backend in SQLite mode and assert the CLI's wire contract for every
+# endpoint. Pass -- -update to regenerate the golden fingerprints in testdata/.
+contract-test *args:
+ cd test/contract && go test ./... {{args}}
+
lint:
golangci-lint run
diff --git a/cli/pkg/client/detail.go b/cli/pkg/client/detail.go
new file mode 100644
index 00000000..fb2f3f09
--- /dev/null
+++ b/cli/pkg/client/detail.go
@@ -0,0 +1,217 @@
+package client
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/url"
+ "time"
+
+ "github.com/google/uuid"
+)
+
+// recordedAtBody is the body for the by-id detail endpoints that bound their
+// ClickHouse lookup to a window around recordedAt. The CLI always sends it:
+// without it the server falls back to scanning every daily partition.
+type recordedAtBody struct {
+ RecordedAt time.Time `json:"recordedAt"`
+}
+
+// startedAtBody is recordedAtBody's session equivalent — the sessions table is
+// partitioned on started_at, so its detail endpoint takes startedAt instead.
+type startedAtBody struct {
+ StartedAt time.Time `json:"startedAt"`
+}
+
+// Span mirrors models.Span. Returned inside endpoint, task, and distributed
+// trace detail responses.
+type Span struct {
+ Id uuid.UUID `json:"id"`
+ TraceId uuid.UUID `json:"traceId"`
+ ProjectId uuid.UUID `json:"projectId"`
+ Name string `json:"name"`
+ StartTime time.Time `json:"startTime"`
+ Duration time.Duration `json:"duration"`
+ RecordedAt time.Time `json:"recordedAt"`
+ ParentSpanId *uuid.UUID `json:"parentSpanId,omitempty"`
+ Attributes map[string]string `json:"attributes,omitempty"`
+}
+
+// Task mirrors models.Task — one run of a background task.
+type Task struct {
+ Id uuid.UUID `json:"id"`
+ ProjectId uuid.UUID `json:"projectId"`
+ TaskName string `json:"taskName"`
+ Duration time.Duration `json:"duration"`
+ RecordedAt time.Time `json:"recordedAt"`
+ ClientIP string `json:"clientIP"`
+ Attributes map[string]string `json:"attributes"`
+ AppVersion string `json:"appVersion"`
+ ServerName string `json:"serverName"`
+ DistributedTraceId *uuid.UUID `json:"distributedTraceId,omitempty"`
+ SpanId *uuid.UUID `json:"spanId,omitempty"`
+ IsRoot bool `json:"isRoot"`
+}
+
+// AiTrace mirrors models.AiTrace — one LLM call/operation.
+type AiTrace struct {
+ Id uuid.UUID `json:"id"`
+ ProjectId uuid.UUID `json:"projectId"`
+ RecordedAt time.Time `json:"recordedAt"`
+ Duration time.Duration `json:"duration"`
+ StatusCode uint8 `json:"statusCode"`
+ Model string `json:"model"`
+ ResponseModel string `json:"responseModel"`
+ Provider string `json:"provider"`
+ Operation string `json:"operation"`
+ InputTokens int64 `json:"inputTokens"`
+ OutputTokens int64 `json:"outputTokens"`
+ TotalTokens int64 `json:"totalTokens"`
+ CachedTokens int64 `json:"cachedTokens"`
+ ReasoningTokens int64 `json:"reasoningTokens"`
+ InputCost float64 `json:"inputCost"`
+ OutputCost float64 `json:"outputCost"`
+ TotalCost float64 `json:"totalCost"`
+ TraceName string `json:"traceName"`
+ UserId string `json:"userId"`
+ FinishReason string `json:"finishReason"`
+ ServerName string `json:"serverName"`
+ AppVersion string `json:"appVersion"`
+ StorageKey string `json:"storageKey"`
+ Attributes map[string]string `json:"attributes"`
+ DistributedTraceId *uuid.UUID `json:"distributedTraceId,omitempty"`
+ IsRoot bool `json:"isRoot"`
+}
+
+// Session mirrors models.Session — one user session that can be replayed.
+type Session struct {
+ Id uuid.UUID `json:"id"`
+ ProjectId uuid.UUID `json:"projectId"`
+ StartedAt time.Time `json:"startedAt"`
+ EndedAt *time.Time `json:"endedAt,omitempty"`
+ Duration int64 `json:"duration"`
+ ClientIP string `json:"clientIP"`
+ Attributes map[string]string `json:"attributes"`
+ AppVersion string `json:"appVersion"`
+ ServerName string `json:"serverName"`
+ DistributedTraceId *uuid.UUID `json:"distributedTraceId,omitempty"`
+}
+
+// LinkedException is the exception/message summary attached to endpoint, task,
+// and distributed-trace detail responses (backend EndpointExceptionInfo).
+// RecordedAt is a preformatted RFC3339 string, matching the server.
+type LinkedException struct {
+ ExceptionHash string `json:"exceptionHash"`
+ StackTrace string `json:"stackTrace"`
+ RecordedAt string `json:"recordedAt"`
+}
+
+// LinkedMessage is a captured message (non-error exception) linked to an
+// endpoint or task (backend EndpointMessageInfo).
+type LinkedMessage struct {
+ Id uuid.UUID `json:"id"`
+ ExceptionHash string `json:"exceptionHash"`
+ StackTrace string `json:"stackTrace"`
+ RecordedAt string `json:"recordedAt"`
+ Attributes map[string]string `json:"attributes,omitempty"`
+}
+
+// TaskDetailResponse is the body of POST /api/tasks/:taskId.
+type TaskDetailResponse struct {
+ Task *Task `json:"task"`
+ Spans []Span `json:"spans"`
+ HasSpans bool `json:"hasSpans"`
+ Exception *LinkedException `json:"exception,omitempty"`
+ Messages []LinkedMessage `json:"messages"`
+}
+
+// GetTask returns one task run plus its spans and linked exceptions/messages.
+// recordedAt should be the task's recordedAt (from a notification, the URL's
+// t= param, or a distributed-trace node) so the lookup prunes partitions.
+func (c *Client) GetTask(ctx context.Context, projectID, id string, recordedAt time.Time) (*TaskDetailResponse, error) {
+ path := "/api/tasks/" + url.PathEscape(id) + "?projectId=" + url.QueryEscape(projectID)
+ var resp TaskDetailResponse
+ if err := c.do(ctx, http.MethodPost, path, recordedAtBody{RecordedAt: recordedAt}, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
+
+// AiTraceDetailResponse is the body of POST /api/ai-traces/:traceId. The
+// conversation blob is passed through verbatim (server stores it opaquely).
+type AiTraceDetailResponse struct {
+ AiTrace *AiTrace `json:"aiTrace"`
+ Conversation json.RawMessage `json:"conversation,omitempty"`
+}
+
+// GetAiTrace returns one AI trace plus its stored conversation. recordedAt is
+// the trace's recordedAt and is required for a fast (partition-pruned) lookup.
+func (c *Client) GetAiTrace(ctx context.Context, projectID, id string, recordedAt time.Time) (*AiTraceDetailResponse, error) {
+ path := "/api/ai-traces/" + url.PathEscape(id) + "?projectId=" + url.QueryEscape(projectID)
+ var resp AiTraceDetailResponse
+ if err := c.do(ctx, http.MethodPost, path, recordedAtBody{RecordedAt: recordedAt}, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
+
+// SessionLinkedException is one exception/message that fired during a session
+// (backend SessionExceptionInfo). Unlike LinkedException it carries isMessage.
+type SessionLinkedException struct {
+ Id uuid.UUID `json:"id"`
+ ExceptionHash string `json:"exceptionHash"`
+ StackTrace string `json:"stackTrace"`
+ RecordedAt string `json:"recordedAt"`
+ IsMessage bool `json:"isMessage"`
+}
+
+// SessionDetailResponse is the body of POST /api/sessions/:sessionId.
+type SessionDetailResponse struct {
+ Session *Session `json:"session"`
+ Exceptions []SessionLinkedException `json:"exceptions"`
+}
+
+// GetSession returns one session plus the exceptions that fired during it.
+// startedAt (not recordedAt) bounds the lookup — the sessions table is
+// partitioned on started_at. Use the session's startedAt, or the recordedAt of
+// a linked exception occurrence, which falls inside the ±24h window.
+func (c *Client) GetSession(ctx context.Context, projectID, id string, startedAt time.Time) (*SessionDetailResponse, error) {
+ path := "/api/sessions/" + url.PathEscape(id) + "?projectId=" + url.QueryEscape(projectID)
+ var resp SessionDetailResponse
+ if err := c.do(ctx, http.MethodPost, path, startedAtBody{StartedAt: startedAt}, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
+
+// DistributedTraceNode is one resource (endpoint/task/ai-trace/exception) that
+// participated in a distributed trace, scoped to its originating project.
+type DistributedTraceNode struct {
+ ProjectId uuid.UUID `json:"projectId"`
+ ProjectName string `json:"projectName"`
+ TraceType string `json:"traceType"`
+ Endpoint *Endpoint `json:"endpoint,omitempty"`
+ Task *Task `json:"task,omitempty"`
+ AiTrace *AiTrace `json:"aiTrace,omitempty"`
+ Spans []Span `json:"spans"`
+ Exception *LinkedException `json:"exception,omitempty"`
+}
+
+// DistributedTraceResponse is the body of POST /api/distributed-traces/:id —
+// the full cross-service request timeline, the highest-value RCA view.
+type DistributedTraceResponse struct {
+ DistributedTraceId string `json:"distributedTraceId"`
+ Nodes []DistributedTraceNode `json:"nodes"`
+}
+
+// GetDistributedTrace returns every node sharing a distributed trace id across
+// all projects the user can see. The route resolves projects from the JWT, so
+// no projectId query param is sent. recordedAt bounds the lookup to ±48h.
+func (c *Client) GetDistributedTrace(ctx context.Context, id string, recordedAt time.Time) (*DistributedTraceResponse, error) {
+ path := "/api/distributed-traces/" + url.PathEscape(id)
+ var resp DistributedTraceResponse
+ if err := c.do(ctx, http.MethodPost, path, recordedAtBody{RecordedAt: recordedAt}, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
diff --git a/cli/pkg/client/detail_test.go b/cli/pkg/client/detail_test.go
new file mode 100644
index 00000000..394da5a4
--- /dev/null
+++ b/cli/pkg/client/detail_test.go
@@ -0,0 +1,193 @@
+package client
+
+import (
+ "context"
+ "encoding/json"
+ "net/http"
+ "net/http/httptest"
+ "testing"
+ "time"
+)
+
+// ts is a fixed RFC3339 timestamp used across the detail tests.
+var ts = time.Date(2026, 6, 23, 14, 30, 0, 0, time.UTC)
+
+func TestGetExceptionById_postsRecordedAtAndProjectId(t *testing.T) {
+ var gotPath, gotProject string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ t.Errorf("method = %q", r.Method)
+ }
+ gotPath = r.URL.Path
+ gotProject = r.URL.Query().Get("projectId")
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"exception":{"id":"00000000-0000-0000-0000-000000000001","exceptionHash":"h","stackTrace":"x","recordedAt":"2026-06-23T14:30:00Z"},"sessionId":"00000000-0000-0000-0000-0000000000aa"}`))
+ }))
+ defer srv.Close()
+
+ c := New(srv.URL, WithJWT("tok"))
+ resp, err := c.GetExceptionById(context.Background(), "proj-1", "00000000-0000-0000-0000-000000000001", ts)
+ if err != nil {
+ t.Fatalf("GetExceptionById: %v", err)
+ }
+ if gotPath != "/api/exception-stack-traces/by-id/00000000-0000-0000-0000-000000000001" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotProject != "proj-1" {
+ t.Errorf("projectId = %q", gotProject)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt = %v", gotBody["recordedAt"])
+ }
+ if resp.Exception == nil || resp.SessionId == nil {
+ t.Errorf("expected exception + sessionId, got %+v", resp)
+ }
+}
+
+func TestGetEndpoint_postsRecordedAtAndProjectId(t *testing.T) {
+ var gotPath, gotProject string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ gotProject = r.URL.Query().Get("projectId")
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"endpoint":{"id":"00000000-0000-0000-0000-000000000002","endpoint":"GET /x","recordedAt":"2026-06-23T14:30:00Z"},"spans":[{"id":"00000000-0000-0000-0000-0000000000b1","name":"db"}],"hasSpans":true,"messages":[]}`))
+ }))
+ defer srv.Close()
+
+ c := New(srv.URL, WithJWT("tok"))
+ resp, err := c.GetEndpoint(context.Background(), "proj-1", "00000000-0000-0000-0000-000000000002", ts)
+ if err != nil {
+ t.Fatalf("GetEndpoint: %v", err)
+ }
+ if gotPath != "/api/endpoints/00000000-0000-0000-0000-000000000002" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotProject != "proj-1" {
+ t.Errorf("projectId = %q", gotProject)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt = %v", gotBody["recordedAt"])
+ }
+ if resp.Endpoint == nil || resp.Endpoint.Endpoint != "GET /x" {
+ t.Errorf("endpoint missing/wrong: %+v", resp.Endpoint)
+ }
+ if len(resp.Spans) != 1 || !resp.HasSpans {
+ t.Errorf("spans = %+v hasSpans=%v", resp.Spans, resp.HasSpans)
+ }
+}
+
+func TestGetTask_postsRecordedAt(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"task":{"id":"00000000-0000-0000-0000-000000000003","taskName":"nightly","recordedAt":"2026-06-23T14:30:00Z"},"spans":[],"hasSpans":false,"messages":[]}`))
+ }))
+ defer srv.Close()
+
+ c := New(srv.URL, WithJWT("tok"))
+ resp, err := c.GetTask(context.Background(), "proj-1", "00000000-0000-0000-0000-000000000003", ts)
+ if err != nil {
+ t.Fatalf("GetTask: %v", err)
+ }
+ if gotPath != "/api/tasks/00000000-0000-0000-0000-000000000003" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt = %v", gotBody["recordedAt"])
+ }
+ if resp.Task == nil || resp.Task.TaskName != "nightly" {
+ t.Errorf("task missing/wrong: %+v", resp.Task)
+ }
+}
+
+func TestGetAiTrace_postsRecordedAt(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"aiTrace":{"id":"00000000-0000-0000-0000-000000000004","traceName":"chat","model":"claude","recordedAt":"2026-06-23T14:30:00Z"},"conversation":[{"role":"user"}]}`))
+ }))
+ defer srv.Close()
+
+ c := New(srv.URL, WithJWT("tok"))
+ resp, err := c.GetAiTrace(context.Background(), "proj-1", "00000000-0000-0000-0000-000000000004", ts)
+ if err != nil {
+ t.Fatalf("GetAiTrace: %v", err)
+ }
+ if gotPath != "/api/ai-traces/00000000-0000-0000-0000-000000000004" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt = %v", gotBody["recordedAt"])
+ }
+ if resp.AiTrace == nil || resp.AiTrace.Model != "claude" {
+ t.Errorf("aiTrace missing/wrong: %+v", resp.AiTrace)
+ }
+ if len(resp.Conversation) == 0 {
+ t.Errorf("expected conversation passthrough")
+ }
+}
+
+func TestGetSession_postsStartedAt(t *testing.T) {
+ var gotPath string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"session":{"id":"00000000-0000-0000-0000-000000000005","startedAt":"2026-06-23T14:30:00Z"},"exceptions":[{"id":"00000000-0000-0000-0000-0000000000c1","exceptionHash":"h","stackTrace":"x","recordedAt":"2026-06-23T14:31:00Z","isMessage":false}]}`))
+ }))
+ defer srv.Close()
+
+ c := New(srv.URL, WithJWT("tok"))
+ resp, err := c.GetSession(context.Background(), "proj-1", "00000000-0000-0000-0000-000000000005", ts)
+ if err != nil {
+ t.Fatalf("GetSession: %v", err)
+ }
+ if gotPath != "/api/sessions/00000000-0000-0000-0000-000000000005" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotBody["startedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("startedAt = %v (want startedAt, not recordedAt)", gotBody["startedAt"])
+ }
+ if gotBody["recordedAt"] != nil {
+ t.Errorf("session body should not carry recordedAt: %v", gotBody)
+ }
+ if resp.Session == nil || len(resp.Exceptions) != 1 {
+ t.Errorf("session/exceptions wrong: %+v", resp)
+ }
+}
+
+func TestGetDistributedTrace_noProjectIdQueryParam(t *testing.T) {
+ var gotPath, gotRawQuery string
+ var gotBody map[string]any
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ gotRawQuery = r.URL.RawQuery
+ _ = json.NewDecoder(r.Body).Decode(&gotBody)
+ _, _ = w.Write([]byte(`{"distributedTraceId":"00000000-0000-0000-0000-000000000006","nodes":[{"projectName":"api","traceType":"endpoint","endpoint":{"id":"00000000-0000-0000-0000-0000000000d1","endpoint":"GET /x"},"spans":[]}]}`))
+ }))
+ defer srv.Close()
+
+ c := New(srv.URL, WithJWT("tok"))
+ resp, err := c.GetDistributedTrace(context.Background(), "00000000-0000-0000-0000-000000000006", ts)
+ if err != nil {
+ t.Fatalf("GetDistributedTrace: %v", err)
+ }
+ if gotPath != "/api/distributed-traces/00000000-0000-0000-0000-000000000006" {
+ t.Errorf("path = %q", gotPath)
+ }
+ if gotRawQuery != "" {
+ t.Errorf("distributed-traces must not send a query string, got %q", gotRawQuery)
+ }
+ if gotBody["recordedAt"] != "2026-06-23T14:30:00Z" {
+ t.Errorf("recordedAt = %v", gotBody["recordedAt"])
+ }
+ if len(resp.Nodes) != 1 || resp.Nodes[0].TraceType != "endpoint" {
+ t.Errorf("nodes wrong: %+v", resp.Nodes)
+ }
+}
diff --git a/cli/pkg/client/endpoints.go b/cli/pkg/client/endpoints.go
index 9dcc8c36..d63629ec 100644
--- a/cli/pkg/client/endpoints.go
+++ b/cli/pkg/client/endpoints.go
@@ -5,6 +5,8 @@ import (
"net/http"
"net/url"
"time"
+
+ "github.com/google/uuid"
)
// EndpointStats matches the upstream models.EndpointStats. Durations are
@@ -58,3 +60,46 @@ func (c *Client) ListEndpoints(ctx context.Context, projectID string, req ListEn
}
return &resp, nil
}
+
+// Endpoint mirrors models.Endpoint — one request (transaction), as returned by
+// the by-id detail endpoint. EndpointStats (above) is the grouped/list shape;
+// this is the single-row shape keyed by the transaction's id.
+type Endpoint struct {
+ Id uuid.UUID `json:"id"`
+ ProjectId uuid.UUID `json:"projectId"`
+ Endpoint string `json:"endpoint"`
+ Duration time.Duration `json:"duration"`
+ RecordedAt time.Time `json:"recordedAt"`
+ StatusCode int16 `json:"statusCode"`
+ BodySize int32 `json:"bodySize"`
+ ClientIP string `json:"clientIP"`
+ Attributes map[string]string `json:"attributes"`
+ AppVersion string `json:"appVersion"`
+ ServerName string `json:"serverName"`
+ DistributedTraceId *uuid.UUID `json:"distributedTraceId,omitempty"`
+ SpanId *uuid.UUID `json:"spanId,omitempty"`
+ IsStream bool `json:"isStream"`
+ IsRoot bool `json:"isRoot"`
+}
+
+// EndpointDetailResponse is the body of POST /api/endpoints/:endpointId.
+type EndpointDetailResponse struct {
+ Endpoint *Endpoint `json:"endpoint"`
+ Spans []Span `json:"spans"`
+ HasSpans bool `json:"hasSpans"`
+ Exception *LinkedException `json:"exception,omitempty"`
+ Messages []LinkedMessage `json:"messages"`
+}
+
+// GetEndpoint returns one request (transaction) by id plus its spans and any
+// linked exception/messages. recordedAt is the transaction's recordedAt and is
+// required for a partition-pruned lookup; without it the server scans every
+// daily partition of the endpoints table.
+func (c *Client) GetEndpoint(ctx context.Context, projectID, id string, recordedAt time.Time) (*EndpointDetailResponse, error) {
+ path := "/api/endpoints/" + url.PathEscape(id) + "?projectId=" + url.QueryEscape(projectID)
+ var resp EndpointDetailResponse
+ if err := c.do(ctx, http.MethodPost, path, recordedAtBody{RecordedAt: recordedAt}, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
diff --git a/cli/pkg/client/exceptions.go b/cli/pkg/client/exceptions.go
index a59989f0..d844e0d2 100644
--- a/cli/pkg/client/exceptions.go
+++ b/cli/pkg/client/exceptions.go
@@ -2,6 +2,7 @@ package client
import (
"context"
+ "encoding/json"
"net/http"
"net/url"
"time"
@@ -31,7 +32,7 @@ type ExceptionTrendPoint struct {
// the body — the upstream RequireProjectAccess middleware reads it via
// c.Query("projectId").
type ListExceptionsRequest struct {
- TimeRange TimeRange `json:"-"` // serialized as fromDate/toDate via MarshalJSON
+ TimeRange TimeRange `json:"-"` // serialized as fromDate/toDate via MarshalJSON
Pagination PaginationParams `json:"pagination"`
OrderBy string `json:"orderBy,omitempty"`
Search string `json:"search,omitempty"`
@@ -110,6 +111,30 @@ func (c *Client) GetException(ctx context.Context, projectID, hash string, page
return &resp, nil
}
+// ExceptionByIdResponse is the body of POST
+// /api/exception-stack-traces/by-id/:exceptionId. Over a paginated `exceptions
+// show <hash>` occurrence it adds the linked sessionId and an inline
+// sessionRecording blob (passed through verbatim), and resolves directly
+// without walking pages.
+type ExceptionByIdResponse struct {
+ Exception *ExceptionStackTrace `json:"exception"`
+ SessionId *uuid.UUID `json:"sessionId,omitempty"`
+ SessionRecording json.RawMessage `json:"sessionRecording,omitempty"`
+}
+
+// GetExceptionById returns a single exception occurrence by its id. recordedAt
+// is the occurrence's recordedAt (from the URL's t= param, a notification's
+// "Occurred at", or an `exceptions show` occurrence) and is required for a
+// partition-pruned lookup.
+func (c *Client) GetExceptionById(ctx context.Context, projectID, id string, recordedAt time.Time) (*ExceptionByIdResponse, error) {
+ path := "/api/exception-stack-traces/by-id/" + url.PathEscape(id) + "?projectId=" + url.QueryEscape(projectID)
+ var resp ExceptionByIdResponse
+ if err := c.do(ctx, http.MethodPost, path, recordedAtBody{RecordedAt: recordedAt}, &resp); err != nil {
+ return nil, err
+ }
+ return &resp, nil
+}
+
// archiveRequest is the body for POST /api/exception-stack-traces/archive
// and .../unarchive. Same shape for both routes.
type archiveRequest struct {
diff --git a/cli/test/contract/.gitignore b/cli/test/contract/.gitignore
new file mode 100644
index 00000000..87f57804
--- /dev/null
+++ b/cli/test/contract/.gitignore
@@ -0,0 +1,5 @@
+storage/
+twcache/
+*.db
+*.db-shm
+*.db-wal
diff --git a/cli/test/contract/contract_test.go b/cli/test/contract/contract_test.go
new file mode 100644
index 00000000..f4646eeb
--- /dev/null
+++ b/cli/test/contract/contract_test.go
@@ -0,0 +1,209 @@
+package contract
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+ "time"
+
+ client "github.com/tracewayapp/traceway/cli/pkg/client"
+)
+
+// timeWindow brackets the seeded instant so list/query endpoints return it.
+func timeWindow() client.TimeRange {
+ return client.TimeRangeFromExplicit(seedAt.Add(-time.Hour), seedAt.Add(time.Hour))
+}
+
+// Each endpoint is driven through the real CLI client (so the request encoding
+// is the contract under test) while a capturing transport snapshots the raw
+// response for the wire-shape golden.
+
+func TestContract_login(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.Login(context.Background(), seedEmail, seedPassword); err != nil {
+ t.Fatalf("login: %v", err)
+ }
+ goldenAssert(t, "login", rt.body)
+}
+
+func TestContract_projectsList(t *testing.T) {
+ c, rt := capturedClient()
+ projects, err := c.ListProjects(context.Background())
+ if err != nil {
+ t.Fatalf("projects: %v", err)
+ }
+ if len(projects) == 0 {
+ t.Fatal("expected at least one project")
+ }
+ goldenAssert(t, "projects-list", rt.body)
+}
+
+func TestContract_endpointsGrouped(t *testing.T) {
+ c, rt := capturedClient()
+ resp, err := c.ListEndpoints(context.Background(), projectID, client.ListEndpointsRequest{
+ TimeRange: timeWindow(),
+ Pagination: client.PaginationParams{Page: 1, PageSize: 50},
+ OrderBy: "impact",
+ })
+ if err != nil {
+ t.Fatalf("endpoints grouped: %v", err)
+ }
+ if len(resp.Data) == 0 {
+ t.Fatal("expected seeded endpoint in response")
+ }
+ goldenAssert(t, "endpoints-grouped", rt.body)
+}
+
+func TestContract_endpointDetail(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.GetEndpoint(context.Background(), projectID, seedEndpointID.String(), seedAt); err != nil {
+ t.Fatalf("endpoint detail: %v", err)
+ }
+ goldenAssert(t, "endpoint-detail", rt.body)
+}
+
+func TestContract_exceptionsGrouped(t *testing.T) {
+ c, rt := capturedClient()
+ resp, err := c.ListExceptions(context.Background(), projectID, client.ListExceptionsRequest{
+ TimeRange: timeWindow(),
+ Pagination: client.PaginationParams{Page: 1, PageSize: 50},
+ OrderBy: "lastSeen",
+ })
+ if err != nil {
+ t.Fatalf("exceptions grouped: %v", err)
+ }
+ if len(resp.Data) == 0 {
+ t.Fatal("expected seeded exception group in response")
+ }
+ goldenAssert(t, "exceptions-grouped", rt.body)
+}
+
+func TestContract_exceptionByHash(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.GetException(context.Background(), projectID, seedHash, client.PaginationParams{Page: 1, PageSize: 20}); err != nil {
+ t.Fatalf("exception by hash: %v", err)
+ }
+ goldenAssert(t, "exception-by-hash", rt.body)
+}
+
+func TestContract_exceptionById(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.GetExceptionById(context.Background(), projectID, seedExceptionID.String(), seedAt); err != nil {
+ t.Fatalf("exception by id: %v", err)
+ }
+ goldenAssert(t, "exception-by-id", rt.body)
+}
+
+func TestContract_exceptionArchiveRoundTrip(t *testing.T) {
+ c := client.New(baseURL, client.WithJWT(jwtToken))
+ ctx := context.Background()
+ if err := c.ArchiveExceptions(ctx, projectID, []string{seedHash}); err != nil {
+ t.Fatalf("archive: %v", err)
+ }
+ // Restore state so other tests still see the (unarchived) exception.
+ if err := c.UnarchiveExceptions(ctx, projectID, []string{seedHash}); err != nil {
+ t.Fatalf("unarchive: %v", err)
+ }
+}
+
+func TestContract_logsQuery(t *testing.T) {
+ c, rt := capturedClient()
+ resp, err := c.QueryLogs(context.Background(), projectID, client.QueryLogsRequest{
+ TimeRange: timeWindow(),
+ Pagination: client.PaginationParams{Page: 1, PageSize: 50},
+ })
+ if err != nil {
+ t.Fatalf("logs query: %v", err)
+ }
+ if len(resp.Data) == 0 {
+ t.Fatal("expected seeded log record in response")
+ }
+ goldenAssert(t, "logs-query", rt.body)
+}
+
+func TestContract_metricsQuery(t *testing.T) {
+ c, rt := capturedClient()
+ resp, err := c.QueryMetrics(context.Background(), projectID, client.QueryMetricsRequest{
+ TimeRange: timeWindow(),
+ IntervalMinutes: 60,
+ Queries: []client.MetricQueryItem{
+ {Name: seedMetricName, Aggregation: "avg"},
+ },
+ })
+ if err != nil {
+ t.Fatalf("metrics query: %v", err)
+ }
+ if !hasMetricValue(resp, seedMetricVal) {
+ t.Fatalf("seeded metric value %v not found in response: %+v", seedMetricVal, resp)
+ }
+ goldenAssert(t, "metrics-query", rt.body)
+}
+
+func TestContract_taskDetail(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.GetTask(context.Background(), projectID, seedTaskID.String(), seedAt); err != nil {
+ t.Fatalf("task detail: %v", err)
+ }
+ goldenAssert(t, "task-detail", rt.body)
+}
+
+func TestContract_aiTraceDetail(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.GetAiTrace(context.Background(), projectID, seedAiTraceID.String(), seedAt); err != nil {
+ t.Fatalf("ai trace detail: %v", err)
+ }
+ goldenAssert(t, "aitrace-detail", rt.body)
+}
+
+func TestContract_sessionDetail(t *testing.T) {
+ c, rt := capturedClient()
+ if _, err := c.GetSession(context.Background(), projectID, seedSessionID.String(), seedAt); err != nil {
+ t.Fatalf("session detail: %v", err)
+ }
+ goldenAssert(t, "session-detail", rt.body)
+}
+
+func TestContract_distributedTrace(t *testing.T) {
+ c, rt := capturedClient()
+ resp, err := c.GetDistributedTrace(context.Background(), seedTraceID.String(), seedAt)
+ if err != nil {
+ t.Fatalf("distributed trace: %v", err)
+ }
+ if len(resp.Nodes) == 0 {
+ t.Fatal("expected seeded nodes in distributed trace")
+ }
+ goldenAssert(t, "distributed-trace", rt.body)
+}
+
+// TestContract_cliMetricsValueRoundTrip drives the actual binary end to end and
+// asserts the seeded value surfaces. With the lowercase json tags on
+// TimeSeriesPoint this decodes by exact tag; the wire-shape golden above is what
+// pins the casing so a regression to PascalCase would be caught.
+func TestContract_cliMetricsValueRoundTrip(t *testing.T) {
+ stdout, stderr, code := runCLI(t, "",
+ "metrics", "query", "--name", seedMetricName, "--aggregation", "avg",
+ "--since", "24h", "--interval-minutes", "60", "--output", "json")
+ if code != 0 {
+ t.Fatalf("metrics query exit %d\nstderr: %s", code, stderr)
+ }
+ var resp client.QueryMetricsResponse
+ if err := json.Unmarshal([]byte(stdout), &resp); err != nil {
+ t.Fatalf("metrics output not JSON: %v\n%s", err, stdout)
+ }
+ if !hasMetricValue(&resp, seedMetricVal) {
+ t.Fatalf("CLI metrics output missing seeded value %v: %s", seedMetricVal, stdout)
+ }
+}
+
+func hasMetricValue(resp *client.QueryMetricsResponse, want float64) bool {
+ for _, r := range resp.Results {
+ for _, points := range r.Series {
+ for _, p := range points {
+ if p.Value == want {
+ return true
+ }
+ }
+ }
+ }
+ return false
+}
diff --git a/cli/test/contract/go.mod b/cli/test/contract/go.mod
new file mode 100644
index 00000000..f1d587f7
--- /dev/null
+++ b/cli/test/contract/go.mod
@@ -0,0 +1,118 @@
+module github.com/tracewayapp/traceway/cli/test/contract
+
+go 1.26.2
+
+require (
+ github.com/google/uuid v1.6.0
+ github.com/tracewayapp/traceway/backend v0.0.0
+ github.com/tracewayapp/traceway/cli v0.0.0
+)
+
+require (
+ cloud.google.com/go/compute/metadata v0.9.0 // indirect
+ github.com/ClickHouse/ch-go v0.69.0 // indirect
+ github.com/ClickHouse/clickhouse-go/v2 v2.42.0 // indirect
+ github.com/andybalholm/brotli v1.2.0 // indirect
+ github.com/aws/aws-sdk-go-v2 v1.41.1 // indirect
+ github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.4 // indirect
+ github.com/aws/aws-sdk-go-v2/config v1.32.7 // indirect
+ github.com/aws/aws-sdk-go-v2/credentials v1.19.7 // indirect
+ github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.17 // indirect
+ github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17 // indirect
+ github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17 // indirect
+ github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 // indirect
+ github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.17 // indirect
+ github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.4 // indirect
+ github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.8 // indirect
+ github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.17 // indirect
+ github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.17 // indirect
+ github.com/aws/aws-sdk-go-v2/service/s3 v1.96.0 // indirect
+ github.com/aws/aws-sdk-go-v2/service/signin v1.0.5 // indirect
+ github.com/aws/aws-sdk-go-v2/service/sso v1.30.9 // indirect
+ github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.13 // indirect
+ github.com/aws/aws-sdk-go-v2/service/sts v1.41.6 // indirect
+ github.com/aws/smithy-go v1.24.0 // indirect
+ github.com/bytedance/sonic v1.14.0 // indirect
+ github.com/bytedance/sonic/loader v0.3.0 // indirect
+ github.com/cespare/xxhash/v2 v2.3.0 // indirect
+ github.com/cloudwego/base64x v0.1.6 // indirect
+ github.com/coreos/go-systemd/v22 v22.6.0 // indirect
+ github.com/dop251/goja v0.0.0-20260607120635-348e6bea910d // indirect
+ github.com/gabriel-vasile/mimetype v1.4.8 // indirect
+ github.com/gin-contrib/sse v1.1.0 // indirect
+ github.com/gin-gonic/gin v1.11.0 // indirect
+ github.com/go-chi/chi/v5 v5.2.2 // indirect
+ github.com/go-faster/city v1.0.1 // indirect
+ github.com/go-faster/errors v0.7.1 // indirect
+ github.com/go-playground/locales v0.14.1 // indirect
+ github.com/go-playground/universal-translator v0.18.1 // indirect
+ github.com/go-playground/validator/v10 v10.27.0 // indirect
+ github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect
+ github.com/goccy/go-json v0.10.2 // indirect
+ github.com/goccy/go-yaml v1.19.2 // indirect
+ github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
+ github.com/golang-migrate/migrate/v4 v4.19.1 // indirect
+ github.com/google/pprof v0.0.0-20260604005048-7023385849c0 // indirect
+ github.com/gorilla/mux v1.7.4 // indirect
+ github.com/gorilla/securecookie v1.1.2 // indirect
+ github.com/gorilla/sessions v1.4.0 // indirect
+ github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
+ github.com/joho/godotenv v1.5.1 // indirect
+ github.com/json-iterator/go v1.1.12 // indirect
+ github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
+ github.com/klauspost/compress v1.18.0 // indirect
+ github.com/klauspost/cpuid/v2 v2.3.0 // indirect
+ github.com/leodido/go-urn v1.4.0 // indirect
+ github.com/lib/pq v1.10.9 // indirect
+ github.com/markbates/goth v1.82.0 // indirect
+ github.com/mattn/go-isatty v0.0.20 // indirect
+ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+ github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
+ github.com/paulmach/orb v0.12.0 // indirect
+ github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+ github.com/pierrec/lz4/v4 v4.1.22 // indirect
+ github.com/quic-go/qpack v0.5.1 // indirect
+ github.com/quic-go/quic-go v0.54.0 // indirect
+ github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0 // indirect
+ github.com/segmentio/asm v1.2.1 // indirect
+ github.com/shopspring/decimal v1.4.0 // indirect
+ github.com/tracewayapp/lit/v2 v2.0.2 // indirect
+ github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+ github.com/ugorji/go/codec v1.3.0 // indirect
+ go.opentelemetry.io/otel v1.44.0 // indirect
+ go.opentelemetry.io/otel/trace v1.44.0 // indirect
+ go.opentelemetry.io/proto/otlp v1.10.0 // indirect
+ go.opentelemetry.io/proto/otlp/collector/profiles/v1development v0.3.0 // indirect
+ go.opentelemetry.io/proto/otlp/profiles/v1development v0.3.0 // indirect
+ go.tracewayapp.com v1.0.2 // indirect
+ go.tracewayapp.com/tracewaygin v1.0.2 // indirect
+ go.uber.org/mock v0.5.0 // indirect
+ go.yaml.in/yaml/v3 v3.0.4 // indirect
+ golang.org/x/arch v0.20.0 // indirect
+ golang.org/x/crypto v0.51.0 // indirect
+ golang.org/x/mod v0.35.0 // indirect
+ golang.org/x/net v0.55.0 // indirect
+ golang.org/x/oauth2 v0.36.0 // indirect
+ golang.org/x/sync v0.20.0 // indirect
+ golang.org/x/sys v0.45.0 // indirect
+ golang.org/x/text v0.37.0 // indirect
+ golang.org/x/tools v0.44.0 // indirect
+ google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171 // indirect
+ google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 // indirect
+ google.golang.org/grpc v1.81.1 // indirect
+ google.golang.org/protobuf v1.36.11 // indirect
+ lukechampine.com/uint128 v1.2.0 // indirect
+ modernc.org/cc/v3 v3.36.3 // indirect
+ modernc.org/ccgo/v3 v3.16.9 // indirect
+ modernc.org/libc v1.17.1 // indirect
+ modernc.org/mathutil v1.5.0 // indirect
+ modernc.org/memory v1.2.1 // indirect
+ modernc.org/opt v0.1.3 // indirect
+ modernc.org/sqlite v1.18.1 // indirect
+ modernc.org/strutil v1.1.3 // indirect
+ modernc.org/token v1.0.0 // indirect
+)
+
+replace github.com/tracewayapp/traceway/cli => ../..
+
+replace github.com/tracewayapp/traceway/backend => ../../../backend
diff --git a/cli/test/contract/go.sum b/cli/test/contract/go.sum
new file mode 100644
index 00000000..1899f880
--- /dev/null
+++ b/cli/test/contract/go.sum
@@ -0,0 +1,390 @@
+cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
+cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
+github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 h1:L/gRVlceqvL25UVaW/CKtUDjefjrs0SPonmDGUVOYP0=
+github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/ClickHouse/ch-go v0.69.0 h1:nO0OJkpxOlN/eaXFj0KzjTz5p7vwP1/y3GN4qc5z/iM=
+github.com/ClickHouse/ch-go v0.69.0/go.mod h1:9XeZpSAT4S0kVjOpaJ5186b7PY/NH/hhF8R6u0WIjwg=
+github.com/ClickHouse/clickhouse-go v1.4.3 h1:iAFMa2UrQdR5bHJ2/yaSLffZkxpcOYQMCUuKeNXGdqc=
+github.com/ClickHouse/clickhouse-go v1.4.3/go.mod h1:EaI/sW7Azgz9UATzd5ZdZHRUhHgv5+JMS9NSr2smCJI=
+github.com/ClickHouse/clickhouse-go/v2 v2.42.0 h1:MdujEfIrpXesQUH0k0AnuVtJQXk6RZmxEhsKUCcv5xk=
+github.com/ClickHouse/clickhouse-go/v2 v2.42.0/go.mod h1:riWnuo4YMVdajYll0q6FzRBomdyCrXyFY3VXeXczA8s=
+github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
+github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/aws/aws-sdk-go-v2 v1.41.1 h1:ABlyEARCDLN034NhxlRUSZr4l71mh+T5KAeGh6cerhU=
+github.com/aws/aws-sdk-go-v2 v1.41.1/go.mod h1:MayyLB8y+buD9hZqkCW3kX1AKq07Y5pXxtgB+rRFhz0=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.4 h1:489krEF9xIGkOaaX3CE/Be2uWjiXrkCH6gUX+bZA/BU=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.4/go.mod h1:IOAPF6oT9KCsceNTvvYMNHy0+kMF8akOjeDvPENWxp4=
+github.com/aws/aws-sdk-go-v2/config v1.32.7 h1:vxUyWGUwmkQ2g19n7JY/9YL8MfAIl7bTesIUykECXmY=
+github.com/aws/aws-sdk-go-v2/config v1.32.7/go.mod h1:2/Qm5vKUU/r7Y+zUk/Ptt2MDAEKAfUtKc1+3U1Mo3oY=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.7 h1:tHK47VqqtJxOymRrNtUXN5SP/zUTvZKeLx4tH6PGQc8=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.7/go.mod h1:qOZk8sPDrxhf+4Wf4oT2urYJrYt3RejHSzgAquYeppw=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.17 h1:I0GyV8wiYrP8XpA70g1HBcQO1JlQxCMTW9npl5UbDHY=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.17/go.mod h1:tyw7BOl5bBe/oqvoIeECFJjMdzXoa/dfVz3QQ5lgHGA=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17 h1:xOLELNKGp2vsiteLsvLPwxC+mYmO6OZ8PYgiuPJzF8U=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.17/go.mod h1:5M5CI3D12dNOtH3/mk6minaRwI2/37ifCURZISxA/IQ=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17 h1:WWLqlh79iO48yLkj1v3ISRNiv+3KdQoZ6JWyfcsyQik=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.17/go.mod h1:EhG22vHRrvF8oXSTYStZhJc1aUgKtnJe+aOiFEV90cM=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4 h1:WKuaxf++XKWlHWu9ECbMlha8WOEGm0OUEZqm4K/Gcfk=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.4/go.mod h1:ZWy7j6v1vWGmPReu0iSGvRiise4YI5SkR3OHKTZ6Wuc=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.17 h1:JqcdRG//czea7Ppjb+g/n4o8i/R50aTBHkA7vu0lK+k=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.17/go.mod h1:CO+WeGmIdj/MlPel2KwID9Gt7CNq4M65HUfBW97liM0=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.4 h1:0ryTNEdJbzUCEWkVXEXoqlXV72J5keC1GvILMOuD00E=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.4/go.mod h1:HQ4qwNZh32C3CBeO6iJLQlgtMzqeG17ziAA/3KDJFow=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.8 h1:Z5EiPIzXKewUQK0QTMkutjiaPVeVYXX7KIqhXu/0fXs=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.9.8/go.mod h1:FsTpJtvC4U1fyDXk7c71XoDv3HlRm8V3NiYLeYLh5YE=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.17 h1:RuNSMoozM8oXlgLG/n6WLaFGoea7/CddrCfIiSA+xdY=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.17/go.mod h1:F2xxQ9TZz5gDWsclCtPQscGpP0VUOc8RqgFM3vDENmU=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.17 h1:bGeHBsGZx0Dvu/eJC0Lh9adJa3M1xREcndxLNZlve2U=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.19.17/go.mod h1:dcW24lbU0CzHusTE8LLHhRLI42ejmINN8Lcr22bwh/g=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.96.0 h1:oeu8VPlOre74lBA/PMhxa5vewaMIMmILM+RraSyB8KA=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.96.0/go.mod h1:5jggDlZ2CLQhwJBiZJb4vfk4f0GxWdEDruWKEJ1xOdo=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.5 h1:VrhDvQib/i0lxvr3zqlUwLwJP4fpmpyD9wYG1vfSu+Y=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.5/go.mod h1:k029+U8SY30/3/ras4G/Fnv/b88N4mAfliNn08Dem4M=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.9 h1:v6EiMvhEYBoHABfbGB4alOYmCIrcgyPPiBE1wZAEbqk=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.9/go.mod h1:yifAsgBxgJWn3ggx70A3urX2AN49Y5sJTD1UQFlfqBw=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.13 h1:gd84Omyu9JLriJVCbGApcLzVR3XtmC4ZDPcAI6Ftvds=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.13/go.mod h1:sTGThjphYE4Ohw8vJiRStAcu3rbjtXRsdNB0TvZ5wwo=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.6 h1:5fFjR/ToSOzB2OQ/XqWpZBmNvmP/pJ1jOWYlFDJTjRQ=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.6/go.mod h1:qgFDZQSD/Kys7nJnVqYlWKnh0SSdMjAi0uSwON4wgYQ=
+github.com/aws/smithy-go v1.24.0 h1:LpilSUItNPFr1eY85RYgTIg5eIEPtvFbskaFcmmIUnk=
+github.com/aws/smithy-go v1.24.0/go.mod h1:LEj2LM3rBRQJxPZTB4KuzZkaZYnZPnvgIhb4pu07mx0=
+github.com/bytedance/sonic v1.14.0 h1:/OfKt8HFw0kh2rj8N0F6C/qPGRESq0BbaNZgcNXXzQQ=
+github.com/bytedance/sonic v1.14.0/go.mod h1:WoEbx8WTcFJfzCe0hbmyTGrfjt8PzNEBdxlNUO24NhA=
+github.com/bytedance/sonic/loader v0.3.0 h1:dskwH8edlzNMctoruo8FPTJDF3vLtDT0sXZwvZJyqeA=
+github.com/bytedance/sonic/loader v0.3.0/go.mod h1:N8A3vUdtUebEY2/VQC0MyhYeKUFosQU6FxH2JmUe6VI=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cloudflare/golz4 v0.0.0-20150217214814-ef862a3cdc58 h1:F1EaeKL/ta07PY/k9Os/UFtwERei2/XzGemhpGnBKNg=
+github.com/cloudflare/golz4 v0.0.0-20150217214814-ef862a3cdc58/go.mod h1:EOBUe0h4xcZ5GoxqC5SDxFQ8gwyZPKQoEzownBlhI80=
+github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
+github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
+github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
+github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
+github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+github.com/coreos/go-systemd/v22 v22.6.0 h1:aGVa/v8B7hpb0TKl0MWoAavPDmHvobFe5R5zn0bCJWo=
+github.com/coreos/go-systemd/v22 v22.6.0/go.mod h1:iG+pp635Fo7ZmV/j14KUcmEyWF+0X7Lua8rrTWzYgWU=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dhui/dktest v0.4.6 h1:+DPKyScKSEp3VLtbMDHcUq6V5Lm5zfZZVb0Sk7Ahom4=
+github.com/dhui/dktest v0.4.6/go.mod h1:JHTSYDtKkvFNFHJKqCzVzqXecyv+tKt8EzceOmQOgbU=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/docker v28.5.2+incompatible h1:DBX0Y0zAjZbSrm1uzOkdr1onVghKaftjlSWt4AFexzM=
+github.com/docker/docker v28.5.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
+github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/dop251/goja v0.0.0-20260607120635-348e6bea910d h1:xbM5U2EvWKkHxzEQJ2DEn20FwolWZahuTnVHr6WL3Q4=
+github.com/dop251/goja v0.0.0-20260607120635-348e6bea910d/go.mod h1:Sc+QOu1WruvaaeT/cxFez/pXHpI9ZDjg/E8QNfSVveI=
+github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/gabriel-vasile/mimetype v1.4.8 h1:FfZ3gj38NjllZIeJAmMhr+qKL8Wu+nOoI3GqacKw1NM=
+github.com/gabriel-vasile/mimetype v1.4.8/go.mod h1:ByKUIKGjh1ODkGM1asKUbQZOLGrPjydw3hYPU2YU9t8=
+github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
+github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
+github.com/gin-gonic/gin v1.11.0 h1:OW/6PLjyusp2PPXtyxKHU0RbX6I/l28FTdDlae5ueWk=
+github.com/gin-gonic/gin v1.11.0/go.mod h1:+iq/FyxlGzII0KHiBGjuNn4UNENUlKbGlNmc+W50Dls=
+github.com/go-chi/chi/v5 v5.2.2 h1:CMwsvRVTbXVytCk1Wd72Zy1LAsAh9GxMmSNWLHCG618=
+github.com/go-chi/chi/v5 v5.2.2/go.mod h1:L2yAIGWB3H+phAw1NxKwWM+7eUH/lU8pOMm5hHcoops=
+github.com/go-faster/city v1.0.1 h1:4WAxSZ3V2Ws4QRDrscLEDcibJY8uf41H6AhXDrNDcGw=
+github.com/go-faster/city v1.0.1/go.mod h1:jKcUJId49qdW3L1qKHH/3wPeUstCVpVSXTM6vO3VcTw=
+github.com/go-faster/errors v0.7.1 h1:MkJTnDoEdi9pDabt1dpWf7AA8/BaSYZqibYyhZ20AYg=
+github.com/go-faster/errors v0.7.1/go.mod h1:5ySTjWFiphBs07IKuiL69nxdfd5+fzh1u7FPGZP2quo=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
+github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.27.0 h1:w8+XrWVMhGkxOaaowyKH35gFydVHOvC0/uWoy2Fzwn4=
+github.com/go-playground/validator/v10 v10.27.0/go.mod h1:I5QpIEbmr8On7W0TktmJAumgzX4CA1XNl4ZmDuVHKKo=
+github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU=
+github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
+github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
+github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
+github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
+github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/golang-migrate/migrate/v4 v4.19.1 h1:OCyb44lFuQfYXYLx1SCxPZQGU7mcaZ7gH9yH4jSFbBA=
+github.com/golang-migrate/migrate/v4 v4.19.1/go.mod h1:CTcgfjxhaUtsLipnLoQRWCrjYXycRz/g5+RWDuYgPrE=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/golang/snappy v0.0.1/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
+github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20260604005048-7023385849c0 h1:h1QTMDl6q9wDvDCJVpKQSjgleGFYnd2fOxmg2K+6BGE=
+github.com/google/pprof v0.0.0-20260604005048-7023385849c0/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/mux v1.7.4 h1:VuZ8uybHlWmqV03+zRzdwKL4tUnIp1MAQtp1mIFE1bc=
+github.com/gorilla/mux v1.7.4/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So=
+github.com/gorilla/securecookie v1.1.2 h1:YCIWL56dvtr73r6715mJs5ZvhtnY73hBvEF8kXD8ePA=
+github.com/gorilla/securecookie v1.1.2/go.mod h1:NfCASbcHqRSY+3a8tlWJwsQap2VX5pwzwo4h3eOamfo=
+github.com/gorilla/sessions v1.4.0 h1:kpIYOp/oi6MG/p5PgxApU8srsSw9tuFbt46Lt7auzqQ=
+github.com/gorilla/sessions v1.4.0/go.mod h1:FLWm50oby91+hl7p/wRxDth9bWSuk0qVL2emc7lT5ik=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
+github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51/go.mod h1:CzGEWj7cYgsdH8dAjBGEr58BoE7ScuLd+fwFZ44+/x8=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/klauspost/compress v1.13.6/go.mod h1:/3/Vjq9QcHkK5uEr5lBEmyoZ1iFhe47etQ6QUkpK6sk=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
+github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
+github.com/markbates/goth v1.82.0 h1:8j/c34AjBSTNzO7zTsOyP5IYCQCMBTRBHAbBt/PI0bQ=
+github.com/markbates/goth v1.82.0/go.mod h1:/DRlcq0pyqkKToyZjsL2KgiA1zbF1HIjE7u2uC79rUk=
+github.com/mattn/go-isatty v0.0.12/go.mod h1:cbi8OIDigv2wuxKPP5vlRcQ1OAZbq2CE4Kysco4FUpU=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
+github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
+github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFdJifH4BDsTlE89Zl93FEloxaWZfGcifgq8=
+github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/montanaflynn/stats v0.0.0-20171201202039-1bf9dbcd8cbe/go.mod h1:wL8QJuTMNUDYhXwkmfOly8iTdp5TEcJFWZD2D7SIkUc=
+github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
+github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
+github.com/paulmach/orb v0.12.0 h1:z+zOwjmG3MyEEqzv92UN49Lg1JFYx0L9GpGKNVDKk1s=
+github.com/paulmach/orb v0.12.0/go.mod h1:5mULz1xQfs3bmQm63QEJA6lNGujuRafwA5S/EnuLaLU=
+github.com/paulmach/protoscan v0.2.1/go.mod h1:SpcSwydNLrxUGSDvXvO0P7g7AuhJ7lcKfDlhJCDw2gY=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pierrec/lz4/v4 v4.1.22 h1:cKFw6uJDK+/gfw5BcDL0JL5aBsAFdsIT18eRtLj7VIU=
+github.com/pierrec/lz4/v4 v4.1.22/go.mod h1:gZWDp/Ze/IJXGXf23ltt2EXimqmTUXEy0GFuRQyBid4=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/quic-go/qpack v0.5.1 h1:giqksBPnT/HDtZ6VhtFKgoLOWmlyo9Ei6u9PqzIMbhI=
+github.com/quic-go/qpack v0.5.1/go.mod h1:+PC4XFrEskIVkcLzpEkbLqq1uCoxPhQuvK5rH1ZgaEg=
+github.com/quic-go/quic-go v0.54.0 h1:6s1YB9QotYI6Ospeiguknbp2Znb/jZYjZLRXn9kMQBg=
+github.com/quic-go/quic-go v0.54.0/go.mod h1:e68ZEaCdyviluZmy44P6Iey98v/Wfz6HCjQEm+l8zTY=
+github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0 h1:OdAsTTz6OkFY5QxjkYwrChwuRruF69c169dPK26NUlk=
+github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8=
+github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
+github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
+github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
+github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
+github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk=
+github.com/tracewayapp/lit/v2 v2.0.2 h1:ZE8UlRWUOX3OZvY2UfbYSDcDUpBoTNLXl70Qujs0mqs=
+github.com/tracewayapp/lit/v2 v2.0.2/go.mod h1:i3zPBL5NtFgZxpxT9PvC2w4gm3S9IzDv4K5JSALtlfs=
+github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
+github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/ugorji/go/codec v1.3.0 h1:Qd2W2sQawAfG8XSvzwhBeoGq71zXOC/Q1E9y/wUcsUA=
+github.com/ugorji/go/codec v1.3.0/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
+github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
+github.com/xdg-go/scram v1.1.1/go.mod h1:RaEWvsqvNKKvBPvcKeFjrG2cJqOkHTiyTpzz23ni57g=
+github.com/xdg-go/stringprep v1.0.3/go.mod h1:W3f5j4i+9rC0kuIEJL0ky1VpHXQU3ocBgklLGvcBnW8=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+github.com/youmark/pkcs8 v0.0.0-20181117223130-1be2e3e5546d/go.mod h1:rHwXgn7JulP+udvsHwJoVG1YGAP6VLg4y9I5dyZdqmA=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+go.mongodb.org/mongo-driver v1.11.4/go.mod h1:PTSz5yu21bkT/wXpkS7WR5f0ddqw5quethTUn9WM+2g=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 h1:F7Jx+6hwnZ41NSFTO5q4LYDtJRXBf2PD0rNBkeB/lus=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0/go.mod h1:UHB22Z8QsdRDrnAtX4PntOl36ajSxcdUMt1sF7Y6E7Q=
+go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
+go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
+go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
+go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
+go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
+go.opentelemetry.io/proto/otlp/collector/profiles/v1development v0.3.0 h1:AWBLtJn3ajH399gyOuJdqPsC9w152x3xGVVO/UK3vyM=
+go.opentelemetry.io/proto/otlp/collector/profiles/v1development v0.3.0/go.mod h1:kCdbxyM9kfmv3v4ZQzZ2pACxoQ6lE0IsjP+UcZwQnr4=
+go.opentelemetry.io/proto/otlp/profiles/v1development v0.3.0 h1:ZQs05qo3Yh4KUHeVH6v89xErwmsvgA/cLX2/w5Ikp+k=
+go.opentelemetry.io/proto/otlp/profiles/v1development v0.3.0/go.mod h1:3iiRVKaCfVo0UI1ZaSMm5WbCBbINRqVlD9SUmvyBNrY=
+go.tracewayapp.com v1.0.2 h1:ICMh5V4Sw5WezEPHMQR0roUsU7r9np+fwJWTIdyMhDI=
+go.tracewayapp.com v1.0.2/go.mod h1:0eQ/FAOA4VzTxrevTayqfYBhTEQYHEfMTPv/IiZ7F6E=
+go.tracewayapp.com/tracewaygin v1.0.2 h1:MRAvtOKz0zceoe1Ee7pl5eciSerc+gIogC7oWJaKQf8=
+go.tracewayapp.com/tracewaygin v1.0.2/go.mod h1:p/26TIhpfte86Gp3QJpA8Q72pJShFXX1jogIiKG2LXQ=
+go.uber.org/mock v0.5.0 h1:KAMbZvZPyBPWgD14IrIQ38QCyjwpvVVV6K/bHl1IwQU=
+go.uber.org/mock v0.5.0/go.mod h1:ge71pBPLYDk7QIi1LupWxdAykm7KIEFchiOqd6z7qMM=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/arch v0.20.0 h1:dx1zTU0MAE98U+TQ8BLl7XsJbgze2WnNKF/8tGp/Q6c=
+golang.org/x/arch v0.20.0/go.mod h1:bdwinDaKcfZUGpH09BB7ZmOfhalA8lQdzl62l8gGWsk=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
+golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
+golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
+golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20201124115921-2c860bdd6e78/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
+golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
+gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
+google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171 h1:tu/dtnW1o3wfaxCOjSLn5IRX4YDcJrtlpzYkhHhGaC4=
+google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171/go.mod h1:M5krXqk4GhBKvB596udGL3UyjL4I1+cTbK0orROM9ng=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 h1:ggcbiqK8WWh6l1dnltU4BgWGIGo+EVYxCaAPih/zQXQ=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ=
+google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.27.1/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+lukechampine.com/uint128 v1.1.1/go.mod h1:c4eWIwlEGaxC/+H1VguhU4PHXNWDCDMUlWdIWl2j1gk=
+lukechampine.com/uint128 v1.2.0 h1:mBi/5l91vocEN8otkC5bDLhi2KdCticRiwbdB0O+rjI=
+lukechampine.com/uint128 v1.2.0/go.mod h1:c4eWIwlEGaxC/+H1VguhU4PHXNWDCDMUlWdIWl2j1gk=
+modernc.org/cc/v3 v3.36.2/go.mod h1:NFUHyPn4ekoC/JHeZFfZurN6ixxawE1BnVonP/oahEI=
+modernc.org/cc/v3 v3.36.3 h1:uISP3F66UlixxWEcKuIWERa4TwrZENHSL8tWxZz8bHg=
+modernc.org/cc/v3 v3.36.3/go.mod h1:NFUHyPn4ekoC/JHeZFfZurN6ixxawE1BnVonP/oahEI=
+modernc.org/ccgo/v3 v3.16.9 h1:AXquSwg7GuMk11pIdw7fmO1Y/ybgazVkMhsZWCV0mHM=
+modernc.org/ccgo/v3 v3.16.9/go.mod h1:zNMzC9A9xeNUepy6KuZBbugn3c0Mc9TeiJO4lgvkJDo=
+modernc.org/ccorpus v1.11.6 h1:J16RXiiqiCgua6+ZvQot4yUuUy8zxgqbqEEUuGPlISk=
+modernc.org/ccorpus v1.11.6/go.mod h1:2gEUTrWqdpH2pXsmTM1ZkjeSrUWDpjMu2T6m29L/ErQ=
+modernc.org/httpfs v1.0.6 h1:AAgIpFZRXuYnkjftxTAZwMIiwEqAfk8aVB2/oA6nAeM=
+modernc.org/httpfs v1.0.6/go.mod h1:7dosgurJGp0sPaRanU53W4xZYKh14wfzX420oZADeHM=
+modernc.org/libc v1.17.0/go.mod h1:XsgLldpP4aWlPlsjqKRdHPqCxCjISdHfM/yeWC5GyW0=
+modernc.org/libc v1.17.1 h1:Q8/Cpi36V/QBfuQaFVeisEBs3WqoGAJprZzmf7TfEYI=
+modernc.org/libc v1.17.1/go.mod h1:FZ23b+8LjxZs7XtFMbSzL/EhPxNbfZbErxEHc7cbD9s=
+modernc.org/mathutil v1.2.2/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
+modernc.org/mathutil v1.4.1/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
+modernc.org/mathutil v1.5.0 h1:rV0Ko/6SfM+8G+yKiyI830l3Wuz1zRutdslNoQ0kfiQ=
+modernc.org/mathutil v1.5.0/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
+modernc.org/memory v1.2.0/go.mod h1:/0wo5ibyrQiaoUoH7f9D8dnglAmILJ5/cxZlRECf+Nw=
+modernc.org/memory v1.2.1 h1:dkRh86wgmq/bJu2cAS2oqBCz/KsMZU7TUM4CibQ7eBs=
+modernc.org/memory v1.2.1/go.mod h1:PkUhL0Mugw21sHPeskwZW4D6VscE/GQJOnIpCnW6pSU=
+modernc.org/opt v0.1.1/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
+modernc.org/opt v0.1.3 h1:3XOZf2yznlhC+ibLltsDGzABUGVx8J6pnFMS3E4dcq4=
+modernc.org/opt v0.1.3/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
+modernc.org/sqlite v1.18.1 h1:ko32eKt3jf7eqIkCgPAeHMBXw3riNSLhl2f3loEF7o8=
+modernc.org/sqlite v1.18.1/go.mod h1:6ho+Gow7oX5V+OiOQ6Tr4xeqbx13UZ6t+Fw9IRUG4d4=
+modernc.org/strutil v1.1.1/go.mod h1:DE+MQQ/hjKBZS2zNInV5hhcipt5rLPWkmpbGeW5mmdw=
+modernc.org/strutil v1.1.3 h1:fNMm+oJklMGYfU9Ylcywl0CO5O6nTfaowNsh2wpPjzY=
+modernc.org/strutil v1.1.3/go.mod h1:MEHNA7PdEnEwLvspRMtWTNnp2nnyvMfkimT1NKNAGbw=
+modernc.org/tcl v1.13.1 h1:npxzTwFTZYM8ghWicVIX1cRWzj7Nd8i6AqqX2p+IYao=
+modernc.org/tcl v1.13.1/go.mod h1:XOLfOwzhkljL4itZkK6T72ckMgvj0BDsnKNdZVUOecw=
+modernc.org/token v1.0.0 h1:a0jaWiNMDhDUtqOj09wvjWWAqd3q7WpBulmL9H2egsk=
+modernc.org/token v1.0.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+modernc.org/z v1.5.1 h1:RTNHdsrOpeoSeOF4FbzTo8gBYByaJ5xT7NgZ9ZqRiJM=
+modernc.org/z v1.5.1/go.mod h1:eWFB510QWW5Th9YGZT81s+LwvaAs3Q2yr4sP0rmLkv8=
diff --git a/cli/test/contract/harness_test.go b/cli/test/contract/harness_test.go
new file mode 100644
index 00000000..ddfd0dab
--- /dev/null
+++ b/cli/test/contract/harness_test.go
@@ -0,0 +1,396 @@
+// Package contract boots the Traceway backend in SQLite mode, seeds telemetry
+// fixtures, and asserts that every endpoint the CLI calls keeps a stable wire
+// contract. Unlike the unit tests (which run against hand-written httptest
+// mocks that encode the CLI's own assumptions), this exercises the real server,
+// so a backend field rename, casing change, or route change is caught here.
+//
+// It is a separate Go module (see go.mod) so the main cli module's lint/vuln
+// graph stays free of the backend's dependency set. Run it with:
+//
+// cd cli/test/contract && go test ./...
+//
+// Regenerate the golden wire-shape fingerprints after an intentional contract
+// change with:
+//
+// go test ./... -update
+package contract
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "flag"
+ "fmt"
+ "io"
+ "net"
+ "net/http"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "sort"
+ "strings"
+ "testing"
+ "time"
+
+ tracewaybackend "github.com/tracewayapp/traceway/backend"
+ client "github.com/tracewayapp/traceway/cli/pkg/client"
+)
+
+const (
+ seedEmail = "[email protected]"
+ seedPassword = "contract-password-123"
+ seedProject = "Contract"
+ seedToken = "contract-project-token"
+)
+
+var update = flag.Bool("update", false, "update golden wire-shape fingerprints in testdata/")
+
+var (
+ baseURL string // http://127.0.0.1:<port> (no /api suffix)
+ jwtToken string // app JWT for the seeded user
+ projectID string // UUID of the seeded project
+ cliBin string // path to the built traceway binary
+ xdgConfig string // XDG_CONFIG_HOME for the CLI under test
+ xdgState string // XDG_STATE_HOME for the CLI under test
+ seedAt time.Time // reference instant telemetry is seeded around
+)
+
+func TestMain(m *testing.M) {
+ flag.Parse()
+
+ if err := bootBackend(); err != nil {
+ fmt.Fprintln(os.Stderr, "contract harness:", err)
+ os.Exit(1)
+ }
+
+ code := m.Run()
+ _ = os.RemoveAll("storage") // storage.Init creates this next to the test
+ os.Exit(code)
+}
+
+// bootBackend starts the backend in SQLite mode, seeds a user/project plus
+// telemetry, builds the CLI binary, and logs it in. Everything lives in temp
+// dirs that are intentionally left for the OS to reclaim (the process is short
+// lived); the local ./storage dir storage.Init creates is removed explicitly.
+func bootBackend() error {
+ port, err := freePort()
+ if err != nil {
+ return fmt.Errorf("free port: %w", err)
+ }
+ baseURL = fmt.Sprintf("http://127.0.0.1:%d", port)
+
+ tmp, err := os.MkdirTemp("", "tw-contract-")
+ if err != nil {
+ return err
+ }
+ dbPath := filepath.Join(tmp, "traceway.db")
+
+ go tracewaybackend.Run(
+ tracewaybackend.WithPort(port),
+ tracewaybackend.WithSQLitePath(dbPath),
+ tracewaybackend.WithServerURL(baseURL),
+ tracewaybackend.WithDefaultUser(seedEmail, seedPassword),
+ tracewaybackend.WithDefaultProject(seedProject, "gin", seedToken),
+ tracewaybackend.DisableLogging(),
+ )
+
+ if err := waitReady(baseURL, 30*time.Second); err != nil {
+ return fmt.Errorf("backend never became ready: %w", err)
+ }
+
+ jwtToken, projectID, err = appLogin(baseURL, seedEmail, seedPassword)
+ if err != nil {
+ return fmt.Errorf("login: %w", err)
+ }
+
+ seedAt = time.Now().UTC().Add(-time.Hour)
+ if err := seedTelemetry(context.Background(), projectID, seedAt); err != nil {
+ return fmt.Errorf("seed telemetry: %w", err)
+ }
+ if err := waitForData(15 * time.Second); err != nil {
+ return fmt.Errorf("seeded telemetry never became visible: %w", err)
+ }
+
+ cliBin = filepath.Join(tmp, "traceway")
+ if err := buildCLI(cliBin); err != nil {
+ return fmt.Errorf("build cli: %w", err)
+ }
+
+ xdgConfig, err = os.MkdirTemp("", "tw-cfg-")
+ if err != nil {
+ return err
+ }
+ xdgState, err = os.MkdirTemp("", "tw-state-")
+ if err != nil {
+ return err
+ }
+ if err := cliLogin(); err != nil {
+ return fmt.Errorf("cli login: %w", err)
+ }
+ return nil
+}
+
+// freePort asks the OS for an unused TCP port, then releases it for the backend
+// to bind. The small window between close and re-bind is acceptable for a test.
+func freePort() (int, error) {
+ l, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ return 0, err
+ }
+ defer l.Close()
+ return l.Addr().(*net.TCPAddr).Port, nil
+}
+
+// waitReady polls the unauthenticated has-organizations endpoint until the
+// server answers (status < 500) or the deadline passes.
+func waitReady(base string, timeout time.Duration) error {
+ deadline := time.Now().Add(timeout)
+ hc := &http.Client{Timeout: 2 * time.Second}
+ for time.Now().Before(deadline) {
+ resp, err := hc.Get(base + "/api/has-organizations")
+ if err == nil {
+ _ = resp.Body.Close()
+ if resp.StatusCode < 500 {
+ return nil
+ }
+ }
+ time.Sleep(100 * time.Millisecond)
+ }
+ return errors.New("timed out")
+}
+
+// appLogin posts the seeded credentials and returns (jwt, projectID).
+func appLogin(base, email, password string) (string, string, error) {
+ body, _ := json.Marshal(map[string]string{"email": email, "password": password})
+ resp, err := http.Post(base+"/api/login", "application/json", bytes.NewReader(body))
+ if err != nil {
+ return "", "", err
+ }
+ defer resp.Body.Close()
+ raw, _ := io.ReadAll(resp.Body)
+ if resp.StatusCode != http.StatusOK {
+ return "", "", fmt.Errorf("status %d: %s", resp.StatusCode, raw)
+ }
+ var parsed struct {
+ Token string `json:"token"`
+ Projects []struct {
+ Id string `json:"id"`
+ } `json:"projects"`
+ }
+ if err := json.Unmarshal(raw, &parsed); err != nil {
+ return "", "", fmt.Errorf("decode login: %w", err)
+ }
+ if parsed.Token == "" || len(parsed.Projects) == 0 {
+ return "", "", fmt.Errorf("login returned no token/project: %s", raw)
+ }
+ return parsed.Token, parsed.Projects[0].Id, nil
+}
+
+// waitForData polls endpoints/grouped until the seeded endpoint is visible,
+// absorbing any insert lag before the assertions run.
+func waitForData(timeout time.Duration) error {
+ deadline := time.Now().Add(timeout)
+ c := client.New(baseURL, client.WithJWT(jwtToken))
+ tr := client.TimeRangeFromExplicit(seedAt.Add(-time.Hour), seedAt.Add(time.Hour))
+ for time.Now().Before(deadline) {
+ resp, err := c.ListEndpoints(context.Background(), projectID, client.ListEndpointsRequest{
+ TimeRange: tr,
+ Pagination: client.PaginationParams{Page: 1, PageSize: 50},
+ })
+ if err == nil && len(resp.Data) > 0 {
+ return nil
+ }
+ time.Sleep(100 * time.Millisecond)
+ }
+ return errors.New("timed out")
+}
+
+// buildCLI compiles the traceway binary from the sibling cli module.
+func buildCLI(out string) error {
+ wd, err := os.Getwd()
+ if err != nil {
+ return err
+ }
+ cliRoot := filepath.Join(wd, "..", "..") // cli/test/contract -> cli
+ cmd := exec.Command("go", "build", "-o", out, "./cmd/traceway")
+ cmd.Dir = cliRoot
+ if combined, err := cmd.CombinedOutput(); err != nil {
+ return fmt.Errorf("%w: %s", err, combined)
+ }
+ return nil
+}
+
+// cliLogin runs the real login + projects-use flow so the CLI binary is
+// authenticated against the booted server for the round-trip assertions.
+func cliLogin() error {
+ if out, _, code := runCLI(nil, seedPassword+"\n", "login", "--url", baseURL, "--username", seedEmail, "--password-stdin"); code != 0 {
+ return fmt.Errorf("login exit %d: %s", code, out)
+ }
+ if out, _, code := runCLI(nil, "", "projects", "use", projectID); code != 0 {
+ return fmt.Errorf("projects use exit %d: %s", code, out)
+ }
+ return nil
+}
+
+// runCLI executes the built binary with the CLI-under-test XDG dirs. t may be
+// nil (used during boot before any test is running); on a nil t an exec failure
+// returns code -1 instead of failing a test.
+func runCLI(t *testing.T, stdin string, args ...string) (stdout, stderr string, code int) {
+ if t != nil {
+ t.Helper()
+ }
+ cmd := exec.Command(cliBin, args...)
+ cmd.Env = append(os.Environ(),
+ "XDG_CONFIG_HOME="+xdgConfig,
+ "XDG_STATE_HOME="+xdgState,
+ )
+ if stdin != "" {
+ cmd.Stdin = strings.NewReader(stdin)
+ }
+ var so, se bytes.Buffer
+ cmd.Stdout = &so
+ cmd.Stderr = &se
+ err := cmd.Run()
+ code = 0
+ if err != nil {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ code = ee.ExitCode()
+ } else if t != nil {
+ t.Fatalf("runCLI %v: %v", args, err)
+ } else {
+ return so.String(), se.String(), -1
+ }
+ }
+ return so.String(), se.String(), code
+}
+
+// capturingRT tees each response body so a test can snapshot the raw wire bytes
+// while the typed client still decodes the (replayed) body normally.
+type capturingRT struct {
+ body []byte
+}
+
+func (c *capturingRT) RoundTrip(r *http.Request) (*http.Response, error) {
+ resp, err := http.DefaultTransport.RoundTrip(r)
+ if err != nil {
+ return nil, err
+ }
+ b, _ := io.ReadAll(resp.Body)
+ _ = resp.Body.Close()
+ c.body = b
+ resp.Body = io.NopCloser(bytes.NewReader(b))
+ return resp, nil
+}
+
+// capturedClient returns a client whose transport records the raw response of
+// the next request, so callers get both the typed result (request-encoding
+// contract) and the raw wire bytes (response-shape contract) from one call.
+func capturedClient() (*client.Client, *capturingRT) {
+ rt := &capturingRT{}
+ c := client.New(baseURL,
+ client.WithJWT(jwtToken),
+ client.WithHTTPClient(&http.Client{Transport: rt, Timeout: 30 * time.Second}),
+ )
+ return c, rt
+}
+
+// goldenAssert reduces body to a value-independent wire-shape fingerprint and
+// compares it against testdata/<name>.schema.txt (or rewrites it under -update).
+func goldenAssert(t *testing.T, name string, body []byte) {
+ t.Helper()
+ got, err := fingerprint(body)
+ if err != nil {
+ t.Fatalf("%s: %v", name, err)
+ }
+ path := filepath.Join("testdata", name+".schema.txt")
+ if *update {
+ if err := os.MkdirAll("testdata", 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(path, []byte(got), 0o644); err != nil {
+ t.Fatal(err)
+ }
+ return
+ }
+ want, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("%s: missing golden %s (regenerate with: go test ./... -update): %v", name, path, err)
+ }
+ if string(want) != got {
+ t.Errorf("%s: wire schema drift vs %s\n--- want ---\n%s\n--- got ---\n%s", name, path, want, got)
+ }
+}
+
+// fingerprint maps a JSON document to a stable schema: the sorted set of
+// "path: type" lines. Array indices collapse to [], so element order and count
+// don't matter; object keys are kept literally, so a rename or casing change
+// (e.g. Timestamp -> timestamp) shows up as a diff.
+func fingerprint(body []byte) (string, error) {
+ dec := json.NewDecoder(bytes.NewReader(body))
+ dec.UseNumber()
+ var v any
+ if err := dec.Decode(&v); err != nil {
+ return "", fmt.Errorf("response is not JSON: %w (body: %s)", err, clip(body))
+ }
+ set := map[string]struct{}{}
+ walk("", v, set)
+ lines := make([]string, 0, len(set))
+ for l := range set {
+ lines = append(lines, l)
+ }
+ sort.Strings(lines)
+ return strings.Join(lines, "\n") + "\n", nil
+}
+
+func walk(path string, v any, set map[string]struct{}) {
+ switch t := v.(type) {
+ case map[string]any:
+ if len(t) == 0 {
+ set[path+": object{}"] = struct{}{}
+ return
+ }
+ for k, child := range t {
+ p := k
+ if path != "" {
+ p = path + "." + k
+ }
+ walk(p, child, set)
+ }
+ case []any:
+ if len(t) == 0 {
+ set[path+"[]: empty"] = struct{}{}
+ return
+ }
+ for _, e := range t {
+ walk(path+"[]", e, set)
+ }
+ case json.Number:
+ set[path+": number"] = struct{}{}
+ case string:
+ set[path+": string"] = struct{}{}
+ case bool:
+ set[path+": bool"] = struct{}{}
+ case nil:
+ set[path+": null"] = struct{}{}
+ }
+}
+
+func clip(b []byte) string {
+ const max = 200
+ if len(b) > max {
+ return string(b[:max]) + "..."
+ }
+ return string(b)
+}
+
+// sortStrings is a tiny insertion-free sort wrapper kept local so the file has
+// no dependency beyond the standard library's sort.
+func sortStrings(s []string) {
+ for i := 1; i < len(s); i++ {
+ for j := i; j > 0 && s[j-1] > s[j]; j-- {
+ s[j-1], s[j] = s[j], s[j-1]
+ }
+ }
+}
diff --git a/cli/test/contract/seed_test.go b/cli/test/contract/seed_test.go
new file mode 100644
index 00000000..6a220796
--- /dev/null
+++ b/cli/test/contract/seed_test.go
@@ -0,0 +1,191 @@
+package contract
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/google/uuid"
+
+ "github.com/tracewayapp/traceway/backend/app/controllers/clientcontrollers"
+ "github.com/tracewayapp/traceway/backend/app/models"
+ "github.com/tracewayapp/traceway/backend/app/repositories"
+)
+
+// Seeded ids, set by seedTelemetry and used to address the by-id detail
+// endpoints. They are shared by every node of one distributed trace so the
+// distributed-trace endpoint returns a populated graph.
+var (
+ seedEndpointID uuid.UUID
+ seedTaskID uuid.UUID
+ seedExceptionID uuid.UUID
+ seedSpanID uuid.UUID
+ seedSessionID uuid.UUID
+ seedAiTraceID uuid.UUID
+ seedLogID uuid.UUID
+ seedTraceID uuid.UUID // the distributed_trace_id shared across nodes
+ seedHash string // exception grouping hash (computed, not assigned)
+
+ seedMetricName = "contract.metric"
+ seedMetricVal = 42.5
+)
+
+// seedTelemetry inserts exactly one row of every telemetry type the CLI reads,
+// directly via the backend repositories (which, in the default build, write to
+// the SQLite telemetry DB synchronously). Everything is timestamped at `at` and
+// linked by a shared distributed trace id.
+func seedTelemetry(ctx context.Context, projectIDStr string, at time.Time) error {
+ pid, err := uuid.Parse(projectIDStr)
+ if err != nil {
+ return fmt.Errorf("parse project id: %w", err)
+ }
+
+ seedEndpointID = uuid.New()
+ seedTaskID = uuid.New()
+ seedExceptionID = uuid.New()
+ seedSpanID = uuid.New()
+ seedSessionID = uuid.New()
+ seedAiTraceID = uuid.New()
+ seedLogID = uuid.New()
+ seedTraceID = uuid.New()
+
+ stack := "ContractError: seeded failure\n\tat contract.go:42"
+ seedHash = clientcontrollers.ComputeExceptionHash(stack, false)
+
+ endpoint := models.Endpoint{
+ Id: seedEndpointID,
+ ProjectId: pid,
+ Endpoint: "GET /api/contract",
+ Duration: 123 * time.Millisecond,
+ RecordedAt: at,
+ StatusCode: 200,
+ BodySize: 1024,
+ ClientIP: "127.0.0.1",
+ Attributes: map[string]string{},
+ AppVersion: "1.0.0",
+ ServerName: "contract-host",
+ DistributedTraceId: &seedTraceID,
+ SpanId: &seedSpanID,
+ IsRoot: true,
+ }
+ if err := repositories.EndpointRepository.InsertAsync(ctx, []models.Endpoint{endpoint}); err != nil {
+ return fmt.Errorf("endpoint: %w", err)
+ }
+
+ task := models.Task{
+ Id: seedTaskID,
+ ProjectId: pid,
+ TaskName: "contract-task",
+ Duration: 250 * time.Millisecond,
+ RecordedAt: at,
+ ClientIP: "127.0.0.1",
+ Attributes: map[string]string{},
+ AppVersion: "1.0.0",
+ ServerName: "contract-host",
+ DistributedTraceId: &seedTraceID,
+ IsRoot: true,
+ }
+ if err := repositories.TaskRepository.InsertAsync(ctx, []models.Task{task}); err != nil {
+ return fmt.Errorf("task: %w", err)
+ }
+
+ exception := models.ExceptionStackTrace{
+ Id: seedExceptionID,
+ ProjectId: pid,
+ TraceId: &seedEndpointID,
+ TraceType: "endpoint",
+ ExceptionHash: seedHash,
+ StackTrace: stack,
+ RecordedAt: at,
+ Attributes: map[string]string{},
+ AppVersion: "1.0.0",
+ ServerName: "contract-host",
+ IsMessage: false,
+ DistributedTraceId: &seedTraceID,
+ SessionId: &seedSessionID,
+ }
+ if err := repositories.ExceptionStackTraceRepository.InsertAsync(ctx, []models.ExceptionStackTrace{exception}); err != nil {
+ return fmt.Errorf("exception: %w", err)
+ }
+
+ span := models.Span{
+ Id: seedSpanID,
+ TraceId: seedTraceID,
+ ProjectId: pid,
+ Name: "contract-span",
+ StartTime: at,
+ Duration: 100 * time.Millisecond,
+ RecordedAt: at,
+ Attributes: map[string]string{},
+ }
+ if err := repositories.SpanRepository.InsertAsync(ctx, []models.Span{span}); err != nil {
+ return fmt.Errorf("span: %w", err)
+ }
+
+ metric := models.MetricPoint{
+ ProjectId: pid,
+ Name: seedMetricName,
+ Value: seedMetricVal,
+ Tags: map[string]string{},
+ RecordedAt: at,
+ }
+ if err := repositories.MetricPointRepository.InsertAsync(ctx, []models.MetricPoint{metric}); err != nil {
+ return fmt.Errorf("metric: %w", err)
+ }
+
+ session := models.Session{
+ Id: seedSessionID,
+ ProjectId: pid,
+ StartedAt: at,
+ Duration: 60000,
+ ClientIP: "127.0.0.1",
+ Attributes: map[string]string{},
+ AppVersion: "1.0.0",
+ ServerName: "contract-host",
+ DistributedTraceId: &seedTraceID,
+ }
+ if err := repositories.SessionRepository.Upsert(ctx, []models.Session{session}); err != nil {
+ return fmt.Errorf("session: %w", err)
+ }
+
+ aiTrace := models.AiTrace{
+ Id: seedAiTraceID,
+ ProjectId: pid,
+ RecordedAt: at,
+ Duration: 500 * time.Millisecond,
+ StatusCode: 200,
+ Model: "gpt-4",
+ ResponseModel: "gpt-4",
+ Provider: "openai",
+ Operation: "chat",
+ InputTokens: 10,
+ OutputTokens: 20,
+ TotalTokens: 30,
+ TotalCost: 0.0012,
+ TraceName: "contract-ai",
+ Attributes: map[string]string{},
+ DistributedTraceId: &seedTraceID,
+ IsRoot: true,
+ }
+ if err := repositories.AiTraceRepository.InsertAsync(ctx, []models.AiTrace{aiTrace}); err != nil {
+ return fmt.Errorf("ai trace: %w", err)
+ }
+
+ logRecord := models.LogRecord{
+ Id: seedLogID,
+ ProjectId: pid,
+ Timestamp: at,
+ SeverityText: "INFO",
+ SeverityNumber: 9,
+ ServiceName: "contract-svc",
+ Body: "contract log line",
+ ResourceAttributes: map[string]string{},
+ ScopeAttributes: map[string]string{},
+ LogAttributes: map[string]string{},
+ }
+ if err := repositories.LogRecordRepository.InsertAsync(ctx, []models.LogRecord{logRecord}); err != nil {
+ return fmt.Errorf("log: %w", err)
+ }
+
+ return nil
+}
diff --git a/cli/test/contract/testdata/aitrace-detail.schema.txt b/cli/test/contract/testdata/aitrace-detail.schema.txt
new file mode 100644
index 00000000..7fdd18f5
--- /dev/null
+++ b/cli/test/contract/testdata/aitrace-detail.schema.txt
@@ -0,0 +1,26 @@
+aiTrace.appVersion: string
+aiTrace.attributes: null
+aiTrace.cachedTokens: number
+aiTrace.distributedTraceId: string
+aiTrace.duration: number
+aiTrace.finishReason: string
+aiTrace.id: string
+aiTrace.inputCost: number
+aiTrace.inputTokens: number
+aiTrace.isRoot: bool
+aiTrace.model: string
+aiTrace.operation: string
+aiTrace.outputCost: number
+aiTrace.outputTokens: number
+aiTrace.projectId: string
+aiTrace.provider: string
+aiTrace.reasoningTokens: number
+aiTrace.recordedAt: string
+aiTrace.responseModel: string
+aiTrace.serverName: string
+aiTrace.statusCode: number
+aiTrace.storageKey: string
+aiTrace.totalCost: number
+aiTrace.totalTokens: number
+aiTrace.traceName: string
+aiTrace.userId: string
diff --git a/cli/test/contract/testdata/distributed-trace.schema.txt b/cli/test/contract/testdata/distributed-trace.schema.txt
new file mode 100644
index 00000000..6f14b4cf
--- /dev/null
+++ b/cli/test/contract/testdata/distributed-trace.schema.txt
@@ -0,0 +1,59 @@
+distributedTraceId: string
+nodes[].aiTrace.appVersion: string
+nodes[].aiTrace.attributes: null
+nodes[].aiTrace.cachedTokens: number
+nodes[].aiTrace.distributedTraceId: string
+nodes[].aiTrace.duration: number
+nodes[].aiTrace.finishReason: string
+nodes[].aiTrace.id: string
+nodes[].aiTrace.inputCost: number
+nodes[].aiTrace.inputTokens: number
+nodes[].aiTrace.isRoot: bool
+nodes[].aiTrace.model: string
+nodes[].aiTrace.operation: string
+nodes[].aiTrace.outputCost: number
+nodes[].aiTrace.outputTokens: number
+nodes[].aiTrace.projectId: string
+nodes[].aiTrace.provider: string
+nodes[].aiTrace.reasoningTokens: number
+nodes[].aiTrace.recordedAt: string
+nodes[].aiTrace.responseModel: string
+nodes[].aiTrace.serverName: string
+nodes[].aiTrace.statusCode: number
+nodes[].aiTrace.storageKey: string
+nodes[].aiTrace.totalCost: number
+nodes[].aiTrace.totalTokens: number
+nodes[].aiTrace.traceName: string
+nodes[].aiTrace.userId: string
+nodes[].endpoint.appVersion: string
+nodes[].endpoint.attributes: null
+nodes[].endpoint.bodySize: number
+nodes[].endpoint.clientIP: string
+nodes[].endpoint.distributedTraceId: string
+nodes[].endpoint.duration: number
+nodes[].endpoint.endpoint: string
+nodes[].endpoint.id: string
+nodes[].endpoint.isRoot: bool
+nodes[].endpoint.isStream: bool
+nodes[].endpoint.projectId: string
+nodes[].endpoint.recordedAt: string
+nodes[].endpoint.serverName: string
+nodes[].endpoint.statusCode: number
+nodes[].exception.exceptionHash: string
+nodes[].exception.recordedAt: string
+nodes[].exception.stackTrace: string
+nodes[].projectId: string
+nodes[].projectName: string
+nodes[].spans[]: empty
+nodes[].task.appVersion: string
+nodes[].task.attributes: null
+nodes[].task.clientIP: string
+nodes[].task.distributedTraceId: string
+nodes[].task.duration: number
+nodes[].task.id: string
+nodes[].task.isRoot: bool
+nodes[].task.projectId: string
+nodes[].task.recordedAt: string
+nodes[].task.serverName: string
+nodes[].task.taskName: string
+nodes[].traceType: string
diff --git a/cli/test/contract/testdata/endpoint-detail.schema.txt b/cli/test/contract/testdata/endpoint-detail.schema.txt
new file mode 100644
index 00000000..8a5bab38
--- /dev/null
+++ b/cli/test/contract/testdata/endpoint-detail.schema.txt
@@ -0,0 +1,21 @@
+endpoint.appVersion: string
+endpoint.attributes: null
+endpoint.bodySize: number
+endpoint.clientIP: string
+endpoint.distributedTraceId: string
+endpoint.duration: number
+endpoint.endpoint: string
+endpoint.id: string
+endpoint.isRoot: bool
+endpoint.isStream: bool
+endpoint.projectId: string
+endpoint.recordedAt: string
+endpoint.serverName: string
+endpoint.spanId: string
+endpoint.statusCode: number
+exception.exceptionHash: string
+exception.recordedAt: string
+exception.stackTrace: string
+hasSpans: bool
+messages[]: empty
+spans[]: empty
diff --git a/cli/test/contract/testdata/endpoints-grouped.schema.txt b/cli/test/contract/testdata/endpoints-grouped.schema.txt
new file mode 100644
index 00000000..b48ee7da
--- /dev/null
+++ b/cli/test/contract/testdata/endpoints-grouped.schema.txt
@@ -0,0 +1,16 @@
+data[].avgDuration: number
+data[].count: number
+data[].endpoint: string
+data[].hasNonRoot: bool
+data[].hasRoot: bool
+data[].impact: number
+data[].impactReason: string
+data[].isStream: bool
+data[].lastSeen: string
+data[].p50Duration: number
+data[].p95Duration: number
+data[].p99Duration: number
+pagination.page: number
+pagination.pageSize: number
+pagination.total: number
+pagination.totalPages: number
diff --git a/cli/test/contract/testdata/exception-by-hash.schema.txt b/cli/test/contract/testdata/exception-by-hash.schema.txt
new file mode 100644
index 00000000..d3eaec2f
--- /dev/null
+++ b/cli/test/contract/testdata/exception-by-hash.schema.txt
@@ -0,0 +1,23 @@
+group.count: number
+group.exceptionHash: string
+group.firstSeen: string
+group.lastSeen: string
+group.stackTrace: string
+occurrences[].appVersion: string
+occurrences[].attributes: null
+occurrences[].distributedTraceId: string
+occurrences[].exceptionHash: string
+occurrences[].id: string
+occurrences[].isMessage: bool
+occurrences[].projectId: string
+occurrences[].recordedAt: string
+occurrences[].serverName: string
+occurrences[].sessionId: string
+occurrences[].stackTrace: string
+occurrences[].traceId: string
+occurrences[].traceType: string
+pagination.page: number
+pagination.pageSize: number
+pagination.total: number
+pagination.totalPages: number
+sessionId: string
diff --git a/cli/test/contract/testdata/exception-by-id.schema.txt b/cli/test/contract/testdata/exception-by-id.schema.txt
new file mode 100644
index 00000000..69edca7c
--- /dev/null
+++ b/cli/test/contract/testdata/exception-by-id.schema.txt
@@ -0,0 +1,14 @@
+exception.appVersion: string
+exception.attributes: null
+exception.distributedTraceId: string
+exception.exceptionHash: string
+exception.id: string
+exception.isMessage: bool
+exception.projectId: string
+exception.recordedAt: string
+exception.serverName: string
+exception.sessionId: string
+exception.stackTrace: string
+exception.traceId: string
+exception.traceType: string
+sessionId: string
diff --git a/cli/test/contract/testdata/exceptions-grouped.schema.txt b/cli/test/contract/testdata/exceptions-grouped.schema.txt
new file mode 100644
index 00000000..5f03f59e
--- /dev/null
+++ b/cli/test/contract/testdata/exceptions-grouped.schema.txt
@@ -0,0 +1,11 @@
+data[].count: number
+data[].exceptionHash: string
+data[].firstSeen: string
+data[].hourlyTrend[].count: number
+data[].hourlyTrend[].timestamp: string
+data[].lastSeen: string
+data[].stackTrace: string
+pagination.page: number
+pagination.pageSize: number
+pagination.total: number
+pagination.totalPages: number
diff --git a/cli/test/contract/testdata/login.schema.txt b/cli/test/contract/testdata/login.schema.txt
new file mode 100644
index 00000000..094f454d
--- /dev/null
+++ b/cli/test/contract/testdata/login.schema.txt
@@ -0,0 +1,18 @@
+organizations[].id: number
+organizations[].name: string
+organizations[].role: string
+organizations[].timezone: string
+projects[].backendUrl: string
+projects[].createdAt: string
+projects[].dropHealthyHealthchecks: bool
+projects[].framework: string
+projects[].healthcheckPaths[]: empty
+projects[].id: string
+projects[].name: string
+projects[].organizationId: number
+projects[].token: string
+token: string
+user.createdAt: string
+user.email: string
+user.id: number
+user.name: string
diff --git a/cli/test/contract/testdata/logs-query.schema.txt b/cli/test/contract/testdata/logs-query.schema.txt
new file mode 100644
index 00000000..50484880
--- /dev/null
+++ b/cli/test/contract/testdata/logs-query.schema.txt
@@ -0,0 +1,21 @@
+data[].body: string
+data[].id: string
+data[].logAttributes: null
+data[].projectId: string
+data[].resourceAttributes: null
+data[].resourceSchemaUrl: string
+data[].scopeAttributes: null
+data[].scopeName: string
+data[].scopeSchemaUrl: string
+data[].scopeVersion: string
+data[].serviceName: string
+data[].severityNumber: number
+data[].severityText: string
+data[].spanId: string
+data[].timestamp: string
+data[].traceFlags: number
+data[].traceId: string
+pagination.page: number
+pagination.pageSize: number
+pagination.total: number
+pagination.totalPages: number
diff --git a/cli/test/contract/testdata/metrics-query.schema.txt b/cli/test/contract/testdata/metrics-query.schema.txt
new file mode 100644
index 00000000..7b12f9d9
--- /dev/null
+++ b/cli/test/contract/testdata/metrics-query.schema.txt
@@ -0,0 +1,4 @@
+results[].name: string
+results[].series.__all__[].timestamp: string
+results[].series.__all__[].value: number
+results[].unit: string
diff --git a/cli/test/contract/testdata/projects-list.schema.txt b/cli/test/contract/testdata/projects-list.schema.txt
new file mode 100644
index 00000000..331aa2eb
--- /dev/null
+++ b/cli/test/contract/testdata/projects-list.schema.txt
@@ -0,0 +1,9 @@
+[].backendUrl: string
+[].createdAt: string
+[].dropHealthyHealthchecks: bool
+[].framework: string
+[].healthcheckPaths[]: empty
+[].id: string
+[].name: string
+[].organizationId: number
+[].token: string
diff --git a/cli/test/contract/testdata/session-detail.schema.txt b/cli/test/contract/testdata/session-detail.schema.txt
new file mode 100644
index 00000000..7c039cf9
--- /dev/null
+++ b/cli/test/contract/testdata/session-detail.schema.txt
@@ -0,0 +1,14 @@
+exceptions[].exceptionHash: string
+exceptions[].id: string
+exceptions[].isMessage: bool
+exceptions[].recordedAt: string
+exceptions[].stackTrace: string
+session.appVersion: string
+session.attributes: null
+session.clientIP: string
+session.distributedTraceId: string
+session.duration: number
+session.id: string
+session.projectId: string
+session.serverName: string
+session.startedAt: string
diff --git a/cli/test/contract/testdata/task-detail.schema.txt b/cli/test/contract/testdata/task-detail.schema.txt
new file mode 100644
index 00000000..6d1318cb
--- /dev/null
+++ b/cli/test/contract/testdata/task-detail.schema.txt
@@ -0,0 +1,14 @@
+hasSpans: bool
+messages[]: empty
+spans[]: empty
+task.appVersion: string
+task.attributes: null
+task.clientIP: string
+task.distributedTraceId: string
+task.duration: number
+task.id: string
+task.isRoot: bool
+task.projectId: string
+task.recordedAt: string
+task.serverName: string
+task.taskName: string
diff --git a/frontend/src/lib/components/dashboard/widget-renderer.svelte b/frontend/src/lib/components/dashboard/widget-renderer.svelte
index 1a310d09..0aebf849 100644
--- a/frontend/src/lib/components/dashboard/widget-renderer.svelte
+++ b/frontend/src/lib/components/dashboard/widget-renderer.svelte
@@ -90,8 +90,8 @@
newSeries.push({
key: label,
data: points.map((p) => ({
- timestamp: new Date(p.Timestamp),
- value: p.Value
+ timestamp: new Date(p.timestamp),
+ value: p.value
})),
color: colors[colorIdx % colors.length]
});
diff --git a/frontend/src/lib/types/dashboard.ts b/frontend/src/lib/types/dashboard.ts
index 57e7930c..2cf48ccc 100644
--- a/frontend/src/lib/types/dashboard.ts
+++ b/frontend/src/lib/types/dashboard.ts
@@ -74,8 +74,8 @@ export type MetricQueryRequest = {
};
export type TimeSeriesPoint = {
- Timestamp: string;
- Value: number;
+ timestamp: string;
+ value: number;
};
export type MetricQueryResult = {
diff --git a/skills/traceway/SKILL.md b/skills/traceway/SKILL.md
index 361a27d2..a28e0c36 100644
--- a/skills/traceway/SKILL.md
+++ b/skills/traceway/SKILL.md
@@ -32,12 +32,14 @@ Users paste dashboard URLs (`https://<instance>/<route>`) as references in any f
| URL path | Identifies | How to fetch it |
|---|---|---|
| `/issues/<hash>` and `/issues/<hash>/events` | Exception group (hash = 16 hex chars) | `traceway exceptions show <hash>` |
-| `/issues/<hash>/<occurrenceId>` (UUID) | One occurrence within the group | `traceway exceptions show <hash> --output json \| jq '.occurrences[] \| select(.id=="<occurrenceId>")'`; occurrences are paginated, walk `--page` if not in the first page |
-| `/endpoints/<endpoint>` | Endpoint group; the segment is the URL-encoded endpoint name (`GET%20%2Fapi%2Fusers%2F%3Aid` is `GET /api/users/:id`) | Decode it, then `traceway endpoints list --search "<decoded name>"` (there is no `endpoints show`) |
-| `/endpoints/<endpoint>/<endpointId>` | One request (transaction) of that endpoint | No CLI for single transactions; fetch the group as above, correlate with `traceway logs query --trace-id <id>` if a trace ID is known from context |
-| `/tasks/<task>` and `/tasks/<task>/<taskId>` | Background task group / single run | No CLI; point the user at the dashboard Tasks page |
-| `/sessions/<sessionId>` | Session replay | No CLI; dashboard only. Occurrences reference sessions via their `sessionId` field |
-| `/ai-traces/<traceName>` and `/ai-traces/<traceName>/<traceId>` | AI trace group / single trace | No CLI; dashboard only |
+| `/issues/<hash>/<occurrenceId>` (UUID) | One occurrence within the group | `traceway exceptions occurrence <occurrenceId> --recorded-at <t>` where `t` is the URL's `?t=` param. Direct and fast; also returns the occurrence's `sessionId` and session recording. No URL? get `recordedAt` from `traceway exceptions show <hash>` occurrences |
+| `/endpoints/<endpoint>` | Endpoint group; the segment is the URL-encoded endpoint name (`GET%20%2Fapi%2Fusers%2F%3Aid` is `GET /api/users/:id`) | Decode it, then `traceway endpoints list --search "<decoded name>"` (the group has no id; `endpoints show` is for one request — next row) |
+| `/endpoints/<endpoint>/<endpointId>` | One request (transaction) of that endpoint | `traceway endpoints show <endpointId> --recorded-at <t>` (`t` = the URL's `?t=` param). Returns the request, its span waterfall, and any linked exception/messages |
+| `/tasks/<task>` | Background task group | No CLI for the group; for one run use the next row |
+| `/tasks/<task>/<taskId>` | Single task run | `traceway tasks show <taskId> --recorded-at <t>` (`t` = the URL's `?t=` param) |
+| `/sessions/<sessionId>` | Session (the exceptions that fired during it; replay stays dashboard-only) | `traceway sessions show <sessionId> --started-at <t>`. The URL has no `?t=`; use the session's start, the URL's `from=`, or a linked occurrence's `recordedAt` (it falls inside the window). Occurrences reference sessions via their `sessionId` |
+| `/ai-traces/<traceName>` | AI trace group | No CLI for the group; for one trace use the next row |
+| `/ai-traces/<traceName>/<traceId>` | Single AI trace | `traceway ai-traces show <traceId> --recorded-at <t>` (`t` = the URL's `?t=` param); returns token/cost stats + the conversation |
| `/logs` | Logs page (its filters are not stored in the URL) | `traceway logs query` with flags taken from the user's description |
| `/issues`, `/endpoints`, `/metrics`, `/` | List and dashboard pages | The matching `list` / `query` command |
@@ -47,6 +49,44 @@ Users paste dashboard URLs (`https://<instance>/<route>`) as references in any f
- `from`/`to` are ISO timestamps; pass via `--from`/`--to`, appending `Z` (or the correct offset) when missing, since the CLI requires RFC3339.
- No time params means the page was on its default; pick `--since` per the ground rules.
+`preset`/`from`/`to` set the *window* for list/group views. Detail URLs additionally carry **`?t=<iso>`** — the single record's timestamp, URL-encoded. That `t` value is exactly what the by-id commands need as `--recorded-at` (or `--started-at` for sessions). See "Fast by-id lookups" next.
+
+## Fast by-id lookups (always pass the timestamp)
+
+The by-id detail commands — `exceptions occurrence`, `endpoints show`, `tasks show`, `ai-traces show`, `sessions show`, `traces show` — **require** the record's timestamp (`--recorded-at`, or `--started-at` for sessions). Telemetry tables are partitioned by day: with the timestamp the lookup is bounded to a small window and ClickHouse prunes to a few partitions; without it the server scans every partition (slow cold load). The flag is mandatory for exactly this reason — never omit it. It can be approximate (within ±24h), and you can recover or estimate it when it isn't handed to you; see "When you don't have the timestamp" below.
+
+Where the timestamp comes from, in order of preference:
+
+1. **A dashboard URL** — the `?t=<iso>` param is the record's `recordedAt`; URL-decode it and pass it verbatim. (Sessions have no `t`; use the session start, `from=`, or a linked occurrence's `recordedAt`.)
+2. **A list/group you already fetched** — every `exceptions show` occurrence carries `recordedAt`. Capture the id and its `recordedAt` together, then drill in.
+3. **A notification** — see below.
+
+Query order when you hold an id: resolve its `recordedAt` first (URL, group, or notification), then call the by-id command with it.
+
+### When you don't have the timestamp
+
+The flag is required, so you must supply *something* — but it can be approximate. The lookup window is **±24h** around what you pass (**±48h** for `traces show`), and if the record isn't in that window the server falls back to an unbounded scan. So a timestamp within a day of the truth stays fast; a wrong guess still returns the right record, just slower. Resolve it in this order:
+
+1. **Recover it from an API.** For an occurrence whose hash you know (e.g. `/issues/<hash>/<occurrenceId>` pasted without `?t=`), run `traceway exceptions show <hash>` and read that occurrence's `recordedAt` — the hash endpoint needs no timestamp. A group's `firstSeen`/`lastSeen` from `exceptions list` bound when its occurrences happened (`lastSeen` ≈ the most recent one).
+2. **Estimate from context.** A notification's send time, the issue's `firstSeen`/`lastSeen`, or the URL's `preset`/`from` window all put you inside ±24h — good enough for a fast lookup.
+3. **Ask the user.** If nothing pins it down (e.g. a bare occurrence/endpoint id with no hash, no time, and no list to recover from), ask roughly when it happened — "around when did this fire? within a day is enough" — and pass that. Don't invent a placeholder like "now" when the issue is old; that defeats the pruning and can miss the ±24h window entirely.
+
+## Resolving an issue notification
+
+Traceway issue notifications (email / Slack / webhook) embed everything for a direct, fast lookup. The body contains:
+
+- `Hash: <16-hex>` — the exception group → `traceway exceptions show <hash>`.
+- `Exception ID: <uuid>` — the specific occurrence.
+- `Occurred at: 2006-01-02 15:04:05 UTC` — the occurrence timestamp. **Convert to RFC3339**: replace the space with `T` and ` UTC` with `Z` (→ `2006-01-02T15:04:05Z`).
+- `View details: /issues/<hash>` — the deep link.
+
+So from a notification, go straight to the occurrence (fast), then pivot reusing the same timestamp:
+
+```bash
+traceway exceptions occurrence <Exception ID> --recorded-at <Occurred at → RFC3339> --output json
+# the result carries distributedTraceId and sessionId → traces show / sessions show below
+```
+
## Flow: Login
### 1. Check for an existing install
@@ -157,6 +197,19 @@ traceway exceptions show $HASH --output json | jq -r '.occurrences[0].distribute
| xargs -I{} traceway logs query --trace-id {} --output json
```
+Pull the whole cross-service trace and the user's session, reusing the occurrence's `recordedAt` as the (mandatory) time hint so both lookups stay partition-bounded:
+
+```bash
+OCC=$(traceway exceptions show $HASH --output json | jq -c '.occurrences[0]')
+TS=$(jq -r '.recordedAt' <<<"$OCC")
+DT=$(jq -r '.distributedTraceId // empty' <<<"$OCC")
+SID=$(jq -r '.sessionId // empty' <<<"$OCC")
+[ -n "$DT" ] && traceway traces show "$DT" --recorded-at "$TS" # every endpoint/task/ai-trace/exception node across services
+[ -n "$SID" ] && traceway sessions show "$SID" --started-at "$TS" # the session + the exceptions that fired in it
+```
+
+`traces show` is usually the single highest-value RCA call: it stitches one logical request together end to end across services.
+
**Check metrics for systemic causes** (spikes lining up with `firstSeen` suggest saturation rather than a code bug):
```bash
@@ -192,13 +245,21 @@ For free-form requests ("what's broken in prod?", "is /api/checkout slow?", "sho
| `traceway projects {list,use}` | List or select the active project |
| `traceway exceptions list` | Grouped exceptions; `--search`, `--search-type text\|regex`, `--order-by lastSeen\|firstSeen\|count`, `--include-archived` |
| `traceway exceptions show <hash>` | One group: full stack trace + occurrences |
+| `traceway exceptions occurrence <id> --recorded-at <t>` | One occurrence by id (fast): full detail + `sessionId` + recording |
| `traceway exceptions archive/unarchive <hash>...` | Mutating; explicit user request + `--yes` only |
| `traceway logs query` | Logs; `--search` (`--search-type body\|attribute`), `--service`, `--min-severity <n>`, `--trace-id` |
| `traceway endpoints list` | Per-endpoint p50/p95/p99 and counts; `--search`, `--order-by impact\|count\|p95\|lastSeen` |
+| `traceway endpoints show <id> --recorded-at <t>` | One request by id: span waterfall + linked errors |
+| `traceway tasks show <id> --recorded-at <t>` | One background task run by id |
+| `traceway ai-traces show <id> --recorded-at <t>` | One AI trace by id + its conversation |
+| `traceway sessions show <id> --started-at <t>` | One session by id + the exceptions that fired in it |
+| `traceway traces show <id> --recorded-at <t>` | Distributed trace: every service node sharing the id |
| `traceway metrics query --name <metric>` | Time series; `--aggregation`, `--tag`, `--group-by`, `--interval-minutes` |
| `traceway profiles {list,use}`, `login`, `logout`, `version` | Profile and session management |
-Not implemented yet (do not fabricate flags; point the user at the web UI): `traces show`, `sessions list/show`, `ai-traces list/show`, `endpoints show`, `metrics list/discover`. Tasks have no CLI command either; the dashboard's Tasks page covers them.
+The by-id `show`/`occurrence` commands take their id from a dashboard URL, a notification, or an `exceptions show` occurrence — and **require** the record's timestamp (`--recorded-at` / `--started-at`); see "Fast by-id lookups" above.
+
+Not implemented yet (do not fabricate flags; point the user at the web UI): `list` verbs for `tasks` / `sessions` / `ai-traces` / `traces` (only by-id `show` exists for those), and `metrics list/discover`.
### Recipes