From 4c91681068a1957e8d4eb92633ae7227b98f9f99 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 8 Aug 2026 15:28:40 +0200 Subject: [PATCH 1/9] feat(studio): correlate logs with traces and expand span detail The Traces panel could show a request's waterfall and the Logs panel could show the same request's log lines, but nothing connected them: `LogEvent` carries a `traceId` to every sink, and the in-memory log buffer dropped it on the way in. A span's attributes were likewise truncated into a fixed-width cell, so the `{ orderId }` you opened the panel to read was exactly what got cut, and `kind` / recorded span events never left the fold at all. - buffer `traceId` on a log entry and stamp it at the `ctx.log` and dispatch-error push sites, so `getLogs` can be joined to `getTraces` - carry `kind` and `events` through `foldTraces` onto `TraceSpan` - expand a span row into a detail block: ids, kind, timing, the full attribute bag, the error, and `addEvent`/`recordException` events - show the dispatch's log lines under its expanded waterfall, read from the same live log ring rather than a new correlated RPC - draw an elapsed-time ruler over the bars, add an "Errors only" filter, and match the search box against span names and span ids - link a log row to its trace, reusing the metrics exemplar hand-off Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- api-snapshots/observability.api.md | 3 + api-snapshots/studio.api.md | 1 + .../content/docs/concepts/observability.mdx | 9 + packages/do/__tests__/shard-do.admin.test.ts | 2 +- packages/do/src/shard-do.ts | 6 +- .../__tests__/span-buffer.test.ts | 28 ++ packages/observability/src/log-buffer.ts | 9 + packages/observability/src/span-buffer.ts | 14 +- packages/studio/__tests__/app/studio.test.tsx | 2 +- .../features/logs/logs-panel.test.tsx | 51 +-- .../features/traces/trace-geometry.test.ts | 51 ++- .../features/traces/traces-panel.test.tsx | 132 ++++++- .../studio/src/features/logs/logs-panel.tsx | 39 +- .../src/features/traces/span-detail.tsx | 110 ++++++ .../src/features/traces/trace-geometry.ts | 59 ++- .../src/features/traces/traces-panel.tsx | 346 +++++++++++++----- packages/studio/src/lib/admin.ts | 22 ++ packages/studio/src/locales/en.ts | 12 +- 18 files changed, 772 insertions(+), 124 deletions(-) create mode 100644 packages/studio/src/features/traces/span-detail.tsx diff --git a/api-snapshots/observability.api.md b/api-snapshots/observability.api.md index b36a9a18aa..f8ac378632 100644 --- a/api-snapshots/observability.api.md +++ b/api-snapshots/observability.api.md @@ -425,6 +425,7 @@ interface LogEntry { level: LogLevel; message: string; timestamp: number; + traceId?: string; } ``` @@ -870,6 +871,8 @@ interface TraceSpan { message: string; type: string; }; + events?: SpanEventPoint[]; + kind?: OtlpSpanKind; name: string; offsetMs: number; ok: boolean; diff --git a/api-snapshots/studio.api.md b/api-snapshots/studio.api.md index c71095f909..b025f89b55 100644 --- a/api-snapshots/studio.api.md +++ b/api-snapshots/studio.api.md @@ -650,6 +650,7 @@ interface LogEntry { level: LogLevel; message: string; timestamp: number; + traceId?: string; } ``` diff --git a/apps/docs/src/content/docs/concepts/observability.mdx b/apps/docs/src/content/docs/concepts/observability.mdx index ae10cd3ad3..8868d7a001 100644 --- a/apps/docs/src/content/docs/concepts/observability.mdx +++ b/apps/docs/src/content/docs/concepts/observability.mdx @@ -395,6 +395,15 @@ hibernation. It is a development readout, not a trace store: for retention and cross-instance search, point [`otlpSink`](#otlpsink) at a real collector, where each span is exported as an OTLP `INTERNAL` span carrying its `parentSpanId`. +Expanding a trace gives an elapsed-time ruler over the bars, a per-span detail +block (span id, kind, the full attribute bag, the error, and any +`span.addEvent` / `span.recordException` events), and the `ctx.log` lines the +same dispatch emitted, joined by trace id. **Errors only** narrows the list to +traces where something threw; the search box matches a span name or span id as +well as the trace's own identifiers, so an id pasted from an error report finds +the trace containing it. In the **Logs** panel, a line emitted inside a dispatch +carries a **Trace** link that opens its waterfall on the shard it came from. + ### Generation spans (AI) An AI model call is a span with the OpenTelemetry diff --git a/packages/do/__tests__/shard-do.admin.test.ts b/packages/do/__tests__/shard-do.admin.test.ts index 502676fd4c..59f72232ce 100644 --- a/packages/do/__tests__/shard-do.admin.test.ts +++ b/packages/do/__tests__/shard-do.admin.test.ts @@ -90,7 +90,7 @@ const QUEUE_METADATA_KEY_GUARD: KeysMatch = true; diff --git a/packages/do/src/shard-do.ts b/packages/do/src/shard-do.ts index bc0b7fb91f..850245f1f9 100644 --- a/packages/do/src/shard-do.ts +++ b/packages/do/src/shard-do.ts @@ -3611,7 +3611,7 @@ abstract class ShardDO { userId: this.getCurrentUserId(), }; - this.logs.push({ fields, functionPath, level, message, timestamp: event.ts }); + this.logs.push({ fields, functionPath, level, message, timestamp: event.ts, traceId: event.traceId }); try { emitLogEvent(event); @@ -4486,6 +4486,10 @@ abstract class ShardDO { level: "error", message, timestamp: Date.now(), + // The throw's own trace, so the Traces panel can show this line + // against the waterfall that failed — the whole point of opening + // a trace after seeing a red log row. + traceId: dispatchTrace.traceId, }); // A fresh error row landed, but the failed dispatch's own writes (if diff --git a/packages/observability/__tests__/span-buffer.test.ts b/packages/observability/__tests__/span-buffer.test.ts index 9b3f7a536c..a63d80f114 100644 --- a/packages/observability/__tests__/span-buffer.test.ts +++ b/packages/observability/__tests__/span-buffer.test.ts @@ -123,6 +123,34 @@ describe("foldTraces", () => { expect(DEFAULT_TRACE_LIMIT).toBeGreaterThan(0); }); + it("carries a span's kind and recorded events through to the folded row", () => { + expect.assertions(2); + + // Both are recorded by `ctx.trace` and were dropped by the fold, so a + // handled exception (`span.recordException`) reached the buffer and then + // vanished before anything could render it. + const { traces } = foldTraces([ + span({ + events: [{ attributes: { "exception.type": "TimeoutError" }, name: "exception", ts: 1002 }], + kind: "client", + }), + ]); + + expect(traces[0]?.spans[0]?.kind).toBe("client"); + expect(traces[0]?.spans[0]?.events).toStrictEqual([{ attributes: { "exception.type": "TimeoutError" }, name: "exception", ts: 1002 }]); + }); + + it("omits kind and events entirely for a span that recorded neither", () => { + expect.assertions(2); + + // Absent rather than `undefined`-valued: these ride every admin `getTraces` + // payload, and the common `ctx.trace` span has neither. + const [row] = foldTraces([span()]).traces[0]?.spans ?? []; + + expect(row).not.toHaveProperty("kind"); + expect(row).not.toHaveProperty("events"); + }); + it("still folds a trace whose root span is missing", () => { expect.assertions(2); diff --git a/packages/observability/src/log-buffer.ts b/packages/observability/src/log-buffer.ts index 815cb16a81..edd99a3177 100644 --- a/packages/observability/src/log-buffer.ts +++ b/packages/observability/src/log-buffer.ts @@ -26,6 +26,15 @@ interface LogEntry { level: LogLevel; message: string; timestamp: number; + + /** + * Trace the line was emitted under, when there was an ambient one. The + * `LogEvent` handed to a sink has always carried this; the buffer dropped it, + * which is why the Studio could show a trace's waterfall and the same + * request's log lines without being able to connect the two. Absent for lines + * emitted outside a dispatch (container lifecycle, hibernation-path errors). + */ + traceId?: string; } const DEFAULT_CAPACITY = 500; diff --git a/packages/observability/src/span-buffer.ts b/packages/observability/src/span-buffer.ts index 22af597149..613ff87fb4 100644 --- a/packages/observability/src/span-buffer.ts +++ b/packages/observability/src/span-buffer.ts @@ -9,7 +9,7 @@ * a real collector that can retain and index them across instances. */ import type { LogFields } from "../../../shared/log-fields"; -import type { SpanEvent } from "../../../shared/span-event"; +import type { SpanEvent, SpanEventPoint, SpanKind } from "../../../shared/span-event"; /* eslint-disable import/exports-last -- a data + types module: the public TraceSpan/TraceSummary shapes are declared next to the ring buffer and fold that produce them; grouping all exports at the end would scatter the contract. */ @@ -30,6 +30,16 @@ export interface TraceSpan { message: string; type: string; }; + + /** + * Timestamped occurrences inside the span — `span.addEvent(...)` and + * `span.recordException(...)`. Carried through so a handled retry or a + * swallowed exception is visible on the span it happened in, which is the + * only place it is interpretable. Absent when the body recorded none. + */ + events?: SpanEventPoint[]; + /** OTel `SpanKind`; absent means `"internal"`. */ + kind?: SpanKind; name: string; /** Start of this span relative to the trace's start, in ms. */ offsetMs: number; @@ -271,6 +281,8 @@ export const foldTraces = (spans: ReadonlyArray, limit: number = DEFA depth: depthOf(span), durationMs: span.durationMs, ...(span.error === undefined ? {} : { error: span.error }), + ...(span.events === undefined ? {} : { events: span.events }), + ...(span.kind === undefined ? {} : { kind: span.kind }), name: span.name, // Clamped at 0: a child whose parent was evicted can predate the // anchor, and a negative offset would render as a bar off-canvas. diff --git a/packages/studio/__tests__/app/studio.test.tsx b/packages/studio/__tests__/app/studio.test.tsx index ed0d7a2d9b..931b939c33 100644 --- a/packages/studio/__tests__/app/studio.test.tsx +++ b/packages/studio/__tests__/app/studio.test.tsx @@ -132,7 +132,7 @@ const QUEUE_METADATA_KEY_GUARD: KeysMatch = true; diff --git a/packages/studio/__tests__/features/logs/logs-panel.test.tsx b/packages/studio/__tests__/features/logs/logs-panel.test.tsx index 36be41c493..bd739cf80b 100644 --- a/packages/studio/__tests__/features/logs/logs-panel.test.tsx +++ b/packages/studio/__tests__/features/logs/logs-panel.test.tsx @@ -8,6 +8,7 @@ import type { LogEntry, RequestLogEntry } from "../../../src/lib/admin"; import { ADMIN_FUNCTIONS } from "../../../src/lib/admin"; import type { MockClientHooks } from "../../mock-client"; import { createMockClient } from "../../mock-client"; +import wrapInRouter from "../../render-with-router"; const WINDOWED_ENTRY = /entry-\d+/; @@ -68,15 +69,23 @@ const createClient = (entries: LogEntry[] = ENTRIES, requests: RequestLogEntry[] }, }); -const renderPanel = (mock: MockClientHooks) => ( - - - -); - -/** Switch to the in-memory Errors view (the default view is the durable request log). */ -const switchToErrors = (): void => { - fireEvent.click(screen.getByTestId("lg-view-errors")); +// Under a router: a log row's "Trace" link navigates to `/traces`, so the panel +// now calls `useNavigate` and must mount inside a `RouterProvider`. +const renderPanel = (mock: MockClientHooks) => + wrapInRouter( + + + , + ); + +/** + * Switch to the in-memory Errors view (the default view is the durable request + * log). Awaits the toggle: the panel mounts under a `RouterProvider`, which + * resolves its route before rendering children, so nothing is in the DOM on the + * synchronous tick after `render`. + */ +const switchToErrors = async (): Promise => { + fireEvent.click(await screen.findByTestId("lg-view-errors")); }; describe("logsPanel — requests view (default)", () => { @@ -203,7 +212,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient())); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); const rows = await screen.findAllByTestId("lg-row"); @@ -223,7 +232,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient(withFields))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); const fields = await screen.findByTestId("lg-fields"); @@ -243,7 +252,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient([], []))); - switchToErrors(); + await switchToErrors(); const empty = await screen.findByTestId("lg-empty"); @@ -272,7 +281,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.change(screen.getByTestId("lg-search"), { target: { value: "BOOM" } }); @@ -290,7 +299,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.change(screen.getByTestId("lg-search"), { target: { value: "no-such-message" } }); @@ -306,7 +315,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.click(screen.getByTestId("logs-level-info")); @@ -323,7 +332,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.change(screen.getByTestId("lg-search"), { target: { value: "boom" } }); @@ -354,7 +363,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(createClient(big))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); const rows = await screen.findAllByTestId("lg-row"); @@ -373,7 +382,7 @@ describe("logsPanel — errors view", () => { render(renderPanel(mock)); await screen.findByTestId("lg-empty"); - switchToErrors(); + await switchToErrors(); // No Live toggle: switching to the Errors view subscribes to getLogs. await waitFor(() => { @@ -532,7 +541,7 @@ describe("logsPanel — advanced explorer (errors view)", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.click(screen.getByTestId("logs-level-info")); @@ -549,7 +558,7 @@ describe("logsPanel — advanced explorer (errors view)", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.change(screen.getByTestId("logs-path-filter"), { target: { value: "auth:" } }); @@ -566,7 +575,7 @@ describe("logsPanel — advanced explorer (errors view)", () => { render(renderPanel(createClient(MIXED_ENTRIES))); await screen.findByTestId("lg-table"); - switchToErrors(); + await switchToErrors(); await screen.findAllByTestId("lg-row"); fireEvent.click(screen.getByTestId("logs-summary-toggle")); diff --git a/packages/studio/__tests__/features/traces/trace-geometry.test.ts b/packages/studio/__tests__/features/traces/trace-geometry.test.ts index 35e54025f1..2213507957 100644 --- a/packages/studio/__tests__/features/traces/trace-geometry.test.ts +++ b/packages/studio/__tests__/features/traces/trace-geometry.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from "vitest"; -import { filterTraces, formatSpanDuration, spanBar } from "../../../src/features/traces/trace-geometry"; +import { filterTraces, formatSpanDuration, spanBar, traceTicks } from "../../../src/features/traces/trace-geometry"; import type { TraceSpan, TraceSummary } from "../../../src/lib/admin"; const span = (overrides: Partial = {}): TraceSpan => { @@ -102,6 +102,55 @@ describe("filterTraces", () => { expect(all).not.toBe(traces); expect(all).toEqual(traces); }); + + it("matches on a nested span's name and id, not just the trace's own identifiers", () => { + expect.assertions(2); + + // A span id pasted from an error report or a traceparent header should find + // the trace CONTAINING it — the trace is rarely named after the span you have. + const withSpans = [trace({ spans: [span(), span({ name: "stripe.charge", spanId: "ffff9999" })], traceId: "ccc333" })]; + + expect(filterTraces(withSpans, "stripe.charge")).toHaveLength(1); + expect(filterTraces(withSpans, "ffff9999")).toHaveLength(1); + }); + + it("keeps only failed traces when onlyErrors is set", () => { + expect.assertions(2); + + const mixed = [trace({ ok: true, traceId: "ok1" }), trace({ ok: false, traceId: "bad1" })]; + + expect(filterTraces(mixed, "", true).map((t) => t.traceId)).toEqual(["bad1"]); + expect(filterTraces(mixed, "", false)).toHaveLength(2); + }); + + it("composes the error filter with the search term rather than replacing it", () => { + expect.assertions(1); + + const mixed = [trace({ ok: false, rootName: "signIn", traceId: "bad1" }), trace({ ok: false, rootName: "listMessages", traceId: "bad2" })]; + + expect(filterTraces(mixed, "signin", true).map((t) => t.traceId)).toEqual(["bad1"]); + }); +}); + +describe("traceTicks", () => { + it("spreads labelled gridlines across the trace, ending at its full duration", () => { + expect.assertions(2); + + const ticks = traceTicks(100); + + expect(ticks.map((tick) => tick.percent)).toEqual([25, 50, 75, 100]); + expect(ticks.map((tick) => tick.label)).toEqual(["25ms", "50ms", "75ms", "100ms"]); + }); + + it("draws no ruler for a duration spanBar would lay out full-width", () => { + expect.assertions(3); + + // Same guard as `spanBar`: with no timeline, there is nothing to annotate, + // and evenly-spaced "0ms" labels would imply a resolution the trace lacks. + expect(traceTicks(0)).toEqual([]); + expect(traceTicks(-5)).toEqual([]); + expect(traceTicks(Number.NaN)).toEqual([]); + }); }); describe("formatSpanDuration", () => { diff --git a/packages/studio/__tests__/features/traces/traces-panel.test.tsx b/packages/studio/__tests__/features/traces/traces-panel.test.tsx index 0a50ed8490..1351028ef5 100644 --- a/packages/studio/__tests__/features/traces/traces-panel.test.tsx +++ b/packages/studio/__tests__/features/traces/traces-panel.test.tsx @@ -5,7 +5,7 @@ import { afterEach, describe, expect, it } from "vitest"; import { filterTraces, formatSpanDuration, spanBar } from "../../../src/features/traces/trace-geometry"; import TracesPanel from "../../../src/features/traces/traces-panel"; -import type { TraceSpan, TraceSummary } from "../../../src/lib/admin"; +import type { LogEntry, TraceSpan, TraceSummary } from "../../../src/lib/admin"; import { ADMIN_FUNCTIONS } from "../../../src/lib/admin"; import { clearPendingTraceFilter, peekPendingTraceFilter, writePendingTraceFilter } from "../../../src/lib/trace-handoff"; import type { MockClientHooks } from "../../mock-client"; @@ -92,13 +92,31 @@ const ZERO_TRACE: TraceSummary = { traceId: "trace-zero", }; -const createClient = (traces: TraceSummary[] = TRACES): MockClientHooks => +/** + * Log lines the panel joins to a waterfall by `traceId`. `trace-orphan` has no + * trace at all — the shape of a container-lifecycle line, which must never be + * bucketed under some unrelated waterfall. + */ +const LOG_ENTRIES: LogEntry[] = [ + { functionPath: "messages:send", level: "info", message: "charged card", timestamp: 1_700_000_002_050, traceId: "trace-send" }, + { fields: { orderId: "o-1" }, functionPath: "messages:send", level: "warn", message: "retrying", timestamp: 1_700_000_002_010, traceId: "trace-send" }, + { functionPath: "messages:list", level: "info", message: "listed", timestamp: 1_700_000_001_000, traceId: "trace-list" }, + { level: "info", message: "container started", timestamp: 1_700_000_000_500 }, +]; + +const createClient = (traces: TraceSummary[] = TRACES, entries: LogEntry[] = LOG_ENTRIES): MockClientHooks => createMockClient({ query: (reference): unknown => { if (reference === ADMIN_FUNCTIONS.getTraces) { return { traces }; } + // The panel joins the live log ring to the waterfalls; `getLogs` is + // newest-first, as the real admin read returns it. + if (reference === ADMIN_FUNCTIONS.getLogs) { + return { entries }; + } + throw new Error(`unexpected ${reference}`); }, }); @@ -235,6 +253,116 @@ describe("tracesPanel", () => { expect(message.textContent).toContain("StripeError"); }); + it("keeps a span's detail collapsed until its row is clicked, then shows the full attribute bag", async () => { + expect.assertions(3); + + render(renderPanel(createClient())); + + fireEvent.click(await screen.findByTestId("tr-toggle-trace-send")); + await screen.findAllByTestId("tr-span-row"); + + expect(screen.queryByTestId("tr-span-detail")).toBeNull(); + + fireEvent.click(screen.getByTestId("tr-span-toggle-s1")); + + const detail = await screen.findByTestId("tr-span-detail"); + + // The row's chip is truncated to a fixed-width cell; the detail is the + // only place the id and the whole attribute bag are legible. + expect(detail.textContent).toContain("s1"); + expect(screen.getByTestId("tr-detail-attributes").textContent).toContain("o-1"); + }); + + it("shows a span's kind and recorded events in its detail", async () => { + expect.assertions(2); + + const traced: TraceSummary = { + ...TRACES[1], + spans: [ + { + ...LIST_SPANS[0], + events: [{ attributes: { "exception.type": "TimeoutError" }, name: "exception", ts: 1_700_000_001_004 }], + kind: "client", + }, + ], + } as TraceSummary; + + render(renderPanel(createClient([traced]))); + + fireEvent.click(await screen.findByTestId("tr-toggle-trace-list")); + fireEvent.click(await screen.findByTestId("tr-span-toggle-l0")); + + const events = await screen.findByTestId("tr-detail-events"); + + expect(events.textContent).toContain("exception"); + expect(events.textContent).toContain("TimeoutError"); + }); + + it("shows the log lines the same dispatch emitted under the expanded trace", async () => { + expect.assertions(3); + + render(renderPanel(createClient())); + + fireEvent.click(await screen.findByTestId("tr-toggle-trace-send")); + + const logs = await screen.findByTestId("tr-logs"); + const rows = screen.getAllByTestId("tr-log-row"); + + // Only this trace's two lines: the other trace's line and the untraced + // container line must not be bucketed here. + expect(rows).toHaveLength(2); + expect(logs.textContent).toContain("charged card"); + // `getLogs` is newest-first; a trace's own lines read as a narrative. + expect(rows[0]?.textContent).toContain("retrying"); + }); + + it("omits the log section for a trace whose dispatch logged nothing", async () => { + expect.assertions(1); + + render(renderPanel(createClient(TRACES, []))); + + fireEvent.click(await screen.findByTestId("tr-toggle-trace-send")); + await screen.findAllByTestId("tr-span-row"); + + expect(screen.queryByTestId("tr-logs")).toBeNull(); + }); + + it("narrows the list to failed traces when 'Errors only' is checked", async () => { + expect.assertions(2); + + render(renderPanel(createClient([TRACES[0] as TraceSummary, ERROR_TRACE]))); + + await screen.findByTestId("tr-row-trace-send"); + + fireEvent.click(screen.getByTestId("tr-only-errors")); + + await waitFor(() => { + expect(screen.queryByTestId("tr-row-trace-send")).toBeNull(); + }); + + expect(screen.getByTestId("tr-row-trace-error")).toBeTruthy(); + }); + + it("draws an elapsed-time ruler over the waterfall, and none for a zero-duration trace", async () => { + expect.assertions(3); + + render(renderPanel(createClient())); + + fireEvent.click(await screen.findByTestId("tr-toggle-trace-send")); + + const ruler = await screen.findByTestId("tr-ruler"); + + expect(ruler.textContent).toContain("25ms"); + expect(ruler.textContent).toContain("100ms"); + + render(renderPanel(createClient([ZERO_TRACE]))); + fireEvent.click(await screen.findByTestId("tr-toggle-trace-zero")); + await screen.findAllByTestId("tr-span-bar"); + + // One ruler still on screen from the first render; the zero trace adds none. + expect(screen.getAllByTestId("tr-ruler")).toHaveLength(1); + }); + it("renders visible bars for a zero-duration trace rather than NaN", async () => { expect.assertions(3); diff --git a/packages/studio/src/features/logs/logs-panel.tsx b/packages/studio/src/features/logs/logs-panel.tsx index e737d64e5d..df489ae4e7 100644 --- a/packages/studio/src/features/logs/logs-panel.tsx +++ b/packages/studio/src/features/logs/logs-panel.tsx @@ -1,3 +1,4 @@ +import { useNavigate } from "@tanstack/react-router"; import { useVirtualizer } from "@tanstack/react-virtual"; import type { ChangeEvent, CSSProperties, ReactElement } from "react"; import { useEffect, useMemo, useRef, useState } from "react"; @@ -15,7 +16,9 @@ import { useShardKey } from "../../hooks/use-shard-key"; import { useT } from "../../i18n/i18n-context"; import type { LogEntry, LogLevel, RequestLogEntry, RequestLogQuery, RequestOutcome } from "../../lib/admin"; import { ADMIN_FUNCTIONS } from "../../lib/admin"; +import { fireAndForget } from "../../lib/internal"; import { recordShard } from "../../lib/shard-history"; +import { writePendingTraceFilter } from "../../lib/trace-handoff"; import flooredRectObserver from "../../lib/virtual-rect"; import { ArchiveFeed } from "./archive-feed"; import type { BadgeVariant } from "./log-level-variant"; @@ -55,6 +58,8 @@ interface LogRowProps { readonly index: number; /** react-virtual's ref-callback that measures the rendered row. */ readonly measureRef: (node: HTMLDivElement | null) => void; + /** Open the Traces panel filtered to this line's trace. */ + readonly onOpenTrace: (traceId: string) => void; /** Pixel offset of this row from the top of the virtualized list. */ readonly start: number; } @@ -65,11 +70,19 @@ interface LogRowProps { * offset) is a `useMemo`-stable reference — keeping the hot map body free of * fresh inline objects. */ -const LogRow = ({ entry, index, measureRef, start }: LogRowProps): ReactElement => { +const LogRow = ({ entry, index, measureRef, onOpenTrace, start }: LogRowProps): ReactElement => { + const t = useT(); const style = { ...ROW_BASE_STYLE, transform: `translateY(${String(start)}px)` }; // Rendered once; `""` (no fields, or an empty bag from a worker predating // field normalization) skips the chip entirely rather than showing a blank span. const fields = formatLogFields(entry.fields); + const { traceId } = entry; + + const onTraceClick = (): void => { + if (traceId !== undefined) { + onOpenTrace(traceId); + } + }; return (
)} + {/* + * The drill-down the two panels were missing: a line emitted inside a + * dispatch knows its trace, so it can hand you the waterfall it came + * from instead of leaving you to match timestamps by eye. Absent for + * lines with no ambient trace (container lifecycle, hibernation errors) + * and for any worker predating the buffered `traceId`. + */} + + {traceId === undefined ? null : ( + + )} +
); }; @@ -319,6 +346,7 @@ export const LogsPanel = ({ initialShardKey }: LogsPanelProps): ReactElement => const t = useT(); const [view, setView] = useState("requests"); + const navigate = useNavigate(); const { queryShardKey, setShardKey, shardKey } = useShardKey(initialShardKey); const [search, setSearch] = useState(""); // Errors-view client-side filters: a level allow-set (empty = all levels), a @@ -364,6 +392,14 @@ export const LogsPanel = ({ initialShardKey }: LogsPanelProps): ReactElement => const activeQuery = view === "requests" ? requestsQuery : errorsQuery; const { error, errorSource, isLoading: activeLoading, liveError } = activeQuery; + // Hand a log line's trace to the Traces panel and navigate there — the same + // one-shot handoff the Metrics panel's exemplar link uses, carrying the shard + // so Traces reads the ring the line came from rather than the root's. + const openTrace = (traceId: string): void => { + writePendingTraceFilter({ shardKey: queryShardKey, traceId }); + fireAndForget(navigate({ to: "/traces" })); + }; + // Coerce each view's resolved payload into its entries array (a one-shot read // or live push without an `entries` array yields `[]`); an unloaded gated // query's `undefined` data also yields `[]`. @@ -590,6 +626,7 @@ export const LogsPanel = ({ initialShardKey }: LogsPanelProps): ReactElement => index={virtualRow.index} key={virtualRow.key} measureRef={virtualizer.measureElement} + onOpenTrace={openTrace} start={virtualRow.start} /> ), diff --git a/packages/studio/src/features/traces/span-detail.tsx b/packages/studio/src/features/traces/span-detail.tsx new file mode 100644 index 0000000000..a145852953 --- /dev/null +++ b/packages/studio/src/features/traces/span-detail.tsx @@ -0,0 +1,110 @@ +import type { ReactElement } from "react"; + +import { Badge } from "../../components/ui/badge"; +import { useT } from "../../i18n/i18n-context"; +import type { TraceSpan } from "../../lib/admin"; +import { formatTimestamp } from "../../lib/internal"; +import { formatSpanDuration } from "./trace-geometry"; + +/** + * Render one attribute value for the detail list. Strings print as-is; anything + * structured is JSON so a nested bag stays inspectable rather than collapsing to + * `[object Object]`. A value that cannot be encoded (a cycle surviving + * normalization) falls back to `String(value)` — the row is worth keeping even + * when its value is unprintable. + */ +const formatValue = (value: unknown): string => { + if (typeof value === "string") { + return value; + } + + try { + return JSON.stringify(value); + } catch { + return String(value); + } +}; + +interface DetailFieldProps { + readonly label: string; + readonly value: string; +} + +/** One `label / value` pair of the detail grid, wrapping rather than truncating. */ +const DetailField = ({ label, value }: DetailFieldProps): ReactElement => ( +
+
{label}
+
{value}
+
+); + +interface SpanDetailProps { + readonly span: TraceSpan; +} + +/** + * The expanded detail for one waterfall row: identity, timing, kind, the span's + * FULL attribute bag, its error, and its recorded span events. + * + * The waterfall row itself can only afford a truncated one-line attribute chip, + * which is enough to notice an attribute exists and not enough to read it — the + * `{ orderId, amount, retryCount }` you opened the panel for is exactly what gets + * cut. Everything here is already in the `getTraces` payload; this only stops + * throwing it away at render time. + */ +const SpanDetail = ({ span }: SpanDetailProps): ReactElement => { + const t = useT(); + const attributes = Object.entries(span.attributes ?? {}); + const events = span.events ?? []; + + return ( +
+
+ + + + + +
+ + {span.error !== undefined && ( +
+ {span.error.type} + {/* Pre-wrapped: a stack-ish message keeps its line breaks here, which is the only place in the panel with room for them. */} +

{span.error.message}

+
+ )} + + {attributes.length > 0 && ( +
+

{t("Attributes")}

+
+ {attributes.map(([key, value]) => ( + + ))} +
+
+ )} + + {events.length > 0 && ( +
+

{t("Events")}

+
    + {events.map((event) => ( +
  • + {formatTimestamp(event.ts)} + {event.name} + + {Object.entries(event.attributes ?? {}) + .map(([key, value]) => `${key}=${formatValue(value)}`) + .join(" ")} + +
  • + ))} +
+
+ )} +
+ ); +}; +export default SpanDetail; diff --git a/packages/studio/src/features/traces/trace-geometry.ts b/packages/studio/src/features/traces/trace-geometry.ts index a1d716f521..1a75bf5ee1 100644 --- a/packages/studio/src/features/traces/trace-geometry.ts +++ b/packages/studio/src/features/traces/trace-geometry.ts @@ -20,6 +20,9 @@ import type { TraceSpan, TraceSummary } from "../../lib/admin"; */ const MIN_BAR_PERCENT = 0.5; +/** Gridlines drawn across a waterfall, excluding the 0% edge (the track's own border reads as that). */ +const TICK_COUNT = 4; + /** Clamp `value` into the inclusive `[0, 100]` percentage range. */ const clampPercent = (value: number): number => Math.min(100, Math.max(0, value)); @@ -61,26 +64,40 @@ export const spanBar = (span: TraceSpan, traceDurationMs: number): SpanBar => { /** * Narrow the trace list by a case-insensitive substring over the trace's root - * span name, function path, and full trace id — the identifiers the row shows, - * plus the id so a metric exemplar can filter straight to its trace. An empty or - * whitespace-only term matches everything, so an untouched control never hides a - * trace. + * span name, function path, full trace id, and every span's name and id — so + * pasting a span id from an error report or a `traceparent` header finds the + * trace that contains it, not just the trace it happens to be named after. An + * empty or whitespace-only term matches everything, so an untouched control never + * hides a trace. * @param traces The loaded traces, newest first. * @param search The raw search-box value. + * @param onlyErrors Keep only traces where the root or a descendant span threw. */ -export const filterTraces = (traces: ReadonlyArray, search: string): TraceSummary[] => { +export const filterTraces = (traces: ReadonlyArray, search: string, onlyErrors = false): TraceSummary[] => { const needle = search.trim().toLowerCase(); + const byStatus = onlyErrors ? traces.filter((trace) => !trace.ok) : traces; if (needle === "") { - return [...traces]; + return [...byStatus]; } - return traces.filter( + return byStatus.filter( (trace) => - trace.rootName.toLowerCase().includes(needle) || trace.functionPath.toLowerCase().includes(needle) || trace.traceId.toLowerCase().includes(needle), + trace.rootName.toLowerCase().includes(needle) || + trace.functionPath.toLowerCase().includes(needle) || + trace.traceId.toLowerCase().includes(needle) || + trace.spans.some((span) => span.name.toLowerCase().includes(needle) || span.spanId.toLowerCase().includes(needle)), ); }; +/** One labelled gridline of the waterfall's time ruler. */ +export interface TraceTick { + /** Elapsed time at this gridline, pre-formatted. */ + readonly label: string; + /** Distance from the left edge of the timeline track, in percent. */ + readonly percent: number; +} + /** * Render a millisecond duration for a waterfall row. Sub-millisecond spans are * shown to two decimals so an instant span reads as `0.4ms` rather than @@ -94,3 +111,29 @@ export const formatSpanDuration = (durationMs: number): string => { return durationMs > 0 && durationMs < 1 ? `${durationMs.toFixed(2)}ms` : `${String(Math.round(durationMs))}ms`; }; + +/** + * Evenly-spaced elapsed-time gridlines for a trace's timeline. + * + * A waterfall without a ruler shows the *shape* of a request but not where in it + * a span sits — you can see one bar starts later than another and have to guess + * by how much. Even spacing rather than "nice" round intervals keeps this to + * arithmetic: the labels are derived from the duration, so they land on whatever + * values the trace actually has. + * + * A non-positive or non-finite duration yields no ticks, matching {@link spanBar}, + * which lays every span out full-width in that case — there is no timeline to + * annotate. + * @param traceDurationMs The enclosing trace's total duration, in ms. + */ +export const traceTicks = (traceDurationMs: number): TraceTick[] => { + if (!Number.isFinite(traceDurationMs) || traceDurationMs <= 0) { + return []; + } + + return Array.from({ length: TICK_COUNT }, (_unused, index) => { + const fraction = (index + 1) / TICK_COUNT; + + return { label: formatSpanDuration(traceDurationMs * fraction), percent: fraction * 100 }; + }); +}; diff --git a/packages/studio/src/features/traces/traces-panel.tsx b/packages/studio/src/features/traces/traces-panel.tsx index 0aead10d5c..6d93f8eb6c 100644 --- a/packages/studio/src/features/traces/traces-panel.tsx +++ b/packages/studio/src/features/traces/traces-panel.tsx @@ -1,5 +1,5 @@ import type { ChangeEvent, CSSProperties, ReactElement } from "react"; -import { useEffect, useState } from "react"; +import { useEffect, useMemo, useState } from "react"; // Bundler-inlined, zero-dep `key=value` field renderer shared with the runtime // sinks and the dev-terminal formatter (see CLAUDE.md `shared/` rules). @@ -8,19 +8,22 @@ import ErrorAlert from "../../components/error-alert"; import { LiveError } from "../../components/live-status"; import { ShardInput } from "../../components/shard-input"; import { Badge } from "../../components/ui/badge"; +import { Checkbox } from "../../components/ui/checkbox"; import { EmptyState } from "../../components/ui/empty-state"; import { Input } from "../../components/ui/input"; import { useAdminQuery } from "../../hooks/use-admin-query"; import { useShardKey } from "../../hooks/use-shard-key"; import { useT } from "../../i18n/i18n-context"; -import type { TraceSpan, TracesResult, TraceSummary } from "../../lib/admin"; +import type { LogEntry, LogsResult, TraceSpan, TracesResult, TraceSummary } from "../../lib/admin"; import { ADMIN_FUNCTIONS } from "../../lib/admin"; import { formatTimestamp } from "../../lib/internal"; import { recordShard } from "../../lib/shard-history"; import type { PendingTraceFilter } from "../../lib/trace-handoff"; import { clearPendingTraceFilter, peekPendingTraceFilter } from "../../lib/trace-handoff"; import { cn } from "../../lib/utils"; -import { filterTraces, formatSpanDuration, spanBar } from "./trace-geometry"; +import { LEVEL_VARIANT } from "../logs/log-level-variant"; +import SpanDetail from "./span-detail"; +import { filterTraces, formatSpanDuration, spanBar, traceTicks } from "./trace-geometry"; /** Pixels of indent per nesting level of a span row. */ const INDENT_PER_DEPTH = 14; @@ -32,7 +35,105 @@ const INDENT_PER_DEPTH = 14; */ const tracesOf = (result: TracesResult | undefined): TraceSummary[] => (Array.isArray(result?.traces) ? result.traces : []); +/** Add or remove one id from a set, returning a fresh set so React sees the change. */ +const toggled = (previous: ReadonlySet, id: string): ReadonlySet => { + const next = new Set(previous); + + if (next.has(id)) { + next.delete(id); + } else { + next.add(id); + } + + return next; +}; + +interface TraceLogsProps { + /** Lines emitted under this trace, oldest first. */ + readonly entries: ReadonlyArray; +} + +/** + * The `ctx.log` lines emitted under one trace, shown beneath its waterfall. + * + * This is the drill-down the Traces page was missing: the waterfall says WHICH + * span was slow or threw, and the log lines say what the code thought it was + * doing at the time. Both were already on the wire — the log buffer simply + * dropped the `traceId` that joins them (see `@lunora/observability`'s + * `LogEntry`), so the two panels could never be put side by side. + * + * Read from the same live `getLogs` ring the Logs panel uses, so no extra RPC and + * no extra retention: a line evicted from that ring disappears here too. + */ +const TraceLogs = ({ entries }: TraceLogsProps): ReactElement => { + const t = useT(); + + return ( +
+

{t("Logs ({count})", { count: entries.length })}

+
+ {entries.map((entry) => { + const fields = formatLogFields(entry.fields); + + return ( +
+ {formatTimestamp(entry.timestamp)} + + {entry.level} + + + {entry.message} + {fields === "" ? null : {fields}} + +
+ ); + })} +
+
+ ); +}; + +interface TimeRulerProps { + /** Total duration the ruler annotates, in ms. */ + readonly traceDurationMs: number; +} + +/** + * Elapsed-time gridlines across the waterfall's timeline track, aligned with the + * span bars' own column so a bar's left edge can be read off a label. Renders + * nothing for a zero-duration trace, where {@link spanBar} lays every span out + * full-width and there is no timeline to annotate. + */ +const TimeRuler = ({ traceDurationMs }: TimeRulerProps): ReactElement | null => { + const ticks = traceTicks(traceDurationMs); + + if (ticks.length === 0) { + return null; + } + + return ( +
+ {/* Spacer columns mirroring SpanRow's name cell, so the track below starts at the same x. */} + + + {ticks.map((tick) => ( + + {tick.label} + + ))} + + + + +
+ ); +}; + interface SpanRowProps { + /** Whether this span's detail block is open. */ + readonly expanded: boolean; + /** Lifts the per-row click out of the map so the row carries no inline closure. */ + readonly onToggle: (spanId: string) => void; readonly span: TraceSpan; /** The enclosing trace's total duration, the denominator for the bar geometry. */ readonly traceDurationMs: number; @@ -42,8 +143,12 @@ interface SpanRowProps { * One waterfall row: the span's name indented by its server-computed `depth`, a * bar positioned by `offsetMs` and sized by `durationMs`, its duration, its * structured attributes, and — when the body threw — an error chip plus message. + * + * Clicking the row opens {@link SpanDetail} beneath it. The row's attribute and + * error cells are hard-truncated to keep the waterfall scannable, so the detail + * block is the only place the full values are legible. */ -const SpanRow = ({ span, traceDurationMs }: SpanRowProps): ReactElement => { +const SpanRow = ({ expanded, onToggle, span, traceDurationMs }: SpanRowProps): ReactElement => { const t = useT(); const { leftPercent, widthPercent } = spanBar(span, traceDurationMs); @@ -54,82 +159,100 @@ const SpanRow = ({ span, traceDurationMs }: SpanRowProps): ReactElement => { const nameStyle: CSSProperties = { paddingLeft: span.depth * INDENT_PER_DEPTH }; const barStyle: CSSProperties = { left: `${String(leftPercent)}%`, width: `${String(widthPercent)}%` }; + const onClick = (): void => { + onToggle(span.spanId); + }; + return ( -
- - {span.ok ? null : ( - - ● - - )} - {span.name} - - {/* - * The bar cell carries no text, so a screen reader would announce an - * empty gridcell. Label it with the waterfall position it encodes — - * where in the trace the span starts and how long it ran — which is - * otherwise available only visually. - */} - +
+ aria-label={t("starts {offset} in, runs {duration}", { + duration: formatSpanDuration(span.durationMs), + offset: formatSpanDuration(span.offsetMs), + })} + className="relative h-3 flex-1 overflow-hidden rounded-sm bg-muted" + > + + + {formatSpanDuration(span.durationMs)} + {/* + * Error and attributes get their own cells rather than sharing one. + * Sharing meant a failed span dropped its attributes — hiding + * `{ orderId }` on exactly the span you opened the panel to debug. + * Both are truncated here; the detail block below prints them whole. + */} + + {span.error === undefined ? null : ( + + {`${span.error.type}: ${span.error.message}`} + + )} + + + {attributes === "" ? null : ( + + {attributes} + + )} + + + + {expanded && ( +
+ +
+ )} + ); }; interface TraceRowProps { /** Whether this trace's waterfall is currently expanded. */ readonly expanded: boolean; + /** Span ids whose detail block is open, across the whole list. */ + readonly expandedSpans: ReadonlySet; + /** `ctx.log` lines emitted under this trace, oldest first. Empty when none were captured. */ + readonly logs: ReadonlyArray; /** Lifts the per-row click out of the map so the row carries no inline closure. */ readonly onToggle: (traceId: string) => void; + readonly onToggleSpan: (spanId: string) => void; readonly trace: TraceSummary; } /** * One trace in the list: a clickable summary header (root name, function path, - * total duration, span count, ok/error badge) that expands into the waterfall. + * total duration, span count, ok/error badge) that expands into the waterfall, + * the spans' detail blocks, and the log lines the same dispatch emitted. */ -const TraceRow = ({ expanded, onToggle, trace }: TraceRowProps): ReactElement => { +const TraceRow = ({ expanded, expandedSpans, logs, onToggle, onToggleSpan, trace }: TraceRowProps): ReactElement => { const t = useT(); const onClick = (): void => { @@ -166,16 +289,20 @@ const TraceRow = ({ expanded, onToggle, trace }: TraceRowProps): ReactElement => {expanded && ( -
- {trace.spans.map((span) => ( - - ))} +
+ +
    + {trace.spans.map((span) => ( + + ))} +
+ {logs.length > 0 && }
)}
@@ -199,6 +326,12 @@ interface TracesPanelProps { * and an `offsetMs`, so this panel does no tree math — it indents by `depth` and * sizes each bar from `offsetMs`/`durationMs` via the pure {@link spanBar} helper. * + * Expanding a trace gives the three things a waterfall alone cannot: an elapsed-time + * ruler to read a bar's position against, a per-span detail block with the FULL + * attribute bag / error / recorded span events (the row can only afford a truncated + * chip), and the `ctx.log` lines the same dispatch emitted, joined by `traceId` + * from the live log ring. + * * The backing span ring is bounded and in-memory, so it resets on hibernation or * restart and a trace can legitimately arrive partial. This is a local-development * readout, NOT a durable trace store — production tracing ships to a real @@ -219,7 +352,9 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { pending?.shardKey !== undefined && pending.shardKey !== "" ? pending.shardKey : (initialShardKey ?? ""), ); const [search, setSearch] = useState(pending?.traceId ?? ""); + const [onlyErrors, setOnlyErrors] = useState(false); const [expanded, setExpanded] = useState>(() => new Set()); + const [expandedSpans, setExpandedSpans] = useState>(() => new Set()); // Consume the hand-off on mount (a committed boundary): clear the store so a // later manual visit isn't re-filtered. Clearing needs no setState, so this @@ -235,6 +370,14 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { { live: true, shardKey: queryShardKey }, ); + // The same live log ring the Logs panel reads, joined to the waterfalls by + // `traceId`. A second read rather than a new correlated RPC: both rings are + // already pushed live over this socket, and joining two cheap reads client-side + // avoids a bespoke server-side join that would only ever serve this panel. + // Its failure is deliberately NOT surfaced — losing the log ring must degrade + // the trace detail, never blank the waterfalls the panel exists to show. + const { data: logsData } = useAdminQuery(ADMIN_FUNCTIONS.getLogs, {}, { live: true, shardKey: queryShardKey }); + // Record the browsed shard into recent-shards history once the read resolves, // so a shard visited here shows up in every other panel's autocomplete — // matching the nine other shard-scoped panels. @@ -252,7 +395,32 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { const truncated = total > traces.length; // The span ring is not a queryable store, so the search runs client-side over // the loaded traces (the same model as the Logs panel's Errors view). - const filtered = filterTraces(traces, search); + const filtered = filterTraces(traces, search, onlyErrors); + + // Index the log ring by trace once per read rather than scanning it per + // expanded trace: the ring holds up to 500 entries and every trace row would + // otherwise re-walk all of them on every render. + const logsByTrace = useMemo(() => { + const index = new Map(); + + // `getLogs` returns newest-first; a trace's own lines read as a narrative, + // so reverse into chronological order as they are bucketed. + for (const entry of (logsData?.entries ?? []).toReversed()) { + if (entry.traceId === undefined) { + continue; + } + + const bucket = index.get(entry.traceId); + + if (bucket === undefined) { + index.set(entry.traceId, [entry]); + } else { + bucket.push(entry); + } + } + + return index; + }, [logsData]); const onSearchChange = (event: ChangeEvent): void => { setSearch(event.target.value); @@ -260,17 +428,11 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { // Toggle one trace in/out of the expanded set without mutating the prior set. const onToggle = (traceId: string): void => { - setExpanded((previous) => { - const next = new Set(previous); - - if (next.has(traceId)) { - next.delete(traceId); - } else { - next.add(traceId); - } + setExpanded((previous) => toggled(previous, traceId)); + }; - return next; - }); + const onToggleSpan = (spanId: string): void => { + setExpandedSpans((previous) => toggled(previous, spanId)); }; // A count of 0 while the first read is still in flight means the ring hasn't @@ -286,9 +448,13 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { className="h-8 w-56" data-testid="tr-search" onChange={onSearchChange} - placeholder={t("search trace or function")} + placeholder={t("search trace, span, or function")} value={search} /> + @@ -326,7 +492,15 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { {error === null && filtered.length > 0 && (
{filtered.map((trace) => ( - + ))}
)} diff --git a/packages/studio/src/lib/admin.ts b/packages/studio/src/lib/admin.ts index 220ad58026..b1d3d43875 100644 --- a/packages/studio/src/lib/admin.ts +++ b/packages/studio/src/lib/admin.ts @@ -762,6 +762,14 @@ export interface LogEntry { level: LogLevel; message: string; timestamp: number; + + /** + * Trace the line was emitted under. Present for lines emitted inside a + * dispatch; absent for container-lifecycle entries, hibernation-path errors, + * and any worker predating the field. What the Logs panel's "Trace" link and + * the Traces panel's correlated-logs section both key on. + */ + traceId?: string; } /** Payload of a `__lunora_admin__:getLogs` call: the buffered entries, newest first. */ @@ -1042,6 +1050,20 @@ export interface TraceSpan { message: string; type: string; }; + + /** + * Timestamped occurrences inside the span — `span.addEvent(...)` / + * `span.recordException(...)`. A handled retry or a swallowed exception, which + * only makes sense against the span it happened in. Absent when none. + */ + events?: { + attributes?: Record; + name: string; + /** Epoch-ms the event was recorded. */ + ts: number; + }[]; + /** OTel `SpanKind`. Absent means `"internal"` — the overwhelming majority of `ctx.trace` spans. */ + kind?: "client" | "consumer" | "internal" | "producer" | "server"; /** Caller-supplied span name, e.g. `"stripe.charge"`. */ name: string; /** Start of this span relative to the trace's start, in ms. Clamped at 0 server-side. */ diff --git a/packages/studio/src/locales/en.ts b/packages/studio/src/locales/en.ts index 33a3799753..908bc10b3a 100644 --- a/packages/studio/src/locales/en.ts +++ b/packages/studio/src/locales/en.ts @@ -1254,7 +1254,8 @@ const MESSAGE_IDS = [ "Traces", "Recent ctx.trace waterfalls for this shard — the drill-down from a log line.", "Search traces", - "search trace or function", + "search trace, span, or function", + "Errors only", "Recent traces", "Trace waterfall", "Errored span", @@ -1262,6 +1263,15 @@ const MESSAGE_IDS = [ "starts {offset} in, runs {duration}", "Showing the {shown} most recent of {total} traces in the buffer.", "No traces", + // Observability — expanded span detail + the dispatch's correlated log lines + "Span ID", + "Parent span ID", + "— (trace root)", + "Started at", + "+{offset}", + "Duration", + "Attributes", + "Logs ({count})", "Traces recorded with ctx.trace show up here as your app handles traffic. The span buffer resets when the shard hibernates.", // Observability — grouped error Issues "Issues", From 8f1ba4e6168f39517d58c50d632c0f191fd12c0c Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 8 Aug 2026 16:26:37 +0200 Subject: [PATCH 2/9] feat(studio): seed the mock client with correlated traces and span events MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The backend-free mock is what `main.mock.tsx` renders for design work, and it answered `getLogs` with entries carrying no `traceId` and `getTraces` with spans carrying no `kind` or events — so the trace/log correlation, the span detail's kind row, and the events list were all invisible in mock mode. The log fixtures already lined up with the trace fixtures by function path, so this only stamps the matching trace ids and adds a handled retry plus a recorded exception. One log line is deliberately left untraced, standing in for a container-lifecycle entry. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- apps/studio/src/mock/dev-client.ts | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/apps/studio/src/mock/dev-client.ts b/apps/studio/src/mock/dev-client.ts index c227b4a6ec..c09a0abf56 100644 --- a/apps/studio/src/mock/dev-client.ts +++ b/apps/studio/src/mock/dev-client.ts @@ -127,6 +127,11 @@ const TRACES = [ attributes: { method: "POST", url: "api.stripe.com/v1/charges" }, depth: 2, durationMs: 200, + // A retried-then-succeeded outbound call: `kind` and the recorded + // events are what the span-detail block exists to show, and a + // handled retry is invisible anywhere else in the Studio. + events: [{ attributes: { "retry.attempt": 1 }, name: "http.retry", ts: now - 3900 }], + kind: "client", name: "http.post", offsetMs: 28, ok: true, @@ -170,6 +175,8 @@ const TRACES = [ depth: 1, durationMs: 165, error: { message: "card_declined: Your card was declined.", type: "StripeError" }, + events: [{ attributes: { "exception.type": "StripeError" }, name: "exception", ts: now - 14_900 }], + kind: "client", name: "stripe.charge", offsetMs: 10, ok: false, @@ -379,10 +386,20 @@ const dataFor = (reference: string, args: unknown): unknown => { } case ADMIN_FUNCTIONS.getLogs: { return { + // `traceId` matches the `TRACES` fixtures above, so the Traces + // panel's correlated-log section and the Logs panel's Trace link + // both have something to resolve. The last line deliberately has + // none — a container-lifecycle entry, emitted outside any dispatch. entries: [ - { functionPath: "posts:publish", level: "error", message: "Rate limited (429) from upstream", timestamp: now - 4000 }, - { functionPath: "messages:list", level: "info", message: "Served 128 rows in 12ms", timestamp: now - 9000 }, - { functionPath: "messages:send", level: "warn", message: "Slow write: 28ms", timestamp: now - 15_000 }, + { + functionPath: "posts:publish", + level: "error", + message: "Rate limited (429) from upstream", + timestamp: now - 4000, + traceId: "trace-publish", + }, + { functionPath: "messages:list", level: "info", message: "Served 128 rows in 12ms", timestamp: now - 9000, traceId: "trace-list" }, + { functionPath: "messages:send", level: "warn", message: "Slow write: 28ms", timestamp: now - 15_000, traceId: "trace-send" }, { level: "debug", message: "Reactive cache warm (312 entries)", timestamp: now - 22_000 }, ], }; From a891bb31b9d142f028e5e8ddc289fb6d26bf9133 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 8 Aug 2026 20:40:40 +0200 Subject: [PATCH 3/9] feat(observability): record the dispatch trace id on the durable request log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The in-memory log buffer now carries a trace id, but the durable request log — the one that survives hibernation and records EVERY dispatch — did not, so the Requests view had no way back to a waterfall and a SIEM receiving the Logpush event could not join it to the collector's spans for the same request. - add a `trace_id` column via a guarded ALTER, mirroring `error_fingerprint`; each ALTER gets its own try so a shard that already has one column still gains the other - stamp it from the shared per-request anchor, so the row lands in the same trace as that dispatch's spans and log lines - emit it on the Logpush console event — the join key on the far side - never redact it: a trace id is an opaque identifier, and masking it destroys the only thing it is for - link a request row to its trace, extracting the cell both log views now share Note the deliberate retention asymmetry, documented at the module, the type, the component, and the docs page: this log is durable while the span ring it points at is in-memory, so a link on a row older than the current DO instance resolves in an external collector but not against the local waterfall. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- api-snapshots/observability.api.md | 2 + .../content/docs/concepts/observability.mdx | 14 ++- apps/studio/src/mock/dev-client.ts | 15 +++ packages/do/src/shard-do.ts | 4 + .../__tests__/request-log.test.ts | 101 ++++++++++++++++++ packages/observability/src/request-log.ts | 68 ++++++++++-- .../features/logs/logs-panel.test.tsx | 51 ++++++++- .../studio/src/features/logs/logs-panel.tsx | 69 ++++++++---- packages/studio/src/lib/admin.ts | 11 ++ 9 files changed, 300 insertions(+), 35 deletions(-) diff --git a/api-snapshots/observability.api.md b/api-snapshots/observability.api.md index f8ac378632..be22a52ca2 100644 --- a/api-snapshots/observability.api.md +++ b/api-snapshots/observability.api.md @@ -56,6 +56,7 @@ interface AppendRequestLogEntry { subscriptionsReRun?: number; tablesRead?: string[]; tablesWritten?: string[]; + traceId?: string; ts: number; userId?: string; } @@ -681,6 +682,7 @@ interface RequestLogEntry { subscriptionsReRun: number; tablesRead: string[]; tablesWritten: string[]; + traceId?: string; ts: number; userId?: string; } diff --git a/apps/docs/src/content/docs/concepts/observability.mdx b/apps/docs/src/content/docs/concepts/observability.mdx index 8868d7a001..a73a1b17dd 100644 --- a/apps/docs/src/content/docs/concepts/observability.mdx +++ b/apps/docs/src/content/docs/concepts/observability.mdx @@ -401,8 +401,18 @@ block (span id, kind, the full attribute bag, the error, and any same dispatch emitted, joined by trace id. **Errors only** narrows the list to traces where something threw; the search box matches a span name or span id as well as the trace's own identifiers, so an id pasted from an error report finds -the trace containing it. In the **Logs** panel, a line emitted inside a dispatch -carries a **Trace** link that opens its waterfall on the shard it came from. +the trace containing it. Both **Logs** views carry a **Trace** link on rows +emitted inside a dispatch, opening the waterfall on the shard it came from. + +:::caution[The Requests view's Trace link is best-effort] +The durable request log records each dispatch's trace id, but it **outlives** the +span ring it points at: the log survives hibernation and the ring does not. A +Trace link on a row older than the current DO instance therefore lands on an +empty Traces panel — the trace has aged out locally. The id itself stays valid +wherever [`otlpSink`](#otlpsink) ships spans, which is where a deployed app's +traces are retained; it is also emitted on the `Logpush` console event, so a SIEM +can join a request to its spans. +::: ### Generation spans (AI) diff --git a/apps/studio/src/mock/dev-client.ts b/apps/studio/src/mock/dev-client.ts index c09a0abf56..d4aa2bf032 100644 --- a/apps/studio/src/mock/dev-client.ts +++ b/apps/studio/src/mock/dev-client.ts @@ -437,6 +437,7 @@ const dataFor = (reference: string, args: unknown): unknown => { subscriptionsReRun: 0, tablesRead: ["messages"], tablesWritten: [], + traceId: "trace-list", ts: now - 4000, }, { @@ -448,8 +449,22 @@ const dataFor = (reference: string, args: unknown): unknown => { subscriptionsReRun: 0, tablesRead: ["posts"], tablesWritten: [], + traceId: "trace-publish", ts: now - 9000, }, + // No `traceId`: a row written before the column existed. The + // Requests view must render it with no Trace link rather than + // an empty button. + { + durationMs: 8, + functionPath: "messages:send", + outcome: "ok", + seq: 8999, + subscriptionsReRun: 2, + tablesRead: [], + tablesWritten: ["messages"], + ts: now - 14_000, + }, ], }; } diff --git a/packages/do/src/shard-do.ts b/packages/do/src/shard-do.ts index 9da83c84c2..3e65205365 100644 --- a/packages/do/src/shard-do.ts +++ b/packages/do/src/shard-do.ts @@ -6443,6 +6443,10 @@ abstract class ShardDO { shardKey: this.runner.shardKey, tablesRead: this.currentRequestReadTables === undefined ? [] : [...this.currentRequestReadTables], tablesWritten, + // Read from the shared per-request anchor rather than re-resolved, so + // the row lands in the SAME trace as this dispatch's `ctx.trace` spans + // and its `ctx.log` lines. `undefined` outside a dispatch-scoped call. + traceId: this.currentRequestTrace?.traceId, ts: Date.now(), userId: this.getCurrentUserId(), }; diff --git a/packages/observability/__tests__/request-log.test.ts b/packages/observability/__tests__/request-log.test.ts index 7c1d6adeb2..69e43e03d6 100644 --- a/packages/observability/__tests__/request-log.test.ts +++ b/packages/observability/__tests__/request-log.test.ts @@ -15,6 +15,14 @@ import { } from "../src/request-log"; import createSqliteExec from "./_helpers/node-sqlite"; +/** + * 32-hex trace ids, built by `repeat` rather than written as literals: a real + * trace id is high-entropy, and a literal one trips the repo's `no-secrets` + * lint. The tests only need the right shape and length. + */ +const TRACE_ID = "ab".repeat(16); +const OTHER_TRACE_ID = "cd".repeat(16); + /** One minimal `ok` entry, overridable per case. */ const entry = (overrides: Partial[1]> = {}): Parameters[1] => { return { @@ -83,6 +91,87 @@ describe("request-log module", () => { } }); + it("round-trips the dispatch's trace id, leaving it undefined when there was none", () => { + expect.assertions(2); + + const database = createSqliteExec(); + + try { + appendRequestLogEntry(database.sql, entry({ traceId: TRACE_ID })); + appendRequestLogEntry(database.sql, entry({ functionPath: "cron:sweep" })); + + const rows = readRequestLog(database.sql); + + // Newest first, so the trace-less cron row leads. + expect(rows[0]!.traceId).toBeUndefined(); + expect(rows[1]!.traceId).toBe(TRACE_ID); + } finally { + database.close(); + } + }); + + it("never redacts the trace id — it is an opaque identifier, and masking it would destroy its only purpose", () => { + expect.assertions(1); + + const database = createSqliteExec(); + + try { + // A 32-hex string is exactly the shape a redaction rule might mistake + // for a token, and the correlation key is worthless once masked. + appendRequestLogEntry(database.sql, entry({ redactedArgs: { password: "hunter2" }, traceId: TRACE_ID })); + + expect(readRequestLog(database.sql)[0]!.traceId).toBe(TRACE_ID); + } finally { + database.close(); + } + }); + + it("adds trace_id to a shard whose table predates the column, without losing its rows", () => { + expect.assertions(4); + + const database = createSqliteExec(); + + try { + // The pre-column schema, verbatim: a shard that logged before this + // change has exactly this table and must gain the column on the next + // ensure — the guarded ALTER path, which a fresh CREATE never exercises. + database.raw( + `CREATE TABLE "${REQUEST_LOG_TABLE}" ( + seq INTEGER PRIMARY KEY AUTOINCREMENT, + ts REAL NOT NULL, + function_path TEXT NOT NULL, + shard_key TEXT, + user_id TEXT, + identity TEXT, + args TEXT, + outcome TEXT NOT NULL, + error_message TEXT, + error_fingerprint TEXT, + duration_ms REAL NOT NULL, + tables_read TEXT NOT NULL DEFAULT '[]', + tables_written TEXT NOT NULL DEFAULT '[]', + cache_hit INTEGER, + subscriptions_rerun INTEGER NOT NULL DEFAULT 0 + )`, + ); + database.raw(`INSERT INTO "${REQUEST_LOG_TABLE}" (ts, function_path, outcome, duration_ms) VALUES (?, ?, ?, ?)`, 900, "legacy:call", "ok", 3); + + ensureRequestLogTable(database.sql); + appendRequestLogEntry(database.sql, entry({ traceId: OTHER_TRACE_ID })); + + const rows = readRequestLog(database.sql); + + expect(rows).toHaveLength(2); + expect(rows[0]!.traceId).toBe(OTHER_TRACE_ID); + // The pre-existing row survives and simply has no trace id — the key + // is omitted rather than set to `undefined`, so assert both. + expect(rows[1]!.functionPath).toBe("legacy:call"); + expect(rows[1]!.traceId).toBeUndefined(); + } finally { + database.close(); + } + }); + it("records error outcome with the failure message", () => { expect.assertions(2); @@ -582,6 +671,18 @@ describe("emitRequestLogEvent (PLAN3 §3.3 Logpush emit)", () => { expect(JSON.stringify(event)).not.toContain("alice@example.com"); }); + it("carries the trace id so a SIEM can join the event to the collector's spans", () => { + expect.assertions(1); + + const log = vi.spyOn(console, "log").mockImplementation(() => {}); + + emitRequestLogEvent(entry({ traceId: TRACE_ID })); + + const event = JSON.parse(log.mock.calls.at(0)?.at(0) as string) as Record; + + expect(event.traceId).toBe(TRACE_ID); + }); + it("captureRaw emits un-redacted args/identity (the dev escape hatch)", () => { expect.assertions(2); diff --git a/packages/observability/src/request-log.ts b/packages/observability/src/request-log.ts index b926dbeb93..c0c68f4292 100644 --- a/packages/observability/src/request-log.ts +++ b/packages/observability/src/request-log.ts @@ -12,6 +12,16 @@ * masking PII in the message can't change which Issue a row groups into — see * {@link appendRequestLogEntry} and {@link readErrorIssues}. * + * Each row also carries the dispatch's `trace_id`. Note the deliberate + * retention asymmetry: this table is DURABLE and bounded by row count, while + * the `ctx.trace` span ring it correlates to is in-memory and resets on + * hibernation. A trace id on a row older than the current DO instance therefore + * resolves in an external collector but NOT against the local waterfall, and + * the Studio treats a local miss as ordinary rather than as an error. Recording + * it is still worth it: the id is what joins this row to the collector's spans + * and to the `Logpush`-shipped console event, which is where a deployed app's + * traces actually live. + * * Modelled exactly on `audit-log.ts` (the CDC-log helpers in `ctx-db.ts` * `migrateCdcLog`/`appendCdcChange`/`readCdcChanges`/`trimCdcChanges` and the * reserved-table pattern in `data-migration.ts` `ensureStateTable`). Unlike the @@ -74,6 +84,18 @@ interface RequestLogEntry { tablesRead: string[]; /** Tables the handler wrote (from the change tracker); empty for a read-only dispatch. */ tablesWritten: string[]; + + /** + * W3C trace id (32-hex) of the dispatch, or `undefined` for a row appended + * before this column existed. + * + * The correlation key, NOT a guarantee the trace is still readable: this + * table is durable and bounded by row count, while the `ctx.trace` span ring + * it would join to is in-memory and dies on hibernation. So the id reliably + * resolves in an external collector (whatever `otlpSink` ships to), and only + * opportunistically against the local waterfall — see the module docstring. + */ + traceId?: string; /** Wall-clock millis when the dispatch completed. */ ts: number; /** Acting userId forwarded by the runtime, or `undefined` when anonymous. */ @@ -93,6 +115,7 @@ interface AppendRequestLogEntry { subscriptionsReRun?: number; tablesRead?: string[]; tablesWritten?: string[]; + traceId?: string; ts: number; userId?: string; } @@ -245,12 +268,18 @@ const redactArgs = (value: unknown, captureRaw = false): unknown => { * * `error_fingerprint` is the {@link fingerprintError} grouping hash captured * from the RAW `error_message` at write time, before {@link appendRequestLogEntry} - * redacts it — see that function's docstring. It is added via a guarded - * `ALTER TABLE` rather than baked into the `CREATE`, mirroring - * `function-metrics.ts`'s `ensureFunctionMetricsTables`, so a shard whose - * `__lunora_reqlog__` predates this column gains it on the next call without a - * migration. SQLite has no `ADD COLUMN IF NOT EXISTS`, so the duplicate-column - * error from a re-run (or the freshly-created schema above) is swallowed. + * redacts it — see that function's docstring. `trace_id` is the dispatch's W3C + * trace id, the correlation key to the span ring and to whatever collector + * `otlpSink` ships to. + * + * Both are added via a guarded `ALTER TABLE` rather than baked into the + * `CREATE`, mirroring `function-metrics.ts`'s `ensureFunctionMetricsTables`, so + * a shard whose `__lunora_reqlog__` predates a column gains it on the next call + * without a migration. SQLite has no `ADD COLUMN IF NOT EXISTS`, so the + * duplicate-column error from a re-run (or the freshly-created schema above) is + * swallowed. Each `ALTER` needs its OWN try — one shared block would let the + * first column's duplicate error skip the second column's add, leaving a shard + * that has `error_fingerprint` but never gains `trace_id`. */ const ensureRequestLogTable = (sql: SqlExec): void => { runSql( @@ -266,6 +295,7 @@ const ensureRequestLogTable = (sql: SqlExec): void => { outcome TEXT NOT NULL, error_message TEXT, error_fingerprint TEXT, + trace_id TEXT, duration_ms REAL NOT NULL, tables_read TEXT NOT NULL DEFAULT '[]', tables_written TEXT NOT NULL DEFAULT '[]', @@ -279,6 +309,12 @@ const ensureRequestLogTable = (sql: SqlExec): void => { } catch { // Column already exists — no-op. } + + try { + runSql(sql, `ALTER TABLE "${REQUEST_LOG_TABLE}" ADD COLUMN trace_id TEXT`); + } catch { + // Column already exists — no-op. + } }; /** Serialise a table list to a sorted, de-duplicated JSON array so the `LIKE` table-touched filter matches deterministically. */ @@ -331,8 +367,8 @@ const appendRequestLogEntry = (sql: SqlExec, entry: AppendRequestLogEntry, optio runSql( sql, `INSERT INTO "${REQUEST_LOG_TABLE}" - (ts, function_path, shard_key, user_id, identity, args, outcome, error_message, error_fingerprint, duration_ms, tables_read, tables_written, cache_hit, subscriptions_rerun) - VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, + (ts, function_path, shard_key, user_id, identity, args, outcome, error_message, error_fingerprint, trace_id, duration_ms, tables_read, tables_written, cache_hit, subscriptions_rerun) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, entry.ts, entry.functionPath, // eslint-disable-next-line unicorn/no-null -- SQL NULL is the correct value for a request with no shard key / anonymous caller / absent field. @@ -353,6 +389,10 @@ const appendRequestLogEntry = (sql: SqlExec, entry: AppendRequestLogEntry, optio entry.errorMessage === undefined ? null : redactArgs(entry.errorMessage, captureRaw), // eslint-disable-next-line unicorn/no-null -- success path, or a legacy row appended before this column existed. errorFingerprint ?? null, + // Never redacted: a trace id is a random 32-hex identifier, not user + // data, and redacting it would destroy the only thing it is for. + // eslint-disable-next-line unicorn/no-null -- dispatch with no ambient trace, or a legacy row appended before this column existed. + entry.traceId ?? null, entry.durationMs, encodeTables(entry.tablesRead), encodeTables(entry.tablesWritten), @@ -395,6 +435,11 @@ const emitRequestLogEvent = (entry: AppendRequestLogEntry, options: RequestLogWr source: REQUEST_LOG_EVENT_SOURCE, tablesRead: entry.tablesRead ?? [], tablesWritten: entry.tablesWritten ?? [], + // The join key on the far side: a SIEM receiving this event and an OTLP + // collector receiving the same dispatch's spans can only be correlated + // through the trace id, so emitting it here is most of the point of + // recording it at all. + traceId: entry.traceId, ts: entry.ts, type: "request", userId: entry.userId, @@ -588,6 +633,7 @@ interface RequestLogRow { subscriptions_rerun: number; tables_read: string; tables_written: string; + trace_id: null | string; ts: number; user_id: null | string; } @@ -640,7 +686,7 @@ const readRequestLog = (sql: SqlExec, options: ReadRequestLogOptions = {}): Requ const rows = runSql( sql, - `SELECT seq, ts, function_path, shard_key, user_id, identity, args, outcome, error_message, duration_ms, tables_read, tables_written, cache_hit, subscriptions_rerun + `SELECT seq, ts, function_path, shard_key, user_id, identity, args, outcome, error_message, trace_id, duration_ms, tables_read, tables_written, cache_hit, subscriptions_rerun FROM "${REQUEST_LOG_TABLE}" WHERE ${conjuncts.join(" AND ")} ORDER BY seq DESC LIMIT ?`, ...parameters, ).toArray(); @@ -681,6 +727,10 @@ const readRequestLog = (sql: SqlExec, options: ReadRequestLogOptions = {}): Requ base.cacheHit = row.cache_hit === 1; } + if (row.trace_id !== null) { + base.traceId = row.trace_id; + } + return base; }); }; diff --git a/packages/studio/__tests__/features/logs/logs-panel.test.tsx b/packages/studio/__tests__/features/logs/logs-panel.test.tsx index bd739cf80b..466500790b 100644 --- a/packages/studio/__tests__/features/logs/logs-panel.test.tsx +++ b/packages/studio/__tests__/features/logs/logs-panel.test.tsx @@ -1,11 +1,12 @@ import { LunoraProvider } from "@lunora/react"; import { act, fireEvent, render, screen, waitFor } from "@testing-library/react"; -import { describe, expect, it } from "vitest"; +import { afterEach, describe, expect, it } from "vitest"; import type { LogFilterCriteria } from "../../../src/features/logs/logs-panel"; import { filterLogs, LogsPanel, summarizeLogs } from "../../../src/features/logs/logs-panel"; import type { LogEntry, RequestLogEntry } from "../../../src/lib/admin"; import { ADMIN_FUNCTIONS } from "../../../src/lib/admin"; +import { peekPendingTraceFilter } from "../../../src/lib/trace-handoff"; import type { MockClientHooks } from "../../mock-client"; import { createMockClient } from "../../mock-client"; import wrapInRouter from "../../render-with-router"; @@ -205,6 +206,54 @@ describe("logsPanel — requests view (default)", () => { }); }); +describe("logsPanel — trace drill-down", () => { + afterEach(() => { + sessionStorage.clear(); + }); + + it("hands a request row's trace to the Traces panel, scoped to the browsed shard", async () => { + expect.assertions(2); + + const traced: RequestLogEntry[] = [{ ...(REQUESTS[0] as RequestLogEntry), traceId: "trace-req" }]; + + render(renderPanel(createClient(ENTRIES, traced))); + + fireEvent.click(await screen.findByTestId("lg-req-trace-link")); + + // The hand-off, not the navigation, is the contract: Traces reads it on + // mount and pre-filters. Shard "" is the root DO the panel defaults to. + expect(peekPendingTraceFilter()?.traceId).toBe("trace-req"); + expect(peekPendingTraceFilter()?.shardKey).toBe(""); + }); + + it("shows no Trace link on a request row written before the trace_id column existed", async () => { + expect.assertions(2); + + render(renderPanel(createClient())); + + // The shared REQUESTS fixtures carry no `traceId` — the legacy-row shape. + await screen.findAllByTestId("lg-req-row"); + + expect(screen.queryByTestId("lg-req-trace-link")).toBeNull(); + expect(screen.getAllByTestId("lg-req-row")).toHaveLength(2); + }); + + it("hands an errors-view log line's trace over the same way", async () => { + expect.assertions(1); + + const traced: LogEntry[] = [{ ...(ENTRIES[0] as LogEntry), traceId: "trace-log" }]; + + render(renderPanel(createClient(traced))); + + await screen.findByTestId("lg-table"); + await switchToErrors(); + + fireEvent.click(await screen.findByTestId("lg-trace-link")); + + expect(peekPendingTraceFilter()?.traceId).toBe("trace-log"); + }); +}); + describe("logsPanel — errors view", () => { it("renders a row per captured log after switching to Errors", async () => { expect.assertions(3); diff --git a/packages/studio/src/features/logs/logs-panel.tsx b/packages/studio/src/features/logs/logs-panel.tsx index df489ae4e7..1c677c62a0 100644 --- a/packages/studio/src/features/logs/logs-panel.tsx +++ b/packages/studio/src/features/logs/logs-panel.tsx @@ -53,6 +53,46 @@ const OUTCOME_VARIANT: Record = { ok: "secondary", }; +interface TraceLinkCellProps { + /** Open the Traces panel filtered to this row's trace. */ + readonly onOpenTrace: (traceId: string) => void; + readonly testId: string; + /** Absent for a row with no ambient trace, or one predating the field. */ + readonly traceId?: string; +} + +/** + * The trailing "Trace" cell shared by both log views — the drill-down from a + * line to the waterfall it came from, instead of matching timestamps by eye. + * + * Best-effort by construction on the Requests side: that log is durable while + * the span ring is in-memory, so a row older than the current DO instance links + * to a waterfall that has been hibernated away and the Traces panel shows its + * ordinary empty state. The id stays valid in an external collector either way. + * + * Renders an empty cell rather than nothing when there is no trace, so the + * column width stays constant down the virtualized list. + */ +const TraceLinkCell = ({ onOpenTrace, testId, traceId }: TraceLinkCellProps): ReactElement => { + const t = useT(); + + const onClick = (): void => { + if (traceId !== undefined) { + onOpenTrace(traceId); + } + }; + + return ( + + {traceId === undefined ? null : ( + + )} + + ); +}; + interface LogRowProps { readonly entry: LogEntry; readonly index: number; @@ -71,18 +111,10 @@ interface LogRowProps { * fresh inline objects. */ const LogRow = ({ entry, index, measureRef, onOpenTrace, start }: LogRowProps): ReactElement => { - const t = useT(); const style = { ...ROW_BASE_STYLE, transform: `translateY(${String(start)}px)` }; // Rendered once; `""` (no fields, or an empty bag from a worker predating // field normalization) skips the chip entirely rather than showing a blank span. const fields = formatLogFields(entry.fields); - const { traceId } = entry; - - const onTraceClick = (): void => { - if (traceId !== undefined) { - onOpenTrace(traceId); - } - }; return (
)} - {/* - * The drill-down the two panels were missing: a line emitted inside a - * dispatch knows its trace, so it can hand you the waterfall it came - * from instead of leaving you to match timestamps by eye. Absent for - * lines with no ambient trace (container lifecycle, hibernation errors) - * and for any worker predating the buffered `traceId`. - */} - - {traceId === undefined ? null : ( - - )} - +
); }; @@ -132,6 +151,8 @@ interface RequestRowProps { readonly entry: RequestLogEntry; readonly index: number; readonly measureRef: (node: HTMLDivElement | null) => void; + /** Open the Traces panel filtered to this dispatch's trace. */ + readonly onOpenTrace: (traceId: string) => void; readonly start: number; } @@ -143,7 +164,7 @@ const tablesLabel = (tables: string[]): string => (tables.length === 0 ? "—" : * log adds over the in-memory error buffer: function path, shard, acting user, * outcome, duration, and the read/written table sets. */ -const RequestRow = ({ entry, index, measureRef, start }: RequestRowProps): ReactElement => { +const RequestRow = ({ entry, index, measureRef, onOpenTrace, start }: RequestRowProps): ReactElement => { const style = { ...ROW_BASE_STYLE, transform: `translateY(${String(start)}px)` }; return ( @@ -178,6 +199,7 @@ const RequestRow = ({ entry, index, measureRef, start }: RequestRowProps): React ? entry.errorMessage : `r:${tablesLabel(entry.tablesRead)} · w:${tablesLabel(entry.tablesWritten)}`} + ); }; @@ -618,6 +640,7 @@ export const LogsPanel = ({ initialShardKey }: LogsPanelProps): ReactElement => index={virtualRow.index} key={virtualRow.key} measureRef={virtualizer.measureElement} + onOpenTrace={openTrace} start={virtualRow.start} /> ) : ( diff --git a/packages/studio/src/lib/admin.ts b/packages/studio/src/lib/admin.ts index b1d3d43875..b057d6e30a 100644 --- a/packages/studio/src/lib/admin.ts +++ b/packages/studio/src/lib/admin.ts @@ -950,6 +950,17 @@ export interface RequestLogEntry { tablesRead: string[]; /** Tables the handler wrote; empty for a read-only dispatch. */ tablesWritten: string[]; + + /** + * W3C trace id (32-hex) of the dispatch; absent for a row written before the + * column existed. + * + * The request log is durable while the span ring it links to is in-memory, so + * a row older than the current DO instance carries an id whose waterfall is + * gone. The Trace link is therefore best-effort against local traces — the id + * still resolves in whatever collector `otlpSink` ships to. + */ + traceId?: string; /** Epoch-ms the dispatch completed. */ ts: number; /** Acting userId forwarded by the runtime; absent when anonymous. */ From e18d75a698a707ef0d98106ad33f630c82a9fe30 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 8 Aug 2026 23:26:42 +0200 Subject: [PATCH 4/9] style(shard-engine): drop redundant parens prettier rejects Formatting only, no behaviour change. The bigint-queryability test landed on alpha with a paren group prettier removes, which fails the repo-wide `Lint (prettier)` job on every branch that merges alpha afterwards. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- packages/shard-engine/__tests__/ctx-db.bigint-bytes.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/shard-engine/__tests__/ctx-db.bigint-bytes.test.ts b/packages/shard-engine/__tests__/ctx-db.bigint-bytes.test.ts index 9a03566f5c..c281499bce 100644 --- a/packages/shard-engine/__tests__/ctx-db.bigint-bytes.test.ts +++ b/packages/shard-engine/__tests__/ctx-db.bigint-bytes.test.ts @@ -444,7 +444,7 @@ describe("ctx-db bigint/bytes doc-blob round-trip", () => { await seed(writer); const grouped = await writer.groupBy("paymentSessions", { agg: { op: "count" }, by: ["currency"] }); - const usd = grouped.find((group) => (group["key"])["currency"] === "usd"); + const usd = grouped.find((group) => group["key"]["currency"] === "usd"); expect(usd?.["value"]).toBe(2); From 63646b9d4ce37b429af8706a9fff43470b3f6067 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sat, 8 Aug 2026 23:57:21 +0200 Subject: [PATCH 5/9] fix(do): stamp the request-log row with its own dispatch's trace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `recordRequestLog` runs after the handler's awaits, and it read the shared `currentRequestTrace` field. A Durable Object interleaves dispatches at await points, so a concurrent request re-sets that field — or clears it in its `finally` — before the first one records its row. Two concurrent `/rpc` calls could file request A's durable row, and the Logpush event carrying it, under request B's trace. Silently: the Requests view's Trace link would open the wrong waterfall and nothing would report a mismatch. The anchor is now threaded by value, matching the `dispatchTrace` capture the same function already uses for the root span — whose comment describes this exact hazard three lines above the code that ignored it. Regression test drives the real race: park a dispatch inside its handler, run a sibling with a different trace to completion, then release. It fails against the previous code with `undefined`, the symptom of the sibling's `finally`. Review fixes, same pass: - gate the Traces panel's correlated-log read on an expanded row, so visiting the page no longer opens a second live subscription streaming the whole log ring for a section that starts collapsed - restore the waterfall row's accessible name: as a button it concatenated every cell, including the bar's own label, into a run-on string - put the ruler and the span rows on one shared grid, so gridlines cannot silently drift from the bars they annotate - key correlated log rows by position; identical messages in the same millisecond are ordinary and collided on a content-derived key - shift the terminal ruler label back over its gridline instead of past the track - loop the guarded ALTERs, making per-column isolation structural rather than a comment defending two copy-pasted blocks - share one LogLine between both log views (they had already drifted on the level column's width and on timestamp formatting) and one useOpenTrace hook between the Logs and Metrics drill-downs - move the waterfall into its own module; let a span row own its expansion state instead of prop-drilling a Set from the panel - replace the hand-rolled log bucketing with Map.groupBy, dropping a useMemo React Compiler flagged as redundant - split the ruler test, which asserted absence against a prior render's DOM, and make the redaction test prove redaction actually ran on the row - collapse the retention-asymmetry note from five copies to one Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- .../do/__tests__/shard-do.sampling.test.ts | 50 +++ packages/do/src/shard-do.ts | 29 +- .../__tests__/request-log.test.ts | 15 +- packages/observability/src/log-buffer.ts | 8 +- packages/observability/src/request-log.ts | 50 ++- .../features/logs/logs-panel.test.tsx | 4 +- .../features/traces/traces-panel.test.tsx | 22 +- .../studio/src/features/logs/log-line.tsx | 53 +++ .../studio/src/features/logs/logs-panel.tsx | 66 +--- .../src/features/reports/metrics-panel.tsx | 15 +- .../src/features/traces/trace-waterfall.tsx | 187 +++++++++++ .../src/features/traces/traces-panel.tsx | 309 ++++-------------- packages/studio/src/hooks/use-open-trace.ts | 26 ++ packages/studio/src/lib/admin.ts | 17 +- packages/studio/src/locales/en.ts | 4 +- 15 files changed, 467 insertions(+), 388 deletions(-) create mode 100644 packages/studio/src/features/logs/log-line.tsx create mode 100644 packages/studio/src/features/traces/trace-waterfall.tsx create mode 100644 packages/studio/src/hooks/use-open-trace.ts diff --git a/packages/do/__tests__/shard-do.sampling.test.ts b/packages/do/__tests__/shard-do.sampling.test.ts index 9030e9e3f7..f59eba7518 100644 --- a/packages/do/__tests__/shard-do.sampling.test.ts +++ b/packages/do/__tests__/shard-do.sampling.test.ts @@ -1,4 +1,5 @@ import type { ContextTracer } from "@lunora/observability"; +import { readRequestLog } from "@lunora/observability"; import { describe, expect, it } from "vitest"; import type { SpanEvent } from "../../../shared/span-event"; @@ -229,6 +230,55 @@ describe("shardDO trace sampling", () => { } }); + it("stamps the durable request-log row with its OWN trace when a sibling dispatch interleaves", async () => { + expect.assertions(2); + + const database = createSqliteExec(); + + try { + const shard = new SamplingShard(makeState(database), {}); + + let markStarted!: () => void; + const slowStarted = new Promise((resolve) => { + markStarted = resolve; + }); + let releaseSlow!: () => void; + const slowGate = new Promise((resolve) => { + releaseSlow = resolve; + }); + + shard.plan = async (_trace, functionPath) => { + if (functionPath === "slow:ok") { + markStarted(); + // Park inside the handler, so the sibling below runs its whole + // dispatch — including the `finally` that CLEARS the shared + // `currentRequestTrace` — before this one records its row. + await slowGate; + } + }; + + const slow = shard.fetch(request("slow:ok", { sampled: true, traceId: TRACE_ID })); + + await slowStarted; + await shard.fetch(request("fast:ok", { sampled: true, traceId: TRACE_ID_B })); + + releaseSlow(); + await slow; + + const rows = readRequestLog(database.sql); + const byPath = new Map(rows.map((row) => [row.functionPath, row.traceId])); + + // The regression: `recordRequestLog` runs after the handler's awaits, so + // reading the shared anchor there stamped the sibling's trace — or + // `undefined`, once the sibling's `finally` had cleared it. The anchor is + // threaded by value precisely so each row carries its own dispatch's id. + expect(byPath.get("slow:ok")).toBe(TRACE_ID); + expect(byPath.get("fast:ok")).toBe(TRACE_ID_B); + } finally { + database.close(); + } + }); + it("flushes a sampled-out trace's held error span even after the ring evicted it (eviction race closed)", async () => { expect.assertions(1); diff --git a/packages/do/src/shard-do.ts b/packages/do/src/shard-do.ts index 3e65205365..8f6b026566 100644 --- a/packages/do/src/shard-do.ts +++ b/packages/do/src/shard-do.ts @@ -4464,7 +4464,7 @@ abstract class ShardDO { // so the request log would record an empty write set. const tablesWritten = [...(this.pendingChangedTables ?? [])]; - this.recordRequestLog(payload.functionPath, payload.args ?? {}, durationMs, "ok", tablesWritten); + this.recordRequestLog(payload.functionPath, payload.args ?? {}, durationMs, "ok", tablesWritten, dispatchTrace); // Inspect the post-write size before responding. SQLite-in-DO // exposes `databaseSize` as a real getter; reading it is a @@ -4523,15 +4523,22 @@ abstract class ShardDO { // Flush statement samples even on error paths — partial sampling // is better than losing the timing signal entirely. this.flushStmtSamples(); - this.recordRequestLog(payload.functionPath, payload.args ?? {}, durationMs, "error", [...(this.pendingChangedTables ?? [])], message); + this.recordRequestLog( + payload.functionPath, + payload.args ?? {}, + durationMs, + "error", + [...(this.pendingChangedTables ?? [])], + dispatchTrace, + message, + ); this.logs.push({ functionPath: payload.functionPath, level: "error", message, timestamp: Date.now(), - // The throw's own trace, so the Traces panel can show this line - // against the waterfall that failed — the whole point of opening - // a trace after seeing a red log row. + // The local, not the shared field: this runs after the handler's + // awaits, where an interleaved dispatch may have re-set it. traceId: dispatchTrace.traceId, }); @@ -6415,6 +6422,7 @@ abstract class ShardDO { durationMs: number, outcome: "error" | "ok", tablesWritten: string[], + trace: TraceAnchor, errorMessage?: string, ): void { const config = this.requestLogConfig(); @@ -6443,10 +6451,13 @@ abstract class ShardDO { shardKey: this.runner.shardKey, tablesRead: this.currentRequestReadTables === undefined ? [] : [...this.currentRequestReadTables], tablesWritten, - // Read from the shared per-request anchor rather than re-resolved, so - // the row lands in the SAME trace as this dispatch's `ctx.trace` spans - // and its `ctx.log` lines. `undefined` outside a dispatch-scoped call. - traceId: this.currentRequestTrace?.traceId, + // Passed BY VALUE, never read off `currentRequestTrace` here: this + // method runs after the handler's awaits, by which point an + // interleaved dispatch may have re-set (or cleared) that shared + // field — which would file this row, and the Logpush event carrying + // it, under another request's trace. Same hazard, and same fix, as + // the dispatch root span's `dispatchTrace` capture. + traceId: trace.traceId, ts: Date.now(), userId: this.getCurrentUserId(), }; diff --git a/packages/observability/__tests__/request-log.test.ts b/packages/observability/__tests__/request-log.test.ts index 69e43e03d6..82a971c80a 100644 --- a/packages/observability/__tests__/request-log.test.ts +++ b/packages/observability/__tests__/request-log.test.ts @@ -110,17 +110,22 @@ describe("request-log module", () => { } }); - it("never redacts the trace id — it is an opaque identifier, and masking it would destroy its only purpose", () => { - expect.assertions(1); + it("keeps the trace id intact on a row whose args were redacted", () => { + expect.assertions(2); const database = createSqliteExec(); try { - // A 32-hex string is exactly the shape a redaction rule might mistake - // for a token, and the correlation key is worthless once masked. appendRequestLogEntry(database.sql, entry({ redactedArgs: { password: "hunter2" }, traceId: TRACE_ID })); - expect(readRequestLog(database.sql)[0]!.traceId).toBe(TRACE_ID); + const [row] = readRequestLog(database.sql); + + // The masked arg proves redaction ran on THIS row, so the intact id + // below is a real exemption and not just an unredacted code path. The + // guard is against widening redaction to the whole entry: a masked + // correlation key joins to nothing, which is its entire purpose. + expect((row!.redactedArgs as Record).password).not.toBe("hunter2"); + expect(row!.traceId).toBe(TRACE_ID); } finally { database.close(); } diff --git a/packages/observability/src/log-buffer.ts b/packages/observability/src/log-buffer.ts index edd99a3177..a37a9f53ef 100644 --- a/packages/observability/src/log-buffer.ts +++ b/packages/observability/src/log-buffer.ts @@ -27,13 +27,7 @@ interface LogEntry { message: string; timestamp: number; - /** - * Trace the line was emitted under, when there was an ambient one. The - * `LogEvent` handed to a sink has always carried this; the buffer dropped it, - * which is why the Studio could show a trace's waterfall and the same - * request's log lines without being able to connect the two. Absent for lines - * emitted outside a dispatch (container lifecycle, hibernation-path errors). - */ + /** Trace the line was emitted under; absent outside a dispatch (container lifecycle, hibernation-path errors). What the Studio joins a log line to its waterfall on. */ traceId?: string; } diff --git a/packages/observability/src/request-log.ts b/packages/observability/src/request-log.ts index c0c68f4292..958f67445b 100644 --- a/packages/observability/src/request-log.ts +++ b/packages/observability/src/request-log.ts @@ -55,6 +55,14 @@ const REQUEST_LOG_RETENTION = 1000; /** Stable tag on every console-emitted event so a Logpush/SIEM consumer can filter lunora request events out of the raw Workers-trace firehose. */ const REQUEST_LOG_EVENT_SOURCE = "lunora"; +/** + * Columns added after the table's first release, as ` ` — each one + * `ALTER`ed in on its own so a shard created before it gains it on the next + * {@link ensureRequestLogTable}. A new column is one entry here plus the matching + * line in the `CREATE`; nothing else needs a migration. + */ +const ADDED_COLUMNS = ["error_fingerprint TEXT", "trace_id TEXT"]; + /** Outcome of one dispatch — `ok` for a returned result, `error` for a thrown handler. */ type RequestOutcome = "error" | "ok"; @@ -85,16 +93,7 @@ interface RequestLogEntry { /** Tables the handler wrote (from the change tracker); empty for a read-only dispatch. */ tablesWritten: string[]; - /** - * W3C trace id (32-hex) of the dispatch, or `undefined` for a row appended - * before this column existed. - * - * The correlation key, NOT a guarantee the trace is still readable: this - * table is durable and bounded by row count, while the `ctx.trace` span ring - * it would join to is in-memory and dies on hibernation. So the id reliably - * resolves in an external collector (whatever `otlpSink` ships to), and only - * opportunistically against the local waterfall — see the module docstring. - */ + /** W3C trace id (32-hex) of the dispatch; `undefined` on a row appended before this column existed. See the module docstring on the retention asymmetry. */ traceId?: string; /** Wall-clock millis when the dispatch completed. */ ts: number; @@ -272,14 +271,13 @@ const redactArgs = (value: unknown, captureRaw = false): unknown => { * trace id, the correlation key to the span ring and to whatever collector * `otlpSink` ships to. * - * Both are added via a guarded `ALTER TABLE` rather than baked into the - * `CREATE`, mirroring `function-metrics.ts`'s `ensureFunctionMetricsTables`, so - * a shard whose `__lunora_reqlog__` predates a column gains it on the next call - * without a migration. SQLite has no `ADD COLUMN IF NOT EXISTS`, so the - * duplicate-column error from a re-run (or the freshly-created schema above) is - * swallowed. Each `ALTER` needs its OWN try — one shared block would let the - * first column's duplicate error skip the second column's add, leaving a shard - * that has `error_fingerprint` but never gains `trace_id`. + * Both are also added via a guarded `ALTER TABLE`, mirroring + * `function-metrics.ts`'s `ensureFunctionMetricsTables`, so a shard whose + * `__lunora_reqlog__` predates a column gains it on the next call without a + * migration. SQLite has no `ADD COLUMN IF NOT EXISTS`, so the duplicate-column + * error from a re-run (or from the freshly-created schema above) is swallowed + * per column — the loop is what keeps one column's duplicate from skipping the + * next column's add. */ const ensureRequestLogTable = (sql: SqlExec): void => { runSql( @@ -304,16 +302,12 @@ const ensureRequestLogTable = (sql: SqlExec): void => { )`, ); - try { - runSql(sql, `ALTER TABLE "${REQUEST_LOG_TABLE}" ADD COLUMN error_fingerprint TEXT`); - } catch { - // Column already exists — no-op. - } - - try { - runSql(sql, `ALTER TABLE "${REQUEST_LOG_TABLE}" ADD COLUMN trace_id TEXT`); - } catch { - // Column already exists — no-op. + for (const column of ADDED_COLUMNS) { + try { + runSql(sql, `ALTER TABLE "${REQUEST_LOG_TABLE}" ADD COLUMN ${column}`); + } catch { + // Column already exists — no-op. + } } }; diff --git a/packages/studio/__tests__/features/logs/logs-panel.test.tsx b/packages/studio/__tests__/features/logs/logs-panel.test.tsx index 466500790b..64bc245049 100644 --- a/packages/studio/__tests__/features/logs/logs-panel.test.tsx +++ b/packages/studio/__tests__/features/logs/logs-panel.test.tsx @@ -218,7 +218,7 @@ describe("logsPanel — trace drill-down", () => { render(renderPanel(createClient(ENTRIES, traced))); - fireEvent.click(await screen.findByTestId("lg-req-trace-link")); + fireEvent.click(await screen.findByTestId("lg-trace-link")); // The hand-off, not the navigation, is the contract: Traces reads it on // mount and pre-filters. Shard "" is the root DO the panel defaults to. @@ -234,7 +234,7 @@ describe("logsPanel — trace drill-down", () => { // The shared REQUESTS fixtures carry no `traceId` — the legacy-row shape. await screen.findAllByTestId("lg-req-row"); - expect(screen.queryByTestId("lg-req-trace-link")).toBeNull(); + expect(screen.queryByTestId("lg-trace-link")).toBeNull(); expect(screen.getAllByTestId("lg-req-row")).toHaveLength(2); }); diff --git a/packages/studio/__tests__/features/traces/traces-panel.test.tsx b/packages/studio/__tests__/features/traces/traces-panel.test.tsx index 1351028ef5..9c87998ad9 100644 --- a/packages/studio/__tests__/features/traces/traces-panel.test.tsx +++ b/packages/studio/__tests__/features/traces/traces-panel.test.tsx @@ -276,16 +276,18 @@ describe("tracesPanel", () => { it("shows a span's kind and recorded events in its detail", async () => { expect.assertions(2); + // Cast the indexed reads, not the whole literal: casting the object would + // switch off excess-property and missing-field checking on the fixture. const traced: TraceSummary = { - ...TRACES[1], + ...(TRACES[1] as TraceSummary), spans: [ { - ...LIST_SPANS[0], + ...(LIST_SPANS[0] as TraceSpan), events: [{ attributes: { "exception.type": "TimeoutError" }, name: "exception", ts: 1_700_000_001_004 }], kind: "client", }, ], - } as TraceSummary; + }; render(renderPanel(createClient([traced]))); @@ -343,8 +345,8 @@ describe("tracesPanel", () => { expect(screen.getByTestId("tr-row-trace-error")).toBeTruthy(); }); - it("draws an elapsed-time ruler over the waterfall, and none for a zero-duration trace", async () => { - expect.assertions(3); + it("draws an elapsed-time ruler across the expanded waterfall", async () => { + expect.assertions(2); render(renderPanel(createClient())); @@ -354,13 +356,19 @@ describe("tracesPanel", () => { expect(ruler.textContent).toContain("25ms"); expect(ruler.textContent).toContain("100ms"); + }); + it("draws no ruler for a zero-duration trace, whose spans are all laid out full-width", async () => { + expect.assertions(1); + + // Its own render: asserting absence against a DOM that still holds a + // previous render's ruler would pass for the wrong reason. render(renderPanel(createClient([ZERO_TRACE]))); + fireEvent.click(await screen.findByTestId("tr-toggle-trace-zero")); await screen.findAllByTestId("tr-span-bar"); - // One ruler still on screen from the first render; the zero trace adds none. - expect(screen.getAllByTestId("tr-ruler")).toHaveLength(1); + expect(screen.queryByTestId("tr-ruler")).toBeNull(); }); it("renders visible bars for a zero-duration trace rather than NaN", async () => { diff --git a/packages/studio/src/features/logs/log-line.tsx b/packages/studio/src/features/logs/log-line.tsx new file mode 100644 index 0000000000..58469874e3 --- /dev/null +++ b/packages/studio/src/features/logs/log-line.tsx @@ -0,0 +1,53 @@ +import type { ReactElement } from "react"; + +// Bundler-inlined, zero-dep `key=value` field renderer shared with the runtime +// sinks and the dev-terminal formatter (see CLAUDE.md `shared/` rules). +import { formatLogFields } from "../../../../../shared/log-fields"; +import { Badge } from "../../components/ui/badge"; +import type { LogEntry } from "../../lib/admin"; +import { formatTimestamp } from "../../lib/internal"; +import { LEVEL_VARIANT } from "./log-level-variant"; + +interface LogLineProps { + readonly entry: LogEntry; +} + +/** + * The cells of one `ctx.log` line — timestamp, severity, function path, and the + * message with its structured fields. + * + * A fragment of `gridcell`s rather than a row element, so each caller supplies + * its own row container: the Logs panel needs an absolutely-positioned, + * measured one for react-virtual, and the Traces panel's per-trace log section + * needs a plain one. Both must render the SAME line — they did not when this was + * duplicated, having already drifted on the level column's width and on whether + * the timestamp went through {@link formatTimestamp}. + */ +const LogLine = ({ entry }: LogLineProps): ReactElement => { + // Rendered once; `""` (no fields, or an empty bag from a worker predating + // field normalization) skips the chip entirely rather than showing a blank span. + const fields = formatLogFields(entry.fields); + + return ( + <> + + {formatTimestamp(entry.timestamp)} + + + {entry.level} + + + {entry.functionPath ?? "—"} + + + {entry.message} + {fields === "" ? null : ( + + {fields} + + )} + + + ); +}; +export default LogLine; diff --git a/packages/studio/src/features/logs/logs-panel.tsx b/packages/studio/src/features/logs/logs-panel.tsx index 1c677c62a0..1488f24f7b 100644 --- a/packages/studio/src/features/logs/logs-panel.tsx +++ b/packages/studio/src/features/logs/logs-panel.tsx @@ -1,4 +1,3 @@ -import { useNavigate } from "@tanstack/react-router"; import { useVirtualizer } from "@tanstack/react-virtual"; import type { ChangeEvent, CSSProperties, ReactElement } from "react"; import { useEffect, useMemo, useRef, useState } from "react"; @@ -12,17 +11,16 @@ import ErrorAlert from "../../components/error-alert"; import { Badge } from "../../components/ui/badge"; import { EmptyState } from "../../components/ui/empty-state"; import { useAdminQuery } from "../../hooks/use-admin-query"; +import useOpenTrace from "../../hooks/use-open-trace"; import { useShardKey } from "../../hooks/use-shard-key"; import { useT } from "../../i18n/i18n-context"; import type { LogEntry, LogLevel, RequestLogEntry, RequestLogQuery, RequestOutcome } from "../../lib/admin"; import { ADMIN_FUNCTIONS } from "../../lib/admin"; -import { fireAndForget } from "../../lib/internal"; import { recordShard } from "../../lib/shard-history"; -import { writePendingTraceFilter } from "../../lib/trace-handoff"; import flooredRectObserver from "../../lib/virtual-rect"; import { ArchiveFeed } from "./archive-feed"; import type { BadgeVariant } from "./log-level-variant"; -import { LEVEL_VARIANT } from "./log-level-variant"; +import LogLine from "./log-line"; import LogsErrorFilters from "./logs-error-filters"; import LogsRequestFilters from "./logs-request-filters"; import type { LogSummary, SummaryBucket } from "./logs-summary"; @@ -56,7 +54,6 @@ const OUTCOME_VARIANT: Record = { interface TraceLinkCellProps { /** Open the Traces panel filtered to this row's trace. */ readonly onOpenTrace: (traceId: string) => void; - readonly testId: string; /** Absent for a row with no ambient trace, or one predating the field. */ readonly traceId?: string; } @@ -65,27 +62,24 @@ interface TraceLinkCellProps { * The trailing "Trace" cell shared by both log views — the drill-down from a * line to the waterfall it came from, instead of matching timestamps by eye. * - * Best-effort by construction on the Requests side: that log is durable while - * the span ring is in-memory, so a row older than the current DO instance links - * to a waterfall that has been hibernated away and the Traces panel shows its - * ordinary empty state. The id stays valid in an external collector either way. - * * Renders an empty cell rather than nothing when there is no trace, so the - * column width stays constant down the virtualized list. + * column width stays constant down the virtualized list. The two views are + * mutually exclusive, so both use one test id. */ -const TraceLinkCell = ({ onOpenTrace, testId, traceId }: TraceLinkCellProps): ReactElement => { +const TraceLinkCell = ({ onOpenTrace, traceId }: TraceLinkCellProps): ReactElement => { const t = useT(); - const onClick = (): void => { - if (traceId !== undefined) { - onOpenTrace(traceId); - } - }; - return ( {traceId === undefined ? null : ( - )} @@ -112,9 +106,6 @@ interface LogRowProps { */ const LogRow = ({ entry, index, measureRef, onOpenTrace, start }: LogRowProps): ReactElement => { const style = { ...ROW_BASE_STYLE, transform: `translateY(${String(start)}px)` }; - // Rendered once; `""` (no fields, or an empty bag from a worker predating - // field normalization) skips the chip entirely rather than showing a blank span. - const fields = formatLogFields(entry.fields); return (
- - {new Date(entry.timestamp).toLocaleString()} - - - {entry.level} - - - {entry.functionPath ?? "—"} - - - {entry.message} - {fields === "" ? null : ( - - {fields} - - )} - - + +
); }; @@ -199,7 +174,7 @@ const RequestRow = ({ entry, index, measureRef, onOpenTrace, start }: RequestRow ? entry.errorMessage : `r:${tablesLabel(entry.tablesRead)} · w:${tablesLabel(entry.tablesWritten)}`}
- + ); }; @@ -368,7 +343,6 @@ export const LogsPanel = ({ initialShardKey }: LogsPanelProps): ReactElement => const t = useT(); const [view, setView] = useState("requests"); - const navigate = useNavigate(); const { queryShardKey, setShardKey, shardKey } = useShardKey(initialShardKey); const [search, setSearch] = useState(""); // Errors-view client-side filters: a level allow-set (empty = all levels), a @@ -414,13 +388,7 @@ export const LogsPanel = ({ initialShardKey }: LogsPanelProps): ReactElement => const activeQuery = view === "requests" ? requestsQuery : errorsQuery; const { error, errorSource, isLoading: activeLoading, liveError } = activeQuery; - // Hand a log line's trace to the Traces panel and navigate there — the same - // one-shot handoff the Metrics panel's exemplar link uses, carrying the shard - // so Traces reads the ring the line came from rather than the root's. - const openTrace = (traceId: string): void => { - writePendingTraceFilter({ shardKey: queryShardKey, traceId }); - fireAndForget(navigate({ to: "/traces" })); - }; + const openTrace = useOpenTrace(queryShardKey); // Coerce each view's resolved payload into its entries array (a one-shot read // or live push without an `entries` array yields `[]`); an unloaded gated diff --git a/packages/studio/src/features/reports/metrics-panel.tsx b/packages/studio/src/features/reports/metrics-panel.tsx index e4cb39aae3..c8dcd70eb8 100644 --- a/packages/studio/src/features/reports/metrics-panel.tsx +++ b/packages/studio/src/features/reports/metrics-panel.tsx @@ -1,5 +1,4 @@ import { useLunora } from "@lunora/react"; -import { useNavigate } from "@tanstack/react-router"; import type { ReactElement } from "react"; import { useEffect, useMemo, useRef, useState } from "react"; @@ -7,6 +6,7 @@ import { LiveError } from "../../components/live-status"; import { ShardInput } from "../../components/shard-input"; import { Button } from "../../components/ui/button"; import { useAdminQuery } from "../../hooks/use-admin-query"; +import useOpenTrace from "../../hooks/use-open-trace"; import { useShardKey } from "../../hooks/use-shard-key"; import { useT } from "../../i18n/i18n-context"; import type { MetricsSnapshot, ShardMetrics } from "../../lib/admin"; @@ -14,7 +14,6 @@ import { ADMIN_FUNCTIONS } from "../../lib/admin"; import { CLOUDFLARE_DURABLE_OBJECTS_URL } from "../../lib/cf-links"; import { adminRef, callOptions, errorMessage, fireAndForget } from "../../lib/internal"; import { loadRecentShards, recordShard } from "../../lib/shard-history"; -import { writePendingTraceFilter } from "../../lib/trace-handoff"; import { InstrumentsTable } from "./instruments-table"; import type { ShardMetricsResult } from "./metrics-aggregate"; import { aggregateMetrics, computeLatencyPercentiles, enrichQueryStats, shardsToAggregate } from "./metrics-aggregate"; @@ -59,7 +58,6 @@ const resolveTab = (hasQueryStats: boolean, activeTab: "overview" | "query-insig export const MetricsPanel = ({ initialShardKey }: MetricsPanelProps): ReactElement => { const client = useLunora(); const t = useT(); - const navigate = useNavigate(); const { queryShardKey, setShardKey, shardKey } = useShardKey(initialShardKey); /** Active panel tab: "overview" (default) or "query-insights" (shown when queryStats present). */ @@ -83,14 +81,9 @@ export const MetricsPanel = ({ initialShardKey }: MetricsPanelProps): ReactEleme }; }, []); - // Exemplar drill-down: stash the trace id — and the shard the series was queried - // on, so the Traces panel searches the right ring rather than the root — for the - // Traces panel to pick up and pre-filter on mount, then navigate there. A - // one-shot handoff keeps the two panels decoupled from the router's search schema. - const openTrace = (traceId: string): void => { - writePendingTraceFilter({ shardKey: queryShardKey, traceId }); - fireAndForget(navigate({ to: "/traces" })); - }; + // Exemplar drill-down: open the trace a metric point sampled, on the shard the + // series was queried from. + const openTrace = useOpenTrace(queryShardKey); // One-shot read + always-on live subscription for the committed shard. Each // server push folds in like a refresh; `liveError` holds a rejection message diff --git a/packages/studio/src/features/traces/trace-waterfall.tsx b/packages/studio/src/features/traces/trace-waterfall.tsx new file mode 100644 index 0000000000..fa160e22f2 --- /dev/null +++ b/packages/studio/src/features/traces/trace-waterfall.tsx @@ -0,0 +1,187 @@ +import type { CSSProperties, ReactElement } from "react"; +import { useState } from "react"; + +// Bundler-inlined, zero-dep `key=value` field renderer shared with the runtime +// sinks and the dev-terminal formatter (see CLAUDE.md `shared/` rules). +import { formatLogFields } from "../../../../../shared/log-fields"; +import { useT } from "../../i18n/i18n-context"; +import type { TraceSpan } from "../../lib/admin"; +import { cn } from "../../lib/utils"; +import SpanDetail from "./span-detail"; +import { formatSpanDuration, spanBar, traceTicks } from "./trace-geometry"; + +/** Pixels of indent per nesting level of a span row. */ +const INDENT_PER_DEPTH = 14; + +/** + * The waterfall's column track, shared by the ruler and every span row. + * + * One definition rather than matching `w-*` classes in two components: the ruler + * annotates the bar column, so if the two drift the gridlines label the wrong + * position — a silent, purely visual failure no test would catch. Columns are + * name / bar / duration / error / attributes. + */ +const WATERFALL_GRID = "grid grid-cols-[14rem_1fr_4rem_16rem_16rem] items-center gap-2 px-3"; + +interface TimeRulerProps { + /** Total duration the ruler annotates, in ms. */ + readonly traceDurationMs: number; +} + +/** + * Elapsed-time gridlines across the waterfall's bar column. Renders nothing for + * a zero-duration trace, where {@link spanBar} lays every span out full-width + * and there is no timeline to annotate. + */ +const TimeRuler = ({ traceDurationMs }: TimeRulerProps): ReactElement | null => { + const ticks = traceTicks(traceDurationMs); + + if (ticks.length === 0) { + return null; + } + + return ( +
+ + + {ticks.map((tick) => ( + + {tick.label} + + ))} + +
+ ); +}; + +interface SpanRowProps { + readonly span: TraceSpan; + /** The enclosing trace's total duration, the denominator for the bar geometry. */ + readonly traceDurationMs: number; +} + +/** + * One waterfall row: the span's name indented by its server-computed `depth`, a + * bar positioned by `offsetMs` and sized by `durationMs`, its duration, its + * structured attributes, and — when the body threw — an error chip plus message. + * + * Clicking the row opens {@link SpanDetail} beneath it. The row's attribute and + * error cells are hard-truncated to keep the waterfall scannable, so the detail + * block is the only place the full values are legible. + */ +const SpanRow = ({ span, traceDurationMs }: SpanRowProps): ReactElement => { + const t = useT(); + const [expanded, setExpanded] = useState(false); + const { leftPercent, widthPercent } = spanBar(span, traceDurationMs); + + // Rendered once; `""` (no attributes) skips the chip entirely rather than + // showing a blank span — the same convention as the Logs panel's fields. + const attributes = formatLogFields(span.attributes); + + const nameStyle: CSSProperties = { paddingLeft: span.depth * INDENT_PER_DEPTH }; + const barStyle: CSSProperties = { left: `${String(leftPercent)}%`, width: `${String(widthPercent)}%` }; + + const onClick = (): void => { + setExpanded((open) => !open); + }; + + return ( +
  • + {/* + * One explicit label rather than a name computed from the row's five + * cells: as a button, every child's text (and the bar's own label) + * would concatenate into a run-on string re-read on each arrow-key + * move. The cells stay visible; only the announcement is curated. + */} + + + {expanded && ( +
    + +
    + )} +
  • + ); +}; + +interface TraceWaterfallProps { + /** Total duration of the trace, the denominator for every bar. */ + readonly durationMs: number; + /** Spans pre-ordered by `(offsetMs, depth)` — a valid pre-order of the span tree. */ + readonly spans: ReadonlyArray; +} + +/** A trace's time ruler plus one expandable row per span. */ +const TraceWaterfall = ({ durationMs, spans }: TraceWaterfallProps): ReactElement => { + const t = useT(); + + return ( + <> + +
      + {spans.map((span) => ( + + ))} +
    + + ); +}; +export default TraceWaterfall; diff --git a/packages/studio/src/features/traces/traces-panel.tsx b/packages/studio/src/features/traces/traces-panel.tsx index 6d93f8eb6c..147b80dceb 100644 --- a/packages/studio/src/features/traces/traces-panel.tsx +++ b/packages/studio/src/features/traces/traces-panel.tsx @@ -1,9 +1,6 @@ -import type { ChangeEvent, CSSProperties, ReactElement } from "react"; -import { useEffect, useMemo, useState } from "react"; +import type { ChangeEvent, ReactElement } from "react"; +import { useEffect, useState } from "react"; -// Bundler-inlined, zero-dep `key=value` field renderer shared with the runtime -// sinks and the dev-terminal formatter (see CLAUDE.md `shared/` rules). -import { formatLogFields } from "../../../../../shared/log-fields"; import ErrorAlert from "../../components/error-alert"; import { LiveError } from "../../components/live-status"; import { ShardInput } from "../../components/shard-input"; @@ -14,19 +11,15 @@ import { Input } from "../../components/ui/input"; import { useAdminQuery } from "../../hooks/use-admin-query"; import { useShardKey } from "../../hooks/use-shard-key"; import { useT } from "../../i18n/i18n-context"; -import type { LogEntry, LogsResult, TraceSpan, TracesResult, TraceSummary } from "../../lib/admin"; +import type { LogEntry, LogsResult, TracesResult, TraceSummary } from "../../lib/admin"; import { ADMIN_FUNCTIONS } from "../../lib/admin"; import { formatTimestamp } from "../../lib/internal"; import { recordShard } from "../../lib/shard-history"; import type { PendingTraceFilter } from "../../lib/trace-handoff"; import { clearPendingTraceFilter, peekPendingTraceFilter } from "../../lib/trace-handoff"; -import { cn } from "../../lib/utils"; -import { LEVEL_VARIANT } from "../logs/log-level-variant"; -import SpanDetail from "./span-detail"; -import { filterTraces, formatSpanDuration, spanBar, traceTicks } from "./trace-geometry"; - -/** Pixels of indent per nesting level of a span row. */ -const INDENT_PER_DEPTH = 14; +import LogLine from "../logs/log-line"; +import { filterTraces, formatSpanDuration } from "./trace-geometry"; +import TraceWaterfall from "./trace-waterfall"; /** * Coerce a (possibly partial or malformed) `getTraces` result into its `traces` @@ -35,32 +28,15 @@ const INDENT_PER_DEPTH = 14; */ const tracesOf = (result: TracesResult | undefined): TraceSummary[] => (Array.isArray(result?.traces) ? result.traces : []); -/** Add or remove one id from a set, returning a fresh set so React sees the change. */ -const toggled = (previous: ReadonlySet, id: string): ReadonlySet => { - const next = new Set(previous); - - if (next.has(id)) { - next.delete(id); - } else { - next.add(id); - } - - return next; -}; - interface TraceLogsProps { /** Lines emitted under this trace, oldest first. */ readonly entries: ReadonlyArray; } /** - * The `ctx.log` lines emitted under one trace, shown beneath its waterfall. - * - * This is the drill-down the Traces page was missing: the waterfall says WHICH - * span was slow or threw, and the log lines say what the code thought it was - * doing at the time. Both were already on the wire — the log buffer simply - * dropped the `traceId` that joins them (see `@lunora/observability`'s - * `LogEntry`), so the two panels could never be put side by side. + * The `ctx.log` lines emitted under one trace, shown beneath its waterfall — the + * waterfall says WHICH span was slow or threw, these say what the code thought + * it was doing at the time. * * Read from the same live `getLogs` ring the Logs panel uses, so no extra RPC and * no extra retention: a line evicted from that ring disappears here too. @@ -71,188 +47,44 @@ const TraceLogs = ({ entries }: TraceLogsProps): ReactElement => { return (

    {t("Logs ({count})", { count: entries.length })}

    -
    - {entries.map((entry) => { - const fields = formatLogFields(entry.fields); - - return ( -
    - {formatTimestamp(entry.timestamp)} - - {entry.level} - - - {entry.message} - {fields === "" ? null : {fields}} - -
    - ); - })} -
    -
    - ); -}; - -interface TimeRulerProps { - /** Total duration the ruler annotates, in ms. */ - readonly traceDurationMs: number; -} - -/** - * Elapsed-time gridlines across the waterfall's timeline track, aligned with the - * span bars' own column so a bar's left edge can be read off a label. Renders - * nothing for a zero-duration trace, where {@link spanBar} lays every span out - * full-width and there is no timeline to annotate. - */ -const TimeRuler = ({ traceDurationMs }: TimeRulerProps): ReactElement | null => { - const ticks = traceTicks(traceDurationMs); - - if (ticks.length === 0) { - return null; - } - - return ( -
    - {/* Spacer columns mirroring SpanRow's name cell, so the track below starts at the same x. */} - - - {ticks.map((tick) => ( - - {tick.label} - - ))} - - - - -
    - ); -}; - -interface SpanRowProps { - /** Whether this span's detail block is open. */ - readonly expanded: boolean; - /** Lifts the per-row click out of the map so the row carries no inline closure. */ - readonly onToggle: (spanId: string) => void; - readonly span: TraceSpan; - /** The enclosing trace's total duration, the denominator for the bar geometry. */ - readonly traceDurationMs: number; -} - -/** - * One waterfall row: the span's name indented by its server-computed `depth`, a - * bar positioned by `offsetMs` and sized by `durationMs`, its duration, its - * structured attributes, and — when the body threw — an error chip plus message. - * - * Clicking the row opens {@link SpanDetail} beneath it. The row's attribute and - * error cells are hard-truncated to keep the waterfall scannable, so the detail - * block is the only place the full values are legible. - */ -const SpanRow = ({ expanded, onToggle, span, traceDurationMs }: SpanRowProps): ReactElement => { - const t = useT(); - const { leftPercent, widthPercent } = spanBar(span, traceDurationMs); - - // Rendered once; `""` (no attributes) skips the chip entirely rather than - // showing a blank span — the same convention as the Logs panel's fields. - const attributes = formatLogFields(span.attributes); - - const nameStyle: CSSProperties = { paddingLeft: span.depth * INDENT_PER_DEPTH }; - const barStyle: CSSProperties = { left: `${String(leftPercent)}%`, width: `${String(widthPercent)}%` }; - - const onClick = (): void => { - onToggle(span.spanId); - }; - - return ( -
  • - - - {expanded && ( -
    - -
    - )} -
  • + {entries.map((entry, index) => ( +
    + +
    + ))} + + ); }; interface TraceRowProps { /** Whether this trace's waterfall is currently expanded. */ readonly expanded: boolean; - /** Span ids whose detail block is open, across the whole list. */ - readonly expandedSpans: ReadonlySet; /** `ctx.log` lines emitted under this trace, oldest first. Empty when none were captured. */ readonly logs: ReadonlyArray; /** Lifts the per-row click out of the map so the row carries no inline closure. */ readonly onToggle: (traceId: string) => void; - readonly onToggleSpan: (spanId: string) => void; readonly trace: TraceSummary; } /** * One trace in the list: a clickable summary header (root name, function path, - * total duration, span count, ok/error badge) that expands into the waterfall, - * the spans' detail blocks, and the log lines the same dispatch emitted. + * total duration, span count, ok/error badge) that expands into the waterfall + * and the log lines the same dispatch emitted. */ -const TraceRow = ({ expanded, expandedSpans, logs, onToggle, onToggleSpan, trace }: TraceRowProps): ReactElement => { +const TraceRow = ({ expanded, logs, onToggle, trace }: TraceRowProps): ReactElement => { const t = useT(); const onClick = (): void => { @@ -290,18 +122,7 @@ const TraceRow = ({ expanded, expandedSpans, logs, onToggle, onToggleSpan, trace {expanded && (
    - -
      - {trace.spans.map((span) => ( - - ))} -
    + {logs.length > 0 && }
    )} @@ -323,14 +144,10 @@ interface TracesPanelProps { * Traces are the drill-down from a log line: a dispatch's synthetic root span * plus every `ctx.trace(name, fn)` span recorded beneath it. The server folds * them (`@lunora/do`'s pure `foldTraces`) and stamps each span with a `depth` - * and an `offsetMs`, so this panel does no tree math — it indents by `depth` and - * sizes each bar from `offsetMs`/`durationMs` via the pure {@link spanBar} helper. + * and an `offsetMs`, so nothing here does tree math — see `trace-waterfall.tsx`. * - * Expanding a trace gives the three things a waterfall alone cannot: an elapsed-time - * ruler to read a bar's position against, a per-span detail block with the FULL - * attribute bag / error / recorded span events (the row can only afford a truncated - * chip), and the `ctx.log` lines the same dispatch emitted, joined by `traceId` - * from the live log ring. + * Expanding a trace also brings up the `ctx.log` lines the same dispatch emitted, + * joined by `traceId` from the live log ring. * * The backing span ring is bounded and in-memory, so it resets on hibernation or * restart and a trace can legitimately arrive partial. This is a local-development @@ -354,7 +171,6 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { const [search, setSearch] = useState(pending?.traceId ?? ""); const [onlyErrors, setOnlyErrors] = useState(false); const [expanded, setExpanded] = useState>(() => new Set()); - const [expandedSpans, setExpandedSpans] = useState>(() => new Set()); // Consume the hand-off on mount (a committed boundary): clear the store so a // later manual visit isn't re-filtered. Clearing needs no setState, so this @@ -371,12 +187,15 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { ); // The same live log ring the Logs panel reads, joined to the waterfalls by - // `traceId`. A second read rather than a new correlated RPC: both rings are - // already pushed live over this socket, and joining two cheap reads client-side - // avoids a bespoke server-side join that would only ever serve this panel. - // Its failure is deliberately NOT surfaced — losing the log ring must degrade - // the trace detail, never blank the waterfalls the panel exists to show. - const { data: logsData } = useAdminQuery(ADMIN_FUNCTIONS.getLogs, {}, { live: true, shardKey: queryShardKey }); + // `traceId` — a client-side join of two reads already pushed over this socket, + // rather than a bespoke server-side join that would only ever serve this panel. + // + // Gated on an open trace: the log section renders only inside an expanded row, + // so an unconditional read would open a second live subscription and stream the + // whole ring on every visit to a page that starts fully collapsed. Its failure + // is deliberately not surfaced — losing the log ring must degrade the trace + // detail, never blank the waterfalls the panel exists to show. + const { data: logsData } = useAdminQuery(ADMIN_FUNCTIONS.getLogs, {}, { enabled: expanded.size > 0, live: true, shardKey: queryShardKey }); // Record the browsed shard into recent-shards history once the read resolves, // so a shard visited here shows up in every other panel's autocomplete — @@ -397,30 +216,10 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { // the loaded traces (the same model as the Logs panel's Errors view). const filtered = filterTraces(traces, search, onlyErrors); - // Index the log ring by trace once per read rather than scanning it per - // expanded trace: the ring holds up to 500 entries and every trace row would - // otherwise re-walk all of them on every render. - const logsByTrace = useMemo(() => { - const index = new Map(); - - // `getLogs` returns newest-first; a trace's own lines read as a narrative, - // so reverse into chronological order as they are bucketed. - for (const entry of (logsData?.entries ?? []).toReversed()) { - if (entry.traceId === undefined) { - continue; - } - - const bucket = index.get(entry.traceId); - - if (bucket === undefined) { - index.set(entry.traceId, [entry]); - } else { - bucket.push(entry); - } - } - - return index; - }, [logsData]); + // `getLogs` is newest-first; a trace's own lines read as a narrative, so + // reverse into chronological order before bucketing. Untraced lines land in an + // `undefined` bucket that no lookup can reach, which is the correct home. + const logsByTrace = Map.groupBy((logsData?.entries ?? []).toReversed(), (entry) => entry.traceId); const onSearchChange = (event: ChangeEvent): void => { setSearch(event.target.value); @@ -428,11 +227,17 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { // Toggle one trace in/out of the expanded set without mutating the prior set. const onToggle = (traceId: string): void => { - setExpanded((previous) => toggled(previous, traceId)); - }; + setExpanded((previous) => { + const next = new Set(previous); + + if (next.has(traceId)) { + next.delete(traceId); + } else { + next.add(traceId); + } - const onToggleSpan = (spanId: string): void => { - setExpandedSpans((previous) => toggled(previous, spanId)); + return next; + }); }; // A count of 0 while the first read is still in flight means the ring hasn't @@ -494,11 +299,9 @@ const TracesPanel = ({ initialShardKey }: TracesPanelProps): ReactElement => { {filtered.map((trace) => ( ))} diff --git a/packages/studio/src/hooks/use-open-trace.ts b/packages/studio/src/hooks/use-open-trace.ts new file mode 100644 index 0000000000..2817e8d335 --- /dev/null +++ b/packages/studio/src/hooks/use-open-trace.ts @@ -0,0 +1,26 @@ +import { useNavigate } from "@tanstack/react-router"; + +import { fireAndForget } from "../lib/internal"; +import { writePendingTraceFilter } from "../lib/trace-handoff"; + +/** + * The trace drill-down every panel with a trace id shares: stash the one-shot + * hand-off — with the shard the row was read from, so Traces searches that ring + * rather than the root's — then navigate to the Traces page, which consumes the + * hand-off on mount and pre-filters. + * + * Bundling the navigate with the write is the point: a caller that stashes but + * forgets to navigate leaves a filter that silently applies to the user's NEXT + * manual visit to Traces. The Metrics exemplar link and both Logs views drive + * the same two steps, so they drive them through here. + * @param shardKey Shard the calling panel is reading, carried into the hand-off. + */ +const useOpenTrace = (shardKey: string): ((traceId: string) => void) => { + const navigate = useNavigate(); + + return (traceId: string): void => { + writePendingTraceFilter({ shardKey, traceId }); + fireAndForget(navigate({ to: "/traces" })); + }; +}; +export default useOpenTrace; diff --git a/packages/studio/src/lib/admin.ts b/packages/studio/src/lib/admin.ts index b057d6e30a..eef1039b13 100644 --- a/packages/studio/src/lib/admin.ts +++ b/packages/studio/src/lib/admin.ts @@ -763,12 +763,7 @@ export interface LogEntry { message: string; timestamp: number; - /** - * Trace the line was emitted under. Present for lines emitted inside a - * dispatch; absent for container-lifecycle entries, hibernation-path errors, - * and any worker predating the field. What the Logs panel's "Trace" link and - * the Traces panel's correlated-logs section both key on. - */ + /** Trace the line was emitted under; absent outside a dispatch (container lifecycle, hibernation-path errors) and on any worker predating the field. The key the Logs panel's Trace link and the Traces panel's correlated logs both join on. */ traceId?: string; } @@ -951,15 +946,7 @@ export interface RequestLogEntry { /** Tables the handler wrote; empty for a read-only dispatch. */ tablesWritten: string[]; - /** - * W3C trace id (32-hex) of the dispatch; absent for a row written before the - * column existed. - * - * The request log is durable while the span ring it links to is in-memory, so - * a row older than the current DO instance carries an id whose waterfall is - * gone. The Trace link is therefore best-effort against local traces — the id - * still resolves in whatever collector `otlpSink` ships to. - */ + /** W3C trace id (32-hex) of the dispatch; absent on a row written before the column existed. The Trace link is best-effort — see `@lunora/observability`'s `request-log.ts` on the retention asymmetry. */ traceId?: string; /** Epoch-ms the dispatch completed. */ ts: number; diff --git a/packages/studio/src/locales/en.ts b/packages/studio/src/locales/en.ts index 908bc10b3a..7151b97ba1 100644 --- a/packages/studio/src/locales/en.ts +++ b/packages/studio/src/locales/en.ts @@ -1258,9 +1258,9 @@ const MESSAGE_IDS = [ "Errors only", "Recent traces", "Trace waterfall", - "Errored span", "{count} spans", - "starts {offset} in, runs {duration}", + "{name}, {duration}, starts {offset} in{failure}", + ", failed: {message}", "Showing the {shown} most recent of {total} traces in the buffer.", "No traces", // Observability — expanded span detail + the dispatch's correlated log lines From cbfa4d7968696618b9a56ce09d9d2cb19c58ad31 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sun, 9 Aug 2026 07:40:54 +0200 Subject: [PATCH 6/9] fix(do): correlate alarm-path log lines to the trigger's trace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The TTL sweep and the shape fan-out's alarm callers were recorded with no trace, on the claim that no trace was ambient. That was wrong: `withTriggerTrace` publishes an anchor for the whole alarm, so those lines were attributable all along — and the alarm is, per its own docstring, where a silent failure hides longest because no client is waiting on a response. Threading it by value rather than reading a field, because `recordShapeError` has callers on both the alarm and socket-frame paths: a field read there would let a socket frame interleaving at an await point file its own failure under the alarm's trace, which is the bug this branch already fixed once. - `withTriggerTrace` publishes its anchor on a dedicated `currentTriggerTrace`, needed only because `runner.handleAlarm()` sits between it and the handler - `handleAlarmCloudflare` captures that into a local synchronously at entry, before its first await, and passes it down through `pollTier`, `pollTtlSweeps` → `deleteExpiredTtlRow`, and `pollGlobalShapes` → `pollSocketGlobalShapes` - `recordShapeError` takes the anchor as an optional parameter, so the socket-frame callers stay untraced, which is correct for them The test drives two alarm ticks and asserts each contained failure carries its own 32-hex id; it fails without the threading. `recordExternalSourceError` is left alone — it is called from codegen-emitted code, so threading it is a cross-package change. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- api-snapshots/do.api.md | 2 +- packages/do/__tests__/shard-do.admin.test.ts | 31 ++++++++++ packages/do/src/shard-do.ts | 62 ++++++++++++++++---- 3 files changed, 82 insertions(+), 13 deletions(-) diff --git a/api-snapshots/do.api.md b/api-snapshots/do.api.md index feff217927..7e51f01840 100644 --- a/api-snapshots/do.api.md +++ b/api-snapshots/do.api.md @@ -370,7 +370,7 @@ abstract class ShardDO { protected pollExternalSources(): Promise; protected scheduleSourcePoll(): Promise; protected ttlSweeps(): ReadonlyArray; - protected pollTtlSweeps(): Promise; + protected pollTtlSweeps(trace?: TraceAnchor): Promise; protected scheduleTtlSweep(): Promise; protected currentShardKey(): string; protected recordExternalSourceError(table: string, error: unknown): void; diff --git a/packages/do/__tests__/shard-do.admin.test.ts b/packages/do/__tests__/shard-do.admin.test.ts index 7e3c80a88a..4002fec8e5 100644 --- a/packages/do/__tests__/shard-do.admin.test.ts +++ b/packages/do/__tests__/shard-do.admin.test.ts @@ -2111,6 +2111,37 @@ describe("shardDO admin data migrations", () => { expect(body.result.entries[0]).toMatchObject({ functionPath: "boom:explode", level: "error", message: "boom" }); }); + it("correlates an alarm-path failure to the trigger's own trace", async () => { + expect.assertions(3); + + // The alarm's ingest tier throws, so `pollTier` contains it and records a + // `source:poll` line — an alarm-path log site, which used to be recorded + // with no trace at all. + class FailingSourceShard extends AdminShard { + // eslint-disable-next-line class-methods-use-this -- test stub mirroring the codegen override + protected override pollExternalSources(): Promise { + return Promise.reject(new Error("source ingest exploded")); + } + } + + const shard = new FailingSourceShard(state, { LUNORA_ADMIN_TOKEN: ADMIN_TOKEN }); + + await shard.alarm(); + await shard.alarm(); + + const response = await shard.fetch(adminRequest(ADMIN_FUNCTIONS.getLogs, {})); + const body = await response.json<{ result: { entries: { functionPath?: string; message: string; traceId?: string }[] } }>(); + const lines = body.result.entries.filter((entry) => entry.functionPath === "source:poll"); + + expect(lines[0]?.message).toBe("source ingest exploded"); + // The alarm publishes an anchor through `withTriggerTrace`, so the line is + // attributable rather than orphaned — a 32-hex W3C trace id. + expect(lines[0]?.traceId).toMatch(/^[\da-f]{32}$/u); + // Each alarm tick mints its own anchor: a shared id would mean the second + // tick's failure was filed under the first tick's trace. + expect(lines[0]?.traceId).not.toBe(lines[1]?.traceId); + }); + it("getFunctionStats reports per-function call and error counts", async () => { expect.assertions(6); diff --git a/packages/do/src/shard-do.ts b/packages/do/src/shard-do.ts index 8f6b026566..f183cf0539 100644 --- a/packages/do/src/shard-do.ts +++ b/packages/do/src/shard-do.ts @@ -1005,6 +1005,20 @@ abstract class ShardDO { */ private currentRequestTrace: { rootSpanId: string; traceId: string } | undefined; + /** + * Anchor of the in-flight trigger (`withTriggerTrace`), handed across the + * `runner.handleAlarm()` boundary that stops the alarm handler from just + * taking it as an argument. + * + * A field only because of that indirection, and read under one rule: capture + * it into a local SYNCHRONOUSLY at the top of the handler, before any `await`. + * Read later it is no safer than `currentRequestTrace` — a socket frame + * interleaving at an await point would pick up the alarm's trace and file its + * own failure under it. Everything downstream takes the captured value as a + * parameter for exactly that reason. + */ + private currentTriggerTrace: TraceAnchor | undefined; + /** * Per-trace head-sampling state, keyed by `traceId` so concurrent dispatches on * the same DO instance can't clobber each other's decision. A DO interleaves @@ -3223,7 +3237,7 @@ abstract class ShardDO { * alarm re-arms promptly via `nextPollAlarmTarget`'s existing due-now floor, * rather than waiting out the full `TTL_SWEEP_INTERVAL_MS` cadence. */ - protected async pollTtlSweeps(): Promise { + protected async pollTtlSweeps(trace?: TraceAnchor): Promise { const specs = this.ttlSweeps(); if (specs.length === 0) { @@ -3243,7 +3257,7 @@ abstract class ShardDO { for (const id of page.ids) { // eslint-disable-next-line no-await-in-loop -- per-row writer deletes must serialise to avoid OCC contention on the shard DO (same reasoning as `runShardBulkDelete`) - const limitHit = await this.deleteExpiredTtlRow(spec.table, id, headroom); + const limitHit = await this.deleteExpiredTtlRow(spec.table, id, headroom, trace); if (limitHit) { return Date.now(); @@ -4621,18 +4635,24 @@ abstract class ShardDO { * as the host-specific handler while the engine is progressively extracted. */ protected async handleAlarmCloudflare(): Promise { + // Captured before the first `await`, then passed by value everywhere below: + // this handler is the alarm's own scope, so nothing has interleaved yet. + // `undefined` when the alarm ran outside `withTriggerTrace` (a direct call + // in a test), which simply leaves these log lines uncorrelated. + const trace = this.currentTriggerTrace; + this.globalPollScheduled = false; let globalShapesRemaining: number; try { - globalShapesRemaining = await this.pollGlobalShapes(); + globalShapesRemaining = await this.pollGlobalShapes(trace); } catch (error) { // `pollGlobalShapes` already contains per-socket/per-shape failures; // this guards a catastrophic failure (e.g. `getWebSockets` throwing) // so the poll heartbeat re-arms and retries next tick instead of // dying permanently and silently dropping every global subscriber. - this.recordShapeError("shape:poll", error); + this.recordShapeError("shape:poll", error, trace); globalShapesRemaining = 1; } @@ -4642,7 +4662,7 @@ abstract class ShardDO { try { return await run(); } catch (error) { - this.recordShapeError(tag, error); + this.recordShapeError(tag, error, trace); return Date.now() + ShardDO.GLOBAL_SHAPE_POLL_INTERVAL_MS; } @@ -4658,7 +4678,7 @@ abstract class ShardDO { // returns `undefined` (no TTL tables); the codegen subclass overrides // `ttlSweeps()` from the schema so the sweep pages + removes expired rows and // reports its next-due. - const nextTtlDueAt = await pollTier("ttl:sweep", async () => this.pollTtlSweeps()); + const nextTtlDueAt = await pollTier("ttl:sweep", async () => this.pollTtlSweeps(trace)); // Drain the tables the ingest poll just wrote: a sourced table is local, so // its `defineShape` subscribers are poked through the standard @@ -4740,6 +4760,13 @@ abstract class ShardDO { this.currentRequestTrace = anchor; } + // Published unconditionally, unlike the shared dispatch field above: this + // one is written only here, and a trigger is the only thing that reads it + // (synchronously, at entry — see the field's docstring). + const previousTrigger = this.currentTriggerTrace; + + this.currentTriggerTrace = anchor; + let failure: { thrown: unknown } | undefined; try { @@ -4749,6 +4776,8 @@ abstract class ShardDO { throw error; } finally { + this.currentTriggerTrace = previousTrigger; + if (claimed && this.currentRequestTrace === anchor) { this.currentRequestTrace = undefined; } @@ -8460,7 +8489,7 @@ abstract class ShardDO { * on an ordinary successful delete. Any OTHER thrown error still propagates — * only the meter's own signal is contained here. */ - private async deleteExpiredTtlRow(table: string, id: string, headroom: TransactionHeadroomTracker): Promise { + private async deleteExpiredTtlRow(table: string, id: string, headroom: TransactionHeadroomTracker, trace?: TraceAnchor): Promise { try { await this.deleteRowThroughWriter(table, id, headroom); @@ -8472,6 +8501,7 @@ abstract class ShardDO { level: "warn", message: `TTL sweep for "${table}" hit the transaction limit mid-batch; resuming next tick: ${error.message}`, timestamp: Date.now(), + traceId: trace?.traceId, }); return true; @@ -8487,13 +8517,20 @@ abstract class ShardDO { * best-effort fan-out: one socket's read or one shape's resolve failing must * never take down the others — so callers swallow the throw and surface it * here for diagnosis. `context` is a synthetic `shape:phase:subId` path. + * + * `trace` is passed by the alarm path, which has an anchor to attribute the + * failure to; the socket-frame callers omit it because their path is + * deliberately untraced (see `webSocketMessage`). It is a parameter rather + * than a field read so an alarm interleaving with a socket frame cannot file + * one path's failure under the other's trace. */ - private recordShapeError(context: string, error: unknown): void { + private recordShapeError(context: string, error: unknown, trace?: TraceAnchor): void { this.logs.push({ functionPath: context, level: "error", message: error instanceof Error ? error.message : String(error), timestamp: Date.now(), + traceId: trace?.traceId, }); } @@ -8527,7 +8564,7 @@ abstract class ShardDO { * subscribed so {@link ShardDO.alarm} knows whether to re-arm. Expired sockets * are dropped in passing (mirrors {@link ShardDO.pokeShapeSubscribers}). */ - private async pollGlobalShapes(): Promise { + private async pollGlobalShapes(trace?: TraceAnchor): Promise { const sockets = [...this.runner.sockets()]; let remaining = 0; @@ -8548,7 +8585,7 @@ abstract class ShardDO { const identity: SubscriptionIdentity = { identity: attachment.identity, userId: attachment.userId }; // eslint-disable-next-line no-await-in-loop -- per-socket reads are intentionally serialized to bound concurrent global reads per tick - remaining += await this.pollSocketGlobalShapes(ws, shapes, identity, attachment.connectionId ?? ""); + remaining += await this.pollSocketGlobalShapes(ws, shapes, identity, attachment.connectionId ?? "", trace); } return remaining; @@ -8566,6 +8603,7 @@ abstract class ShardDO { shapes: Record, identity: SubscriptionIdentity, connectionId: string, + trace?: TraceAnchor, ): Promise { let count = 0; @@ -8576,7 +8614,7 @@ abstract class ShardDO { resolved = this.resolveShape(shape.name, shape.args ?? {}, identity); } catch (error) { count += 1; - this.recordShapeError(`shape:poll:${subId}`, error); + this.recordShapeError(`shape:poll:${subId}`, error, trace); continue; } @@ -8591,7 +8629,7 @@ abstract class ShardDO { // eslint-disable-next-line no-await-in-loop -- per-shape D1 reads serialized within a socket to bound concurrency await this.refreshGlobalShape(ws, subId, resolved, identity, connectionId); } catch (error) { - this.recordShapeError(`shape:poll:${subId}`, error); + this.recordShapeError(`shape:poll:${subId}`, error, trace); } } From 00d5e457a1dcf10eef26488cc12a5ed169422ffe Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sun, 9 Aug 2026 08:03:13 +0200 Subject: [PATCH 7/9] fix(codegen): correlate external-source ingest failures, and stop reaching into a private field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the last uncorrelated alarm-path log site. The generated `pollExternalSources` override now takes the alarm's trace and forwards it to all three places it records a contained failure, so a `.source()` table's ingest error is attributable to the tick that produced it. While threading it, found that the emitted poll loop writes `this.logs.push(...)` — and `logs` is PRIVATE on `ShardDO`, so that statement cannot compile in the generated subclass. Any project declaring a `.source()` table has been emitting a shard that fails `tsc`. It went unnoticed because no fixture or example declares one and the emitted string is only ever asserted against as text, never compiled. Routed through a new protected `recordExternalSourceWarning` seam instead, which keeps the ring encapsulated and gives the line the same correlation as its sibling. The trace crosses the package boundary as `TraceRefLike`, a structural projection exported from `@lunora/do` — `@lunora/do` deliberately does not re-export `@lunora/observability`, and a generated app should not take on that dependency to name a parameter. Verified the emitted shape compiles from OUTSIDE the base class (a throwaway subclass mirroring exactly what the emitter writes) rather than trusting the substring assertions that missed the private access. Two new emit tests pin it: one asserts all three sites forward the trace, one asserts the output never contains `this.logs`. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- api-snapshots/do.api.md | 15 +++- api-snapshots/lunora.api.md | 4 ++ .../__tests__/emit-external-source.test.ts | 38 +++++++++- packages/codegen/src/emit.ts | 23 ++++--- packages/do/src/index.ts | 1 + packages/do/src/shard-do.ts | 69 +++++++++++++++---- 6 files changed, 122 insertions(+), 28 deletions(-) diff --git a/api-snapshots/do.api.md b/api-snapshots/do.api.md index 7e51f01840..f3fc5702f2 100644 --- a/api-snapshots/do.api.md +++ b/api-snapshots/do.api.md @@ -367,13 +367,14 @@ abstract class ShardDO { protected resolveShape(_name: string, _args: Record, _identity?: SubscriptionIdentity): ResolvedShape | undefined; protected isShapeRelayUniform(name: string, args: Record): boolean; protected readGlobalShapeRows(_resolved: ResolvedShape, _identity?: SubscriptionIdentity): Promise; - protected pollExternalSources(): Promise; + protected pollExternalSources(_trace?: TraceRefLike): Promise; protected scheduleSourcePoll(): Promise; protected ttlSweeps(): ReadonlyArray; - protected pollTtlSweeps(trace?: TraceAnchor): Promise; + protected pollTtlSweeps(trace?: TraceRefLike): Promise; protected scheduleTtlSweep(): Promise; protected currentShardKey(): string; - protected recordExternalSourceError(table: string, error: unknown): void; + protected recordExternalSourceError(table: string, error: unknown, trace?: TraceRefLike): void; + protected recordExternalSourceWarning(table: string, message: string, trace?: TraceRefLike): void; protected executeStream(_functionPath: string, _args: Record): null | { iterator: (signal: AbortSignal) => AsyncIterable; }; @@ -509,6 +510,14 @@ interface TelemetrySink { } ``` +### `TraceRefLike` (interface) + +```ts +interface TraceRefLike { + traceId: string; +} +``` + ### `TransactionHeadroomTracker` (class) Re-exported from `@lunora/shard-engine` — signature tracked at its source. diff --git a/api-snapshots/lunora.api.md b/api-snapshots/lunora.api.md index bf17c2e8c9..2a9f94530c 100644 --- a/api-snapshots/lunora.api.md +++ b/api-snapshots/lunora.api.md @@ -2237,6 +2237,10 @@ Re-exported from `@lunora/shard-engine` — signature tracked at its source. Re-exported from `@lunora/do` — signature tracked at its source. +### `TraceRefLike` (interface) + +Re-exported from `@lunora/do` — signature tracked at its source. + ### `TransactionHeadroomTracker` (class) Re-exported from `@lunora/shard-engine` — signature tracked at its source. diff --git a/packages/codegen/__tests__/emit-external-source.test.ts b/packages/codegen/__tests__/emit-external-source.test.ts index d1cae6ccdd..a0811db4ee 100644 --- a/packages/codegen/__tests__/emit-external-source.test.ts +++ b/packages/codegen/__tests__/emit-external-source.test.ts @@ -45,7 +45,7 @@ describe("emitShard — external-source ingest", () => { const shard = emitShard({ schema: discover(SOURCED) }); - expect(shard).toContain("protected override async pollExternalSources()"); + expect(shard).toContain("protected override async pollExternalSources(trace?: TraceRefLike)"); // The per-table work delegates to the tested @lunora/do helper, not an inline projection. expect(shard).toContain("pullExternalSourceTick(this.sql as SqlExec, writer, client"); // Incremental mode (plan 136) branches to the durable-watermark helper. @@ -62,7 +62,7 @@ describe("emitShard — external-source ingest", () => { // Plan 148: the override reports the earliest NEXT-DUE timestamp (not a // bare active count), so the shared alarm can sleep until a source is // actually due instead of spinning at the 2 s global-shape floor. - expect(shard).toContain("protected override async pollExternalSources(): Promise"); + expect(shard).toContain("protected override async pollExternalSources(trace?: TraceRefLike): Promise"); expect(shard).toContain("nextDueAt = nextDueAt === undefined ? sourceNextDueAt : Math.min(nextDueAt, sourceNextDueAt);"); // Plan 207 step 2: each table's writer gets its OWN fresh per-work-item // meter — an alarm tick has no `/rpc` dispatch to fall back to. @@ -71,7 +71,39 @@ describe("emitShard — external-source ingest", () => { // warns (not `recordExternalSourceError`) and leaves the table due so the // shared alarm re-arms promptly instead of throttling to `refresh.everyMs`. expect(shard).toContain('error instanceof LunoraError && error.code === "TRANSACTION_LIMIT_EXCEEDED"'); - expect(shard).toContain('level: "warn"'); + // The `warn` level itself is the base class's (`recordExternalSourceWarning`); + // what the emitter owns is routing the back-off there rather than to + // `recordExternalSourceError`, which would group it as a real Issue. + expect(shard).toContain("this.recordExternalSourceWarning("); + }); + + it("forwards the alarm's trace to every contained ingest failure it records", () => { + expect.assertions(4); + + const shard = emitShard({ schema: discover(SOURCED) }); + + // The parameter is only worth having if all three log sites in the + // generated poll loop actually pass it on — a signature that accepts a + // trace and drops it would leave these lines uncorrelated exactly as + // before, and the type-checker would not notice. + expect(shard).toContain("this.recordExternalSourceError(table, error, trace);"); + // A regex so the emitted `${source.binding}` interpolation stays out of a + // string literal (`no-template-curly-in-string`). + expect(shard).toMatch(/no sourceClient resolved for binding[^\n]*, trace\);/u); + expect(shard).toContain("this.recordExternalSourceWarning("); + // Structural projection from the base package, so a generated app never + // takes on an `@lunora/observability` dependency for this. + expect(shard).toContain("import type { ExternalSourceLike, SourceClientLike, TraceRefLike }"); + }); + + it("never reaches into the base class's private log ring", () => { + expect.assertions(1); + + // `logs` is private on `ShardDO`, so `this.logs.push(...)` in the emitted + // subclass does not type-check. Nothing caught it for the life of the + // feature because no fixture or example declares a `.source()` table, and + // the emitted string is never compiled — so assert the shape directly. + expect(emitShard({ schema: discover(SOURCED) })).not.toContain("this.logs"); }); it("stays byte-identical (none of the ingest surface) for a non-sourced schema", () => { diff --git a/packages/codegen/src/emit.ts b/packages/codegen/src/emit.ts index 100cb08a1a..ba76b02728 100644 --- a/packages/codegen/src/emit.ts +++ b/packages/codegen/src/emit.ts @@ -4297,7 +4297,11 @@ const LUNORA_RLS_READ_REGISTRY = buildRlsReadRegistry(Object.values(LUNORA_FUNCT const importLines = [ `import type { ${doTypeImports.join(", ")} } from "${base.do}";`, `import { applyCdcChanges, buildReprojectionMigration, ${shapeGuardImport}createReadFootprint, createShardCtxDb, exportShardRows, importShardRows, ${hasSourcedTables ? "isSourceDue, pullExternalSourceIncrementalTick, pullExternalSourceTick, " : ""}${hasShardedVectors ? "ROOT_SHARD_NAME, " : ""}runDataMigration, runShardMigrations, ${relationFanout.importFragment}ShardDO as ShardDOBase } from "${base.do}";`, - ...(hasSourcedTables ? [`import type { ExternalSourceLike, SourceClientLike } from "${base.do}";`] : []), + // `TraceRefLike` rides along with the source imports: the poll override + // takes the alarm's trace so its contained failures are correlated, and + // `@lunora/do` projects it structurally rather than re-exporting the + // observability type. + ...(hasSourcedTables ? [`import type { ExternalSourceLike, SourceClientLike, TraceRefLike } from "${base.do}";`] : []), // `asBucketStorage` (the bucket-aware `ctx.storage` wrapper) and // `createSecrets` (the `ctx.secrets` core built-in) live in // `@lunora/server`, the single source — imported here rather than stamped @@ -4598,7 +4602,7 @@ const sourcePollAtCache = new WeakMap>(); /* eslint-disable no-secrets/no-secrets -- the emitted `pullExternalSourceIncrementalTick(this.sql …)` poll-loop call is a dense generated identifier, not a credential */ const externalSourceOverride = hasSourcedTables ? ` - protected override async pollExternalSources(): Promise { + protected override async pollExternalSources(trace?: TraceRefLike): Promise { const env = (this.env ?? {}) as Record; const sourced = Object.entries((schema as unknown as SchemaLike).tables) .map(([table, definition]) => [table, (definition as { externalSource?: ExternalSourceLike }).externalSource] as const) @@ -4655,7 +4659,7 @@ const sourcePollAtCache = new WeakMap>(); // \`config.sourceClient\`, or wired it wrong). Surface it in the // Logs panel and stamp \`polledAt\` so a persistent misconfig backs // off to \`refresh.everyMs\` instead of retrying every alarm tick. - this.recordExternalSourceError(table, new Error(\`external-source: no sourceClient resolved for binding "\${source.binding}"\`)); + this.recordExternalSourceError(table, new Error(\`external-source: no sourceClient resolved for binding "\${source.binding}"\`), trace); } else { // A FRESH tracker per TABLE, not one shared across the whole // loop: one table's runaway pull must not spend a budget a @@ -4703,19 +4707,18 @@ const sourcePollAtCache = new WeakMap>(); // table stays "due" and \`nextPollAlarmTarget\`'s existing // due-now floor re-arms the shared alarm promptly — not a // fresh \`setAlarm(now)\`. - this.logs.push({ - functionPath: \`source:\${table}\`, - level: "warn", - message: \`external-source poll for "\${table}" hit the transaction limit mid-batch; resuming next tick: \${error.message}\`, - timestamp: Date.now(), - }); + this.recordExternalSourceWarning( + table, + \`external-source poll for "\${table}" hit the transaction limit mid-batch; resuming next tick: \${error.message}\`, + trace, + ); nextDueAt = nextDueAt === undefined ? now : Math.min(nextDueAt, now); continue; } - this.recordExternalSourceError(table, error); + this.recordExternalSourceError(table, error, trace); // Stamp on failure too, so a persistently failing source throttles // to \`refresh.everyMs\` rather than being hammered every tick. polledAt.set(table, Date.now()); diff --git a/packages/do/src/index.ts b/packages/do/src/index.ts index 2244d1fb71..93000fabc9 100644 --- a/packages/do/src/index.ts +++ b/packages/do/src/index.ts @@ -28,6 +28,7 @@ export type { ShardDOState, SubscriptionOutcome, TelemetrySink, + TraceRefLike, } from "./shard-do"; export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO, subscriptionListDeltas } from "./shard-do"; export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from "./shard-registry-do"; diff --git a/packages/do/src/shard-do.ts b/packages/do/src/shard-do.ts index f183cf0539..270fecbf7e 100644 --- a/packages/do/src/shard-do.ts +++ b/packages/do/src/shard-do.ts @@ -495,6 +495,21 @@ interface ContextLogger { with: (fields: LogFields) => ContextLogger; } +/** + * The only part of a trace anchor an alarm-path log site needs: the id it files + * the line under. + * + * Declared here as a structural projection rather than re-exporting + * `@lunora/observability`'s `TraceAnchor`, because `@lunora/do` deliberately + * does not re-export observability (see this package's index) and the generated + * shard — which forwards this value into `recordExternalSourceError` — must be + * able to name the type without taking on that dependency. A real `TraceAnchor` + * satisfies it, so internal callers pass theirs unchanged. + */ +interface TraceRefLike { + traceId: string; +} + /** * Minimal projection of `DurableObjectState` that the ShardDO base requires. * Declared structurally so unit tests can pass in plain object doubles @@ -3184,8 +3199,8 @@ abstract class ShardDO { * `GLOBAL_SHAPE_POLL_INTERVAL_MS` floor for a source whose `refresh.everyMs` * is, say, an hour away. */ - // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass implements the real Hyperdrive-backed poll - protected pollExternalSources(): Promise { + // eslint-disable-next-line class-methods-use-this -- base-class override hook: the codegen subclass implements the real Hyperdrive-backed poll, and is the only consumer of `_trace` + protected pollExternalSources(_trace?: TraceRefLike): Promise { return Promise.resolve(undefined); } @@ -3237,7 +3252,7 @@ abstract class ShardDO { * alarm re-arms promptly via `nextPollAlarmTarget`'s existing due-now floor, * rather than waiting out the full `TTL_SWEEP_INTERVAL_MS` cadence. */ - protected async pollTtlSweeps(trace?: TraceAnchor): Promise { + protected async pollTtlSweeps(trace?: TraceRefLike): Promise { const specs = this.ttlSweeps(); if (specs.length === 0) { @@ -3287,9 +3302,39 @@ abstract class ShardDO { return this.runner.shardKey ?? ROOT_SHARD_NAME; } - /** Record a contained external-source ingest failure (one sourced table's poll) into the log ring without aborting the others. */ - protected recordExternalSourceError(table: string, error: unknown): void { - this.recordShapeError(`source:${table}`, error); + /** + * Record a contained external-source ingest failure (one sourced table's + * poll) into the log ring without aborting the others. + * + * `trace` is the alarm's anchor, forwarded by the generated + * `pollExternalSources` override from the value it was handed. Optional so a + * subclass generated before this parameter existed still compiles and simply + * records an uncorrelated line. + */ + protected recordExternalSourceError(table: string, error: unknown, trace?: TraceRefLike): void { + this.recordShapeError(`source:${table}`, error, trace); + } + + /** + * Record a contained external-source BACK-OFF — a transaction-limit hit + * mid-batch, which is "batch full" rather than a failure, so it lands at + * `warn` and does NOT group as an Issue the way + * {@link ShardDO.recordExternalSourceError} does. + * + * Exists because the generated poll loop needs to write this line and the log + * ring is private: emitting `this.logs.push(...)` into the subclass does not + * compile, which went unnoticed only because no fixture or example declares a + * `.source()` table. A protected seam keeps the buffer encapsulated and gives + * the line the same trace correlation as its sibling above. + */ + protected recordExternalSourceWarning(table: string, message: string, trace?: TraceRefLike): void { + this.logs.push({ + functionPath: `source:${table}`, + level: "warn", + message, + timestamp: Date.now(), + traceId: trace?.traceId, + }); } /* eslint-disable no-secrets/no-secrets -- JSDoc names the `AsyncIterable` type, not a credential */ @@ -4672,7 +4717,7 @@ abstract class ShardDO { // base hook returns `undefined` (dormant); the codegen subclass overrides // it to materialize each sourced table and report the earliest NEXT-DUE // timestamp across every non-manual source. - const nextSourceDueAt = await pollTier("source:poll", async () => this.pollExternalSources()); + const nextSourceDueAt = await pollTier("source:poll", async () => this.pollExternalSources(trace)); // Declarative TTL expiry (`.ttl(...)`) shares this alarm too. The base hook // returns `undefined` (no TTL tables); the codegen subclass overrides @@ -8489,7 +8534,7 @@ abstract class ShardDO { * on an ordinary successful delete. Any OTHER thrown error still propagates — * only the meter's own signal is contained here. */ - private async deleteExpiredTtlRow(table: string, id: string, headroom: TransactionHeadroomTracker, trace?: TraceAnchor): Promise { + private async deleteExpiredTtlRow(table: string, id: string, headroom: TransactionHeadroomTracker, trace?: TraceRefLike): Promise { try { await this.deleteRowThroughWriter(table, id, headroom); @@ -8524,7 +8569,7 @@ abstract class ShardDO { * than a field read so an alarm interleaving with a socket frame cannot file * one path's failure under the other's trace. */ - private recordShapeError(context: string, error: unknown, trace?: TraceAnchor): void { + private recordShapeError(context: string, error: unknown, trace?: TraceRefLike): void { this.logs.push({ functionPath: context, level: "error", @@ -8564,7 +8609,7 @@ abstract class ShardDO { * subscribed so {@link ShardDO.alarm} knows whether to re-arm. Expired sockets * are dropped in passing (mirrors {@link ShardDO.pokeShapeSubscribers}). */ - private async pollGlobalShapes(trace?: TraceAnchor): Promise { + private async pollGlobalShapes(trace?: TraceRefLike): Promise { const sockets = [...this.runner.sockets()]; let remaining = 0; @@ -8603,7 +8648,7 @@ abstract class ShardDO { shapes: Record, identity: SubscriptionIdentity, connectionId: string, - trace?: TraceAnchor, + trace?: TraceRefLike, ): Promise { let count = 0; @@ -9264,4 +9309,4 @@ export type { // canonical home is `./subscription-delivery`. export { subscriptionListDeltas } from "@lunora/shard-engine"; -export type { HibernatableWebSocket, LogSink, ShardDOOptions, ShardDOState, SubscriptionOutcome, TelemetrySink }; +export type { HibernatableWebSocket, LogSink, ShardDOOptions, ShardDOState, SubscriptionOutcome, TelemetrySink, TraceRefLike }; From ec8ac8cc9cb666151c6a26d3a7c0cbf21d2fe023 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sun, 9 Aug 2026 08:15:47 +0200 Subject: [PATCH 8/9] test(codegen): compile the base-class surface the emitted shard depends on MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the gap that let `this.logs.push(...)` — a private access — ship inside the generated poll loop. The emitter produces TypeScript as a string and every test asserts on substrings of it; nothing compiles it, and golden fixtures cannot, since `tsconfig.json` excludes them (generated output only type-checks inside a whole app). Two halves, each useless alone: - `emitted-shard-contract.ts` is a real subclass of `ShardDO` exercising every base member the emitted sourced shard touches. It is never executed — it just has to compile, so `lint:types` fails in the package that owns the emitter the moment one of those members changes visibility or signature. - A test asserting the emitter still restricts itself to that set, computed as the delta between a sourced and a non-sourced shard's `this.*` usage, so it needs no hand-maintained allowlist of unrelated members. Verified both directions: adding `this.logs.push(...)` back to the contract reproduces the original `TS2341`, and making the emitter reach for an uncovered private member (`pendingChangedTables`) fails the delta test. Both reverted. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- .../__tests__/emit-external-source.test.ts | 22 +++++-- .../__tests__/emitted-shard-contract.ts | 59 +++++++++++++++++++ 2 files changed, 75 insertions(+), 6 deletions(-) create mode 100644 packages/codegen/__tests__/emitted-shard-contract.ts diff --git a/packages/codegen/__tests__/emit-external-source.test.ts b/packages/codegen/__tests__/emit-external-source.test.ts index a0811db4ee..0a87a73e40 100644 --- a/packages/codegen/__tests__/emit-external-source.test.ts +++ b/packages/codegen/__tests__/emit-external-source.test.ts @@ -96,14 +96,24 @@ describe("emitShard — external-source ingest", () => { expect(shard).toContain("import type { ExternalSourceLike, SourceClientLike, TraceRefLike }"); }); - it("never reaches into the base class's private log ring", () => { + it("only touches base-class members the compile-time contract covers", () => { expect.assertions(1); - // `logs` is private on `ShardDO`, so `this.logs.push(...)` in the emitted - // subclass does not type-check. Nothing caught it for the life of the - // feature because no fixture or example declares a `.source()` table, and - // the emitted string is never compiled — so assert the shape directly. - expect(emitShard({ schema: discover(SOURCED) })).not.toContain("this.logs"); + // The emitted shard is a string, so nothing type-checks it — which is how + // `this.logs.push(...)` (private on `ShardDO`) shipped in the poll loop for + // the life of this feature. `emitted-shard-contract.ts` compiles a subclass + // using each member below, so `lint:types` fails if one changes visibility + // or signature; this asserts the emitter still restricts itself to that set. + // + // Adding a member here means adding it to the contract file too — that + // pairing is the whole guard. Members read off `this` inside the emitted + // poll loop, ignoring locals and the `schema`/`config` module closures. + const membersOf = (shard: string): Set => new Set([...shard.matchAll(/\bthis\.([A-Za-z_]\w*)/gu)].map((match) => match[1] as string)); + + const plain = membersOf(emitShard({ schema: discover(PLAIN) })); + const added = [...membersOf(emitShard({ schema: discover(SOURCED) }))].filter((member) => !plain.has(member)).toSorted((a, b) => a.localeCompare(b)); + + expect(added).toStrictEqual(["alarmHeadroom", "currentShardKey", "recordExternalSourceError", "recordExternalSourceWarning", "scheduleSourcePoll"]); }); it("stays byte-identical (none of the ingest surface) for a non-sourced schema", () => { diff --git a/packages/codegen/__tests__/emitted-shard-contract.ts b/packages/codegen/__tests__/emitted-shard-contract.ts new file mode 100644 index 0000000000..6dba542a7c --- /dev/null +++ b/packages/codegen/__tests__/emitted-shard-contract.ts @@ -0,0 +1,59 @@ +/** + * A compile-time contract for the shard subclass `emitShard` generates. + * + * **Why this file exists.** The emitter produces TypeScript as a *string*, and + * every test around it asserts on substrings of that string. Nothing compiles + * it. So the generated code can reference a base-class member that a subclass + * cannot legally touch, and the whole suite stays green — which is exactly what + * happened: the external-source poll loop emitted `this.logs.push(...)` against + * a `private logs`, so every project declaring a `.source()` table emitted a + * shard that failed `tsc`. No fixture or example declares one, so nobody ran + * into it. + * + * Golden fixtures cannot close that gap: `tsconfig.json` deliberately excludes + * `__tests__/fixtures/**`, because generated output only type-checks inside a + * whole app (its schema, its `_generated` siblings, its bindings). This file is + * the cheap half of the job — it mirrors the base-class surface the emitted + * shard depends on, in a real subclass, so `lint:types` fails HERE, in the + * package that owns the emitter, the moment one of those members changes + * visibility or signature. + * + * It is not a test and is never executed. Keeping it honest is a two-part + * contract with `emit-external-source.test.ts`, which asserts the emitted text + * really does call these members (and really does not touch `this.logs`): + * this file proves the calls compile, that one proves they are the calls made. + * + * When the emitter starts using a new base member, add it here. + */ +import type { TraceRefLike } from "@lunora/do"; +import { ShardDO } from "@lunora/do"; + +class EmittedShardContract extends ShardDO { + // eslint-disable-next-line class-methods-use-this -- required abstract override; this file exercises the base surface, it never dispatches + public override handleRpc(): Promise { + return Promise.resolve(undefined); + } + + /** + * Mirrors the `hasSourcedTables` branch of the generated shard: the override + * signature, and every base member its poll loop touches. + */ + protected override async pollExternalSources(trace?: TraceRefLike): Promise { + await Promise.resolve(); + + const shardKey = this.currentShardKey(); + + this.alarmHeadroom(); + this.recordChangedTable("documents"); + + // The two contained-failure seams. `recordExternalSourceWarning` exists + // precisely so this loop never has to reach for the private log ring. + this.recordExternalSourceError("documents", new Error(shardKey), trace); + this.recordExternalSourceWarning("documents", "hit the transaction limit mid-batch", trace); + + await this.scheduleSourcePoll(); + + return undefined; + } +} +export default EmittedShardContract; From 034fc93189c6bc76c98f87b5a726bcd0344c3309 Mon Sep 17 00:00:00 2001 From: Daniel Bannert Date: Sun, 9 Aug 2026 08:40:16 +0200 Subject: [PATCH 9/9] test(studio): pin the correlated-log read to an expanded trace The gate that stops the Traces page opening a second live subscription on every visit had no test, so removing it would have broken nothing. Asserts `getLogs` is untouched while the list is collapsed and read once a trace opens; fails against the ungated version. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KBeSX2o4sTCPjVDRDWkVQG --- .../features/traces/traces-panel.test.tsx | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/packages/studio/__tests__/features/traces/traces-panel.test.tsx b/packages/studio/__tests__/features/traces/traces-panel.test.tsx index 9c87998ad9..a2095e30d1 100644 --- a/packages/studio/__tests__/features/traces/traces-panel.test.tsx +++ b/packages/studio/__tests__/features/traces/traces-panel.test.tsx @@ -318,6 +318,28 @@ describe("tracesPanel", () => { expect(rows[0]?.textContent).toContain("retrying"); }); + it("does not read the log ring until a trace is actually expanded", async () => { + expect.assertions(2); + + const mock = createClient(); + const readsLogs = (): boolean => mock.query.mock.calls.some((call) => (call[0] as { __lunoraRef: string }).__lunoraRef === ADMIN_FUNCTIONS.getLogs); + + render(renderPanel(mock)); + + await screen.findByTestId("tr-row-trace-send"); + + // The page starts fully collapsed, so the correlated-log section is not on + // screen; reading it unconditionally would open a second live subscription + // and stream the whole ring on every visit for nothing. + expect(readsLogs()).toBe(false); + + fireEvent.click(screen.getByTestId("tr-toggle-trace-send")); + + await waitFor(() => { + expect(readsLogs()).toBe(true); + }); + }); + it("omits the log section for a trace whose dispatch logged nothing", async () => { expect.assertions(1);