Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

perf(webapp): add sampled performance tracing across the app (#9302)

Wolf Mermelsteincb7e1042067e
diff --git a/.agents/rules/observability.md b/.agents/rules/observability.md
index d3f095ec38..454629c740 100644
--- a/.agents/rules/observability.md
+++ b/.agents/rules/observability.md
@@ -10,7 +10,7 @@ the user's action through every service it touches, with the timing and IDs need
to answer "what happened to this request and where did the time go". Reviewers
treat missing instrumentation on a new flow as a defect, like a missing test.
New flows and hot paths are instrumented in the same change, frontend and
-backend. The document open lifecycle (`doc.open`) and agent editing
+backend. The routed document load flow (`view.*` → `doc.load`) and agent editing
(`edit.session`) are the reference examples; the `instrumentation` skill walks
through them and the per-runtime APIs.
@@ -23,8 +23,17 @@ through them and the per-runtime APIs.
frame, worker call) needs inject on send and extract on receive. If a hop
can't carry context, record the upstream trace id as a span field.
- Web and Cloudflare Workers use the `@macro-inc/observability` `Telemetry`
- facade (`Telemetry.span`, `Telemetry.clientSpan`); don't import OpenTelemetry
- directly and don't add a second telemetry path.
+ facade (`Telemetry.span`); don't import OpenTelemetry
+ directly and don't add a second telemetry path (ast-grep
+ `ts/tsx-observability-facade`).
+- Browser context does not survive an `await`: retain the parent span (or a
+ `Telemetry.captureContext()` taken at synchronous admission, before auth or
+ scheduling yields) across awaits and retries, and pass it explicitly, e.g. in
+ mutation variables, never in the request payload. Don't restore global async
+ patches.
+- Web view loading and in-view interactions use `@app/observability/flow`
+ (`TraceFlow`, `usePending`, `useFlow().task`, `beginInteraction`), never a
+ hand-rolled root span per load.
## Spans at boundaries
diff --git a/.agents/skills/instrumentation/SKILL.md b/.agents/skills/instrumentation/SKILL.md
index f67963a322..bfaa961ff6 100644
--- a/.agents/skills/instrumentation/SKILL.md
+++ b/.agents/skills/instrumentation/SKILL.md
@@ -20,11 +20,13 @@ the spans. This skill is how to meet it.
Before writing code, sketch the trace you want to read during an incident:
```text
-doc.open (browser, root, document.id)
-├─ doc.load
-│ └─ doc.load.context (HTTP → DSS, traceparent header)
-├─ doc.seed / doc.sync.catchup
-└─ sync-service connect (WebSocket, traceparent query param)
+navigation (browser interaction)
+└─ view.<route> (caller-owned loading flow)
+ ├─ document.load / block.data
+ │ └─ doc.load → doc.load.context (HTTP → DSS)
+ ├─ doc.snapshot.*
+ └─ doc.editor
+ └─ doc.editor.initialize (initial sync → editor ready)
```
One root span per user action, one child per phase a reader would ask about
@@ -37,18 +39,162 @@ Use the `@macro-inc/observability` facade (`packages/observability`); never
import OpenTelemetry directly.
- `Telemetry.span(name, fn)` for a phase; `span.span(name, fn)` for a child.
- `Telemetry.clientSpan(name)` for an outbound call, then
+ `Telemetry.span(name, { kind: 'client' })` for an outbound call, then
`span.injectTraceHeaders(headers)`.
+- `Telemetry.span(name, { sampling: 'perf' })` puts a trace in a sampling
+ class; without one it is always kept. See
+ [What gets exported](#what-gets-exported).
- `span.setAttr(key, value)` for ids and counts; `span.error(message)` on
failure; manual spans must `end()` on every path.
-- A flow that spans components or outlives one call keeps its root span in a
- registry keyed by entity id and resumes it later (see the document example).
+- The browser uses a synchronous `StackContextManager`, so after an `await`
+ call `parent.span(...)`, or wrap later dispatch in `parent.run(...)`; see the
+ rule for `Telemetry.captureContext()`.
+- Share a caller-owned span through flow context and explicit client
+ parameters (`parentSpan`). Never keep entity-keyed span registries or end
+ another owner's span.
- Transports without headers carry `span.traceparent()` another way, such as a
WebSocket query parameter.
- Workers wrap their handler with `instrument()` and `createWorkerTraceConfig`
from `@macro-inc/observability/worker`, which adopts the incoming
`traceparent`.
+## Frontend view loading
+
+Use `@app/observability/flow` for user-visible loading. A flow is a span that
+stays open while anything under it is loading and ends one paint after the last
+hold releases.
+
+- **Views are roots already.** Router commits start a `navigation` interaction
+ and every routed view is a `view.<route id>` `<TraceFlow>` keyed on its
+ params (`RouteView` in `split-router/solid/outlet.tsx`). Don't add one per
+ route; add phases inside it.
+- **Phases: `usePending(name, accessor)`**, right after creating the query,
+ e.g. `usePending('channel.messages', () => query.isLoading)`. While the
+ accessor is true it holds the flow as a child span; it can start again each
+ time the flow is open. Already false when the flow reaches it (a cache hit or
+ an earlier view's load) records a `<name>.ready` event and
+ `<name>.waited=false` instead of a span; a real wait sets
+ `<name>.waited=true` on the parent. Read status only: reading pending
+ `query.data` suspends the enclosing shell. Track initial loading, not
+ background refreshes or a disabled query that cannot complete.
+- **Nested flows:** `<TraceFlow name="doc.editor">` around an independently
+ loaded subtree, placed **inside** its Suspense boundary (outside it the flow
+ can settle while the fallback shows). A view can hold several. Pass `key` to
+ restart it when the subtree shows a different entity in place; pending
+ phases move to the new run. Unmounting before it settles ends it, and its
+ open phases, as `flow.outcome=cancelled`.
+- **Async phases: `useFlow()`** during component setup, then
+ `flow.task('block.data', async (span) => ...)` for imperative loading. It
+ holds the flow until the promise settles and runs the synchronous start in
+ the child's context. A span alone does not hold the flow; give that work a
+ `usePending` or `task`.
+- **Requests in the flow:** urql and TanStack queries created inside a flow
+ already send in its trace. Start any other request inside
+ `flow.run(() => ...)`, or hand `useFlowTrace()` to a transport that sends
+ later.
+- **No Zone across `await`.** The browser's `StackContextManager` keeps context
+ only synchronously. After an await call `span.span(...)`, or wrap later work
+ in `span.run(...)`; capture `Telemetry.captureContext()` at synchronous
+ admission (before auth or queueing) and `.run(...)` the send in it.
+- **User actions: `beginInteraction('channel.tab')`** for an in-view action
+ that mounts content without navigation: update state, then `.end()` in a
+ `finally`. The window is synchronous; flows created inside it join it. Use
+ `startUiOperation` directly only for a measured action that mounts no flow (a
+ cell commit, a submit), calling `afterPaint()` once the UI updated.
+- **Sampling** is per trace; see [What gets exported](#what-gets-exported).
+- `flow.kind`, `route.id`, `flow.root`, `flow.outcome`, `<phase>.waited`,
+ `macro.sampling.*` and the `ui.*` timing fields come from the owners; never
+ set them per call site. Keep names static and attributes to opaque ids,
+ categories and counts. No flow per message, row or cell; measure the
+ containing view.
+
+Flows never schedule application work; preloading and warm-up own their own
+gates.
+
+### Example: a view with two phases
+
+The database block holds its view with two phases, the table's metadata and
+its first rows (`block-database/component/Block.tsx`, `DatabaseGrid.tsx`):
+
+```tsx
+function DatabaseDetail(props: { databaseId: string }) {
+ const detailQuery = useDatabaseDetailQuery(() => props.databaseId);
+ usePending('database.detail', () => detailQuery.isLoading);
+ return (
+ <Suspense fallback={<GridSkeleton />}>
+ <DatabaseGrid detail={detailQuery.data} />
+ </Suspense>
+ );
+}
+
+function DatabaseGrid(props: { detail: DatabaseDetail | undefined }) {
+ const source = useTableRows(() => props.detail);
+ usePending('database.rows', source.loading);
+ // ...
+}
+```
+
+Opened from a list this exports `navigation → view.<route id> →
+{database.detail, database.rows}`, with the HTTP and server spans under each
+phase. In Datadog, the root is `service:web-app @macro.sampling.class:perf
+resource_name:navigation @route.id:<route id> @ui.outcome:success`; read
+`@ui.elapsed_ms` (input to paint) and split by `@flow.kind` to compare entry
+points. On the view span, `@database.rows.waited:false` marks rows served from
+the cache; phase durations are `resource_name:database.rows
[email protected]:success`, with `@flow.root` naming the root. The
+`perf-investigation` skill has the tested query shapes, and the
+[observability walkthrough](../../../docs/agent-guide/observability.md#web-performance-traces)
+lists every root and attribute.
+
+## What gets exported
+
+Four layers decide whether a span reaches Datadog:
+
+1. **The global gate.** Built apps (browser and desktop) export only where
+ the `enable-browser-otel` PostHog flag is on; the Vite dev server exports
+ whenever a collector is configured, and `VITE_ENABLE_BROWSER_OTEL`
+ overrides both (`observability/browser.ts`). Spans are buffered from boot
+ and exported once enablement resolves; nothing is sent before it.
+2. **Unclassed spans: always exported** once the gate is open. A
+ `Telemetry.span(name)` with no `sampling` option. Use this for requests,
+ errors, mutations, background work and anything a backend trace hangs off:
+ `safeFetch` HTTP spans, `graphql.mutation_queue.attempt`, `channel.send`.
+3. **Sampling classes**, declared by the app in
+ `apps/web/src/observability/sampling.ts` with their rates:
+ - `perf` (5% of production users, every user elsewhere): performance
+ measurement. Flows, `beginInteraction`, `startUiOperation`,
+ `app.boot`, `input.typing_burst`, `app.runtime.sample`,
+ `urql.reconcile`. This is the default for `<TraceFlow>`,
+ `beginInteraction` and `startUiOperation`.
+ - `always` (every user): a span that must survive a dropped `perf` trace
+ under a class of its own.
+
+ Each class is decided once per user per class at enablement, from the user
+ id (the `frontend_instance_id` before sign-in) salted with the week, so the
+ cohort rotates weekly; `Telemetry.config.sampled('perf')` reads it, and
+ explicit native recordings keep every class. Exported spans in a classed
+ trace carry `macro.sampling.class` and `macro.sampling.rate` (weight counts
+ by `1 / rate`).
+
+ Nesting: a span joins its parent's trace when that trace is exported.
+ Otherwise a phase (`span.span`, `usePending`, `flow.task`) is dropped with
+ its root, and any other span starts its own trace when its own class is kept
+ (an unclassed span always is) and is dropped when it is not. So requests
+ started inside an unsampled perf trace still export as their own traces,
+ and their backend spans are never lost to perf sampling.
+4. **Backend.** Rust services and workers do not sample themselves: they
+ follow the incoming `traceparent`'s sampled flag (OpenTelemetry's default
+ parent-based sampler) and export the rest. Datadog then indexes a subset of
+ ingested spans; the perf retention filter in
+ `infra/stacks/monitoring/dashboards/web-performance.ts` keeps exported perf
+ traces searchable.
+
+**Picking a class.** Timing a view, phase or user action to rank or compare
+latency: use a flow or interaction (`perf`). Something that must be there to
+debug one user's failure, or that a backend trace joins: leave it unclassed. A
+new class belongs in `sampling.ts` with a rate, and only for a new kind of
+telemetry with its own volume budget.
+
## Rust services
- HTTP handlers already get spans from `macro_tower_layers`; outbound HTTP calls
@@ -65,11 +211,12 @@ import OpenTelemetry directly.
## Worked examples
**Document open lifecycle (web → DSS → sync-service).**
-`apps/web/src/features/block-md/definition.ts` starts or resumes `doc.open`
-(`document.id`, `doc.type`) and times `doc.load` → `doc.load.context`.
-`apps/web/src/features/block-md/observability.ts` keeps open document spans by
-id so the launcher's `doc.create`, the collab provider, and the sync client all
-attach to one trace. `packages/collaboration/src/collab/telemetry.ts` stamps
+`BlockLoader` and `FileDetailLoadGate` own loading tasks and pass their span to
+Markdown loaders. The loader times `doc.load` → `doc.load.context` and passes
+context to its sync source. The editor and collaboration adapter use the
+nearest flow context; collaboration reports ready without ending the caller's
+span. No `doc.open` root or document-id span registry is created.
+`packages/collaboration/src/collab/telemetry.ts` stamps
`document.id` and `session.id` on `doc.seed`, `doc.sync.catchup`, and
`edit.apply`. The sync WebSocket carries `traceparent` as a query parameter,
which sync-service reads with `worker_rs_otel::traceparent_from_request`.
@@ -102,6 +249,11 @@ can repeat forever reports counters instead of lines: each item logs a failure
class once, and `graphql.mutation_queue.summary` flushes counters every five
minutes only when something non-routine happened.
+## Reading production
+
+To find slow flows in Datadog from these spans, use the `perf-investigation`
+skill.
+
## Verify
Run the flow on the local stack and find its trace (see the `live-debug`
diff --git a/.agents/skills/perf-investigation/SKILL.md b/.agents/skills/perf-investigation/SKILL.md
new file mode 100644
index 0000000000..c8e83d8fd6
--- /dev/null
+++ b/.agents/skills/perf-investigation/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: perf-investigation
+description: >-
+ Find which web or desktop app flows are slow, for whom, and why, using the
+ Datadog MCP over the app's perf traces. Use when asked why the app, a view,
+ boot, navigation or an interaction is slow, to rank slow flows, to compare
+ platforms, OSes or versions, to check a performance change after a deploy,
+ or to map a slow span to its code.
+---
+
+# Perf investigation
+
+The web app (`service:web-app`, browser and Tauri desktop) exports `perf`-class
+traces: one root per boot, navigation, view or interaction, a child per phase,
+and HTTP spans that join backend services. Span names and required attributes
+are the [span model](../../../docs/agent-guide/observability.md#span-model);
+read it first. The dashboard is "Web app performance"
+(`infra/stacks/monitoring/dashboards/web-performance.ts`).
+
+## How web-app spans look in Datadog
+
+Verified against production web-app spans:
+
+- The span name is `resource_name`. `operation_name` is the span kind
+ (`Internal`, `http.client.request`); never group by it. HTTP client spans
+ (`http <METHOD> <path>` in Tempo) are `operation_name:http.client.request`
+ with the method as `resource_name`; group them by `@http.url` (no query string)
+ and time them with `@http.response_headers_ms`.
+- Span attributes are `@<attribute>` (`@route.id`, `@flow.kind`,
+ `@ui.work_to_ready_ms`). Resource attributes are facets too: `@app.platform`
+ (`web`, `desktop`, `ios`, `android`), `@app.runtime`, `@os.type`,
+ `@version` (group by `@version`; bare `version` returns nothing), and
+ `env` (`prod`, `development`, `dev`).
+- Numeric attributes are measures (`pc75` over `@ui.elapsed_ms` works).
+ Booleans arrive as strings: `@agent.session.load.cache_hit:true`.
+- `@duration` is nanoseconds; `ui.*_ms` fields are milliseconds; trace metrics
+ (`trace.Internal`) are seconds.
+- Grouping by a facet a span lacks drops that span from the result. Pass
+ `missing: "unknown"` in the SDK `groupBy` (the `aggregate_spans` tool cannot).
+ Spans from builds before `os.type` shipped in browsers have it only on desktop;
+ `@otel.user_agent:*Macintosh*` / `*Windows*` / `*Linux*` splits those.
+- Span search and aggregation see indexed spans only. The perf retention
+ filter keeps every exported perf trace once deployed; without it, counts are
+ a sample (diversity plus 1% flat). Use the `macro.web.*` span-based metrics
+ or `trace.Internal{service:web-app} by {resource_name,version}` (roots only,
+ 100% of ingested spans) for volume and percentiles.
+- DSS spans are `service:cloud-storage-service` in Datadog.
+
+## Pitfalls
+
+- Production exports perf traces for 5% of users (a cohort that rotates
+ weekly), and only where the `enable-browser-otel` PostHog flag is on. Weight
+ counts by `1 / @macro.sampling.rate` to estimate all users. Small routes have few samples:
+ report counts with every percentile.
+- Perf spans exist only from the release that shipped them; check `@version`
+ before concluding a flow is fast or missing.
+- Exclude non-success outcomes from load percentiles: roots
+ `@ui.outcome:success`, phases `@flow.outcome:success`. Views are roots
+ (`@flow.kind:view`) or phases of `navigation`/`app.boot`; filter by
+ `resource_name:view.*` to get both.
+- Phases overlap; never sum them. `<phase>.waited:false` means it was already
+ loaded, not necessarily a cache hit.
+- `ui.long_task_*` and `ui.long_animation_frame_*` overlap each other and are
+ not CPU time.
+
+## Workflow
+
+Load `datadog/traces` once, then run each step as one `execute_code` script.
+`agg` is reused below:
+
+```javascript
+import { client, v2 } from "@datadog/datadog-api-client";
+const spans = new v2.SpansApi(client.createConfiguration());
+const agg = (filter, compute, groupBy = []) =>
+ spans.aggregateSpans({ body: { data: { type: "aggregate_request",
+ attributes: { filter: { from: "now-7d", to: "now", ...filter }, compute, groupBy } } } })
+ .then((r) => r.data.map((b) => ({ by: b.attributes.by, ...b.attributes.compute })));
+```
+
+**1. Rank flows** by p75/p95 and volume:
+
+```javascript
+return agg(
+ { query: "service:web-app env:prod @macro.sampling.class:perf @flow.kind:* @ui.outcome:success" },
+ [ { aggregation: "count", type: "total" },
+ { aggregation: "pc75", metric: "@ui.elapsed_ms", type: "total" },
+ { aggregation: "pc95", metric: "@ui.elapsed_ms", type: "total" } ],
+ [ { facet: "resource_name", limit: 30,
+ sort: { type: "measure", aggregation: "pc95", metric: "@ui.elapsed_ms", order: "desc" } } ]);
+```
+
+Views (roots and phases): query `resource_name:view.* [email protected]:cancelled
[email protected]:(cancelled OR hidden OR timeout)`, metric `@duration`, group by
+`@route.id`.
+
+**2. Split the slow flow** by who sees it: add `groupBy` entries for
+`@app.platform`, `@os.type`, `@app.runtime` and `@version`, each with
+`missing: "unknown"`, filtered to its `resource_name`. For trends, use
+`type: "timeseries", interval: "12h"` on every compute.
+
+**3. Break it into phases.** Phases carry the root's name, so aggregate them
+without trace queries:
+
+```javascript
+return agg(
+ { query: "service:web-app env:prod @flow.root:navigation @route.id:view-mail @flow.outcome:success" },
+ [ { aggregation: "count", type: "total" },
+ { aggregation: "pc75", metric: "@duration", type: "total" } ],
+ [ { facet: "resource_name", limit: 30,
+ sort: { type: "measure", aggregation: "pc75", metric: "@duration", order: "desc" } } ]);
+```
+
+Then fetch exemplars at the slow tail and read their trees:
+
+```javascript
+const list = await spans.listSpansGet({
+ filterQuery: "service:web-app env:prod resource_name:view.view-mail @duration:>2000000000",
+ filterFrom: "now-1d", filterTo: "now", sort: "-timestamp", pageLimit: 5 });
+return list.data.map((s) => ({ trace: s.attributes.traceId, ns: s.attributes.custom?.duration }));
+```
+
+`get_datadog_trace` with each `trace` id gives every span's start and duration;
+compute each phase's offset from the root's start and look for the longest
+serial gap, not the longest span. Compare the root's `flow.ready_phase_count`
+and the `<phase>.waited` fields between fast and slow exemplars to separate
+cold loads from slow ones.
+
+**4. Correlate with the backend.** The same trace holds the
+`http <METHOD> <path>` and `graphql.transport` client spans and the server
+spans under them (`only_service_entry_spans: true` to summarise). Compare the
+client span with its server child: a large gap is network, queueing or auth
+refresh (`boot.auth.refresh`, `http POST /auth/jwt/refresh`), not the
+handler. To rank the endpoints perf traces wait on, aggregate
+`service:web-app @macro.sampling.class:perf operation_name:http.client.request`
+by `@http.url` over `@http.response_headers_ms`.
+
+**5. Main thread and resources.** On roots, compare `@ui.work_to_ready_ms`
+with `@ui.long_animation_frame_blocking_ms` and `@ui.long_task_overlap_ms`:
+blocking close to the elapsed time means the main thread, not the network.
+`resource_name:app.runtime.sample` carries `@macro.memory.js_heap.used_bytes`,
+`@runtime.long_animation_frame.blocking_ms` and `@runtime.session_age_ms`;
+bucket by session age with a histogram group:
+
+```javascript
+return agg(
+ { query: "service:web-app env:prod resource_name:app.runtime.sample" },
+ [ { aggregation: "pc75", metric: "@macro.memory.js_heap.used_bytes", type: "total" },
+ { aggregation: "count", type: "total" } ],
+ [ { facet: "@runtime.session_age_ms",
+ histogram: { interval: 600000, min: 0, max: 7200000 }, limit: 20 } ]);
+```
+
+Typing latency: `resource_name:input.typing_burst`, measure
+`@typing.event_duration_p95_ms`, group by `@typing.surface`.
+
+**6. Map the span to code.** Search the span name: `rg "'channel.messages'"
+apps/web/src` finds the `usePending`/`TraceFlow`/`beginInteraction` owner;
+`view.<route id>` comes from `lib/split-router/solid/outlet.tsx` with the
+route defined in the router; `http <METHOD> <path>` is the request path. The
+instrumentation skill explains each primitive.
+
+## Verify locally first
+
+Before relying on a new or renamed span in Datadog, run the flow on a local
+stack and find it in Tempo (`live-debug` skill): `{ span.flow.kind != nil }`
+lists roots, `{ span.flow.root = "navigation" }` its phases. Local traces are
+100% sampled. Perf data reaches Datadog only after the release ships.
+
+Report: the flows ranked (with counts), who is affected, the dominant phase or
+blocking work with exemplar trace links, the owning code, and what the sample
+size cannot tell.
diff --git a/CLAUDE.md b/CLAUDE.md
index f875fd62fa..f15076b89d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,7 +51,8 @@ Real files live in `.agents/`; tool-specific directories only symlink to it.
| --- | --- |
| Reusing database storage or separating it from an app entity | [Database core skill](.agents/skills/database-core/SKILL.md) |
| Adding collaborative markdown to a feature | [Collab surface core skill](.agents/skills/collab-surface-core/SKILL.md) |
-| Adding a flow or hot path, or tracing one | `instrumentation` skill |
+| Editing frontend or backend code that adds a flow, view, or hot path, or tracing one | `instrumentation` skill |
+| Finding slow web or desktop app flows in Datadog | `perf-investigation` skill |
| Rust code, builds, or tests | [Rust development](docs/development/rust.md) |
| SQLx queries, migrations, DB tests, or cache errors | [Database development](docs/development/database.md) |
| Web frontend | [Web agent guide](apps/web/AGENTS.md) |
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index b76d22204b..0ff96cdcd5 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -626,6 +626,9 @@ resolved session ID; keep the existing `AgentSessionProvider` subscription to
and asserts every observed row-ID state on revisits and an OPFS reload.
It also verifies that cold empty Mail tabs stay loading until HTTP settles.
It also runs in `just test-cache-wasm-browser`.
+- Trace initial Soup loading through pending flow phases; aggregate incremental
+ cache activity in `cache-activity-telemetry.ts`. Never start a root span per
+ cache revision or choose a root by comparing no-op span identity.
- Reactive GraphQL reads use `createLiveQuery` for a document and
`useSoupAstItemsQuery` (backed by `createSoupLiveQuery`) for Soup lists; see
[choosing a reactive read](docs/graphql-normalized-cache-plan.md#choosing-a-reactive-read).
@@ -996,3 +999,33 @@ and bot personas share one renderer; keep surface sizing in the caller.
- Advertise Mail v5 capsules only for the current browser engine or a verified supported installed native build; OTA bundle version alone cannot establish native capability.
- Bound native Mail capability discovery to 1.5 seconds and cache the legacy profile on failure or timeout so stalled IPC cannot block GraphQL transport; record the selected profile and bounded outcome in HTTP and WebSocket setup spans without error text.
+
+## Performance
+
+### Tracing
+
+- Instrument loading with the flow API in the `instrumentation` skill; read the
+ traces with the [observability guide](../../docs/agent-guide/observability.md#web-performance-traces).
+ Tracing observes readiness; never drive app behavior from trace callbacks.
+- Keep document load, snapshot and editor phases under the routed view flow and
+ pass its span explicitly to sync/AI clients; never store spans by document id
+ or end caller-owned spans in collaboration code. Acquire agent sessions in the
+ active view span.
+- Put flows at the shared owner so every host inherits them: Soup status in
+ `SoupViewListContent`; channel tabs in `ChannelTabProvider`, with each host's
+ `channel.*.view` inside the panel's Suspense and the routed detail observing
+ `detail.view().status` as `channel.detail`; form tabs and panels in
+ `FormPageView` (keep its builder/layout session alive across tabs); form
+ responding (`view.form-respond`, `form.submit`) keyed on form and preview
+ mode; CRM detail in the shared company/contact views keyed by record and
+ section; Command-K input through `beginInteraction` and a query-keyed results
+ flow with debounce/source `usePending` phases, no manual per-input signals
+ (the universal-input browser suite checks the exported traces).
+- Cancel the form-submit measurement on teardown but let its in-flight save
+ finish; late completion must not scroll or measure another view.
+- Runtime resource samples and typing bursts use the `perf` class decision
+ (`Telemetry.config.sampled('perf')`) and the shared UI-operation observer: no
+ second observer, no per-key frame sampling, no listeners for unsampled users. Typing surfaces come from
+ static `data-input-surface` categories on editor/field owners, never caller
+ labels.
+- Keep record names, addresses, answers and query text out of attributes.
diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.md
index 4de95badce..0bdbfa4275 100644
--- a/apps/web/docs/graphql-normalized-cache-plan.md
+++ b/apps/web/docs/graphql-normalized-cache-plan.md
@@ -956,6 +956,98 @@ Date rollover uses the original server bin as old membership. The
`graphql_cache.soup_grouped_local_evaluation` span records grouping field,
loaded baseline size and resulting bin count.
+#### Mail window evaluation cost
+
+Mail through-cursor reads start with the requested visible minimum plus one
+lookahead row (bounded by the index page limit), then grow their scan size
+geometrically only when the cursor is deeper. Previously each read started with
+499 indexed rows and loaded their sort projections even for a 20-row window.
+The shared `soup_filter_cache_adapter::mail` owner applies this policy to native
+and browser engines. Cursor fingerprints are independent of page size; retained
+server membership and the 5,000-row window ceiling keep their existing semantics.
+
+Repeat the native benchmark with
+`SOUP_BENCHMARK_FIXTURE=/tmp/mail-fixture.json cargo run --release -p soup-filter-cache-adapter --example mail_window_benchmark`.
+It seeds 2,000 canonical threads in in-memory Turso and measures 20 warm through
+reads at each window size. The optional fixture uses the Rust capsule encoder.
+For worker/OPFS and JavaScript phase timings, serve
+`src/lib/queries/soup/graphql/browser-test/vite.config.ts` from `apps/web`, then run
+`bun scripts/benchmark-mail-evaluation.ts /tmp/mail-fixture.json /tmp/mail-timings.json`.
+Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` for a system browser. The runner throttles
+the renderer 4x, isolates worker samples by operation/window, and separates
+cache-read round trips from JavaScript projection. It does not measure network,
+DOM rendering, or native IPC. Setup and warmup are excluded from reported runs.
+
+On the measured 2,000-thread fixture, native median 20-row evaluation fell from
+21.48 to 3.07 ms; browser filter round trip fell from 25.10 to 3.00 ms and total
+cache-read/projection evaluation from 28.45 to 5.10 ms. A 499-row window was
+approximately unchanged. The initial 20-row worker filter was 24.5 ms while
+JavaScript projection was about 0.1 ms: the dominant cost was inside the worker,
+not cross-worker transport or JavaScript materialization. These are fixture
+measurements, not production p90s.
+
+#### Cache notification coalescing
+
+Native maintained views return a `registrationId` bound to the engine's retained
+validated specification. The native host keeps at most 32 descriptors; subsequent
+reads of the same descriptor send only its view id, registration token and
+subscriber revision. Token lookup and the read share the engine lease. Replacement,
+release, eviction or reset makes resume miss, so the host registers the complete
+specification again. Older binaries without a token continue using full requests.
+Revision/reset/delta semantics remain the same. Empty explicit-key selections
+need only a fresh engine revision and send no unused selection document.
+
+Soup's revision observer and maintained predicate reader both use
+`subscribeToVisibleCacheChanges`: leading/trailing 250 ms coalescing while
+visible, one dirty refresh after visibility returns, and serialized asynchronous
+reads. Generation resets and explicit/initial reads remain immediate. The
+revision fence still observes every accepted notification before scheduling
+work, so a late persistence acknowledgement cannot regain network authority.
+Predicate snapshots publish revision progress independently of stable row/order
+identities; the Soup adapter memoizes those inputs before materializing rows.
+
+Hydration still emits notifications, but a shared cache-core owner may attach
+`unchangedViews`: immutable observation tokens whose displayed windows are proven
+unchanged through that notification's revision. Each accepted maintained-view
+read or Mail page advertises its own token. Fragment reads bind recursive record
+dependencies; the Mail compiler also binds the readable-account catalog's
+`emailLinks` field, so unrelated fields on that parent do not wake Mail.
+
+The owner uses the complete record/projection journal, validated predicate,
+selected and baseline keys, and a proven full-window sort cutoff. A matching
+entrant, selected dependency change, uncertain facts, optimistic composition,
+journal barrier/gap, or evicted token prevents a proof. Observations are bounded
+to 64 snapshots. Proof failure preserves the committed hydration and broadcasts
+broadly. Older native engines omit tokens and continue conservative refreshes;
+no new request arguments are sent across that deployed boundary.
+
+Mail cutoffs additionally require a known matching lookahead row, tracked as a
+record/projection dependency. Its continued membership proves the cursor still
+exists. Exhausted windows omit that cutoff so older hydration can expose a new
+continuation; deleting the last lookahead also invalidates the proof.
+
+The subscriber skips only its exact accepted observation. Pagination clears its
+proof until a through-read observes the combined window. Batched hydration
+notifications intersect proofs across all writes. Calendar coverage commits
+record their complete normalized deletion set in the same journal and carry the
+same proof metadata, without changing calendar range invalidation. Quick Access search bucket
+hints remain insufficient for Soup property/membership invalidation. Filtering,
+sorting, proof decisions and maintained view deltas stay in the shared Rust
+owners; screen components do not inspect changed entity kinds.
+
+`soup.network`, `soup.cache`, and the initial `soup.local` pending phases join
+existing route flows through paint. Incremental cache evaluations create no
+standalone spans and do not compare no-op span identity. The shared Soup
+telemetry owner aggregates predicate/local read counts, rows, changed-row
+counts, retries, errors, discarded reads, durations, authority transitions and
+stale-fallback durations into `graphql_cache.soup_updates.summary` logs at most
+once per five active minutes per tab. It retains only fixed numeric categories,
+uses no timers, and isolates exporter failures. Durations in that summary are
+aggregate measurements, not duplicate duration attributes on operation spans.
+`urql.reconcile` times the Solid bridge, and subscription cache application has
+separate write/delete children and an effect count so transport waits are visible
+per effect.
+
#### Grouped projection performance
Run `bun scripts/benchmark-grouped-soup.ts /tmp/grouped-soup.json` from
@@ -1068,3 +1160,64 @@ version mechanism, preserving normalized records, pending mutations, and storage
generation. This does not expand hydration: automatic backfill remains 90 days of
signal email and 30 days of noise email, plus any other cached threads. Explicit
full-text search reaches older uncached mail.
+
+
+### Foreground writes and background hydration
+
+Native `EngineAccess` reserves FIFO mutex turns for foreground commands.
+Background hydration waits on release notifications without reserving a turn;
+a foreground authoritative write advances the admission epoch. A waiting page
+whose epoch is superseded returns an error before touching storage. The worker
+owner applies the same rule by rejecting earlier queued hydration within the
+current lifecycle segment. Foreground write order is preserved. An already
+running storage transaction finishes atomically.
+
+Soup backfill treats this supersession as flow control: it refetches the same
+cursor after a short interruptible delay, preserving its checkpoint. Ordinary
+network/storage failures retain the lane's existing bounded retry policy.
+Calendar range and delta callers await their persisted occurrence fetches
+before sending coverage/replacement commits; those commits may supersede
+unrelated queued hydration just like other authoritative writes.
+
+`graphql.subscription.cache_queue` times preceding effects from the same
+subscription operation. `graphql.subscription.cache_apply` starts afterward
+and includes host readiness, IPC, engine admission and persistence. Native IPC
+has a 10-second request deadline, so a 10-second apply duration alone does not
+prove successful engine work. Apply/write/delete spans carry `cache.failure`
+from the bounded cache error classifier; use it with `cache.effects_applied`
+to distinguish timeouts from successful slow applies. Native engine admission
+has a `graphql_cache.native.lock` phase, emitted once by `EngineAccess`
+for each foreground or hydrate acquisition. Its `graphql_cache.lock.wait_ms`
+includes waiting until admission or supersession, not time holding the lock. Native scheduling changes require a
+rebuilt native binary; older installed binaries retain their scheduling.
+
+### Native IPC transport
+
+The Tauri host coalesces identical concurrent `readQuery` calls, including their
+operation registration identity. It never retains a completed result. Commands
+and native change notifications invalidate pending-read reuse, so writes and
+resets cannot cause a later caller to share an older read. Conservative operation
+invalidations coalesce until the next task. Before delivering field patches,
+cache changes (including resets), hydration or mutation settlements, the host
+flushes earlier invalidations so other observers cannot overtake them. Disposal
+drops pending callbacks.
+
+Native live views advertise a specification-bound registration token. The host
+retains at most 32 descriptors and resumes an unchanged specification from its
+id, token and revision; a missing registration triggers a full request. Changed
+specifications, release, reset and disposal invalidate retention. Older
+installed binaries omit the token and keep receiving full requests. Empty record
+selections fetch only the current revision, with no unused fragment.
+
+`graphql_cache.ipc.request` is a `perf`-class span (`sampling: 'perf'`) that
+records command and outcome. The webview does not re-encode read
+arguments to count bytes or create spans for notification callbacks.
+`graphql_cache.ipc.notification` in the native emitter measures serialization and
+emission, recording the single serialized payload's byte count. Native read, watch,
+write, and hydration spans include the shared owner’s lock-wait child phase,
+with `graphql_cache.lock.kind` set to `foreground` or `hydrate`. Native receive spans
+carry the originating webview trace id, since the native logger does not adopt
+the browser OpenTelemetry context. No payload content is
+recorded. Broadcast operation notifications carry operation ids and optional field
+patches, without a redundant entity-key list. The native emitter serializes once
+and uses `emit_str`; consumers still receive ordinary JSON events.
diff --git a/apps/web/native-commands.json b/apps/web/native-commands.json
index 528da430ba..966ea9028b 100644
--- a/apps/web/native-commands.json
+++ b/apps/web/native-commands.json
@@ -23,6 +23,7 @@
"graphql_cache_delete_records",
"graphql_cache_enqueue_optimistic_mutation",
"graphql_cache_entity_filter",
+ "graphql_cache_entity_filter_resume",
"graphql_cache_hydrate",
"graphql_cache_init_with_schema",
"graphql_cache_inspect_mutations",
diff --git a/apps/web/patches/opentelemetry-otlp-exporter-base-0.220.0.patch b/apps/web/patches/opentelemetry-otlp-exporter-base-0.220.0.patch
new file mode 100644
index 0000000000..c4a19e5380
--- /dev/null
+++ b/apps/web/patches/opentelemetry-otlp-exporter-base-0.220.0.patch
@@ -0,0 +1,210 @@
+diff --git a/build/src/configuration/convert-legacy-browser-http-options.js b/build/src/configuration/convert-legacy-browser-http-options.js
+--- a/build/src/configuration/convert-legacy-browser-http-options.js
++++ b/build/src/configuration/convert-legacy-browser-http-options.js
+@@ -13,6 +13,7 @@
+ function convertLegacyBrowserHttpOptions(config, signalResourcePath, requiredHeaders) {
+ return (0, otlp_http_configuration_1.mergeOtlpHttpConfigurationWithDefaults)({
+ url: config.url,
++ fetch: config.fetch,
+ timeoutMillis: config.timeoutMillis,
+ headers: (0, convert_legacy_http_options_1.convertLegacyHeaders)(config),
+ concurrencyLimit: config.concurrencyLimit,
+diff --git a/build/src/configuration/otlp-http-configuration.js b/build/src/configuration/otlp-http-configuration.js
+--- a/build/src/configuration/otlp-http-configuration.js
++++ b/build/src/configuration/otlp-http-configuration.js
+@@ -46,6 +46,7 @@
+ function mergeOtlpHttpConfigurationWithDefaults(userProvidedConfiguration, fallbackConfiguration, defaultConfiguration) {
+ return {
+ ...(0, shared_configuration_1.mergeOtlpSharedConfigurationWithDefaults)(userProvidedConfiguration, fallbackConfiguration, defaultConfiguration),
++ fetch: userProvidedConfiguration.fetch ?? fallbackConfiguration.fetch ?? defaultConfiguration.fetch,
+ headers: mergeHeaders(userProvidedConfiguration.headers, fallbackConfiguration.headers, defaultConfiguration.headers),
+ url: validateUserProvidedUrl(userProvidedConfiguration.url) ??
+ fallbackConfiguration.url ??
+diff --git a/build/src/transport/fetch-transport.js b/build/src/transport/fetch-transport.js
+--- a/build/src/transport/fetch-transport.js
++++ b/build/src/transport/fetch-transport.js
+@@ -45,9 +45,9 @@
+ // This creates an indirect endless loop Export -> Span -> Export
+ // By using the `__original` function the instrumentation can't intercept the call
+ // and no Span will be created breaking the vicious cycle
+- let fetchApi = globalThis.fetch;
++ let fetchApi = this._parameters.fetch ?? globalThis.fetch;
+ // @ts-expect-error -- fetch could be wrapped
+- if (typeof fetchApi.__original === 'function') {
++ if (!this._parameters.fetch && typeof fetchApi.__original === 'function') {
+ // @ts-expect-error -- fetch could be wrapped
+ fetchApi = fetchApi.__original;
+ }
+diff --git a/build/src/configuration/legacy-base-configuration.d.ts b/build/src/configuration/legacy-base-configuration.d.ts
+--- a/build/src/configuration/legacy-base-configuration.d.ts
++++ b/build/src/configuration/legacy-base-configuration.d.ts
+@@ -1,5 +1,7 @@
+ import type { HeadersFactory } from './otlp-http-configuration';
+ export interface OTLPExporterConfigBase {
++ /** Explicit browser transport; bypasses discovery of wrapped global fetch. */
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ /**
+ * Custom headers that will be attached to the HTTP request that's sent to the endpoint.
+ *
+diff --git a/build/src/configuration/otlp-http-configuration.d.ts b/build/src/configuration/otlp-http-configuration.d.ts
+--- a/build/src/configuration/otlp-http-configuration.d.ts
++++ b/build/src/configuration/otlp-http-configuration.d.ts
+@@ -2,6 +2,7 @@
+ export type HeadersFactory = () => Promise<Record<string, string>>;
+ export interface OtlpHttpConfiguration extends OtlpSharedConfiguration {
+ url: string;
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ headers: HeadersFactory;
+ }
+ /**
+diff --git a/build/src/transport/fetch-transport.d.ts b/build/src/transport/fetch-transport.d.ts
+--- a/build/src/transport/fetch-transport.d.ts
++++ b/build/src/transport/fetch-transport.d.ts
+@@ -2,6 +2,7 @@
+ import type { HeadersFactory } from '../configuration/otlp-http-configuration';
+ export interface FetchTransportParameters {
+ url: string;
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ headers: HeadersFactory;
+ }
+ /**
+diff --git a/build/esm/configuration/convert-legacy-browser-http-options.js b/build/esm/configuration/convert-legacy-browser-http-options.js
+--- a/build/esm/configuration/convert-legacy-browser-http-options.js
++++ b/build/esm/configuration/convert-legacy-browser-http-options.js
+@@ -10,6 +10,7 @@
+ export function convertLegacyBrowserHttpOptions(config, signalResourcePath, requiredHeaders) {
+ return mergeOtlpHttpConfigurationWithDefaults({
+ url: config.url,
++ fetch: config.fetch,
+ timeoutMillis: config.timeoutMillis,
+ headers: convertLegacyHeaders(config),
+ concurrencyLimit: config.concurrencyLimit,
+diff --git a/build/esm/configuration/otlp-http-configuration.js b/build/esm/configuration/otlp-http-configuration.js
+--- a/build/esm/configuration/otlp-http-configuration.js
++++ b/build/esm/configuration/otlp-http-configuration.js
+@@ -43,6 +43,7 @@
+ export function mergeOtlpHttpConfigurationWithDefaults(userProvidedConfiguration, fallbackConfiguration, defaultConfiguration) {
+ return {
+ ...mergeOtlpSharedConfigurationWithDefaults(userProvidedConfiguration, fallbackConfiguration, defaultConfiguration),
++ fetch: userProvidedConfiguration.fetch ?? fallbackConfiguration.fetch ?? defaultConfiguration.fetch,
+ headers: mergeHeaders(userProvidedConfiguration.headers, fallbackConfiguration.headers, defaultConfiguration.headers),
+ url: validateUserProvidedUrl(userProvidedConfiguration.url) ??
+ fallbackConfiguration.url ??
+diff --git a/build/esm/transport/fetch-transport.js b/build/esm/transport/fetch-transport.js
+--- a/build/esm/transport/fetch-transport.js
++++ b/build/esm/transport/fetch-transport.js
+@@ -42,9 +42,9 @@
+ // This creates an indirect endless loop Export -> Span -> Export
+ // By using the `__original` function the instrumentation can't intercept the call
+ // and no Span will be created breaking the vicious cycle
+- let fetchApi = globalThis.fetch;
++ let fetchApi = this._parameters.fetch ?? globalThis.fetch;
+ // @ts-expect-error -- fetch could be wrapped
+- if (typeof fetchApi.__original === 'function') {
++ if (!this._parameters.fetch && typeof fetchApi.__original === 'function') {
+ // @ts-expect-error -- fetch could be wrapped
+ fetchApi = fetchApi.__original;
+ }
+diff --git a/build/esm/configuration/legacy-base-configuration.d.ts b/build/esm/configuration/legacy-base-configuration.d.ts
+--- a/build/esm/configuration/legacy-base-configuration.d.ts
++++ b/build/esm/configuration/legacy-base-configuration.d.ts
+@@ -1,5 +1,7 @@
+ import type { HeadersFactory } from './otlp-http-configuration';
+ export interface OTLPExporterConfigBase {
++ /** Explicit browser transport; bypasses discovery of wrapped global fetch. */
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ /**
+ * Custom headers that will be attached to the HTTP request that's sent to the endpoint.
+ *
+diff --git a/build/esm/configuration/otlp-http-configuration.d.ts b/build/esm/configuration/otlp-http-configuration.d.ts
+--- a/build/esm/configuration/otlp-http-configuration.d.ts
++++ b/build/esm/configuration/otlp-http-configuration.d.ts
+@@ -2,6 +2,7 @@
+ export type HeadersFactory = () => Promise<Record<string, string>>;
+ export interface OtlpHttpConfiguration extends OtlpSharedConfiguration {
+ url: string;
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ headers: HeadersFactory;
+ }
+ /**
+diff --git a/build/esm/transport/fetch-transport.d.ts b/build/esm/transport/fetch-transport.d.ts
+--- a/build/esm/transport/fetch-transport.d.ts
++++ b/build/esm/transport/fetch-transport.d.ts
+@@ -2,6 +2,7 @@
+ import type { HeadersFactory } from '../configuration/otlp-http-configuration';
+ export interface FetchTransportParameters {
+ url: string;
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ headers: HeadersFactory;
+ }
+ /**
+diff --git a/build/esnext/configuration/convert-legacy-browser-http-options.js b/build/esnext/configuration/convert-legacy-browser-http-options.js
+--- a/build/esnext/configuration/convert-legacy-browser-http-options.js
++++ b/build/esnext/configuration/convert-legacy-browser-http-options.js
+@@ -10,6 +10,7 @@
+ export function convertLegacyBrowserHttpOptions(config, signalResourcePath, requiredHeaders) {
+ return mergeOtlpHttpConfigurationWithDefaults({
+ url: config.url,
++ fetch: config.fetch,
+ timeoutMillis: config.timeoutMillis,
+ headers: convertLegacyHeaders(config),
+ concurrencyLimit: config.concurrencyLimit,
+diff --git a/build/esnext/configuration/otlp-http-configuration.js b/build/esnext/configuration/otlp-http-configuration.js
+--- a/build/esnext/configuration/otlp-http-configuration.js
++++ b/build/esnext/configuration/otlp-http-configuration.js
+@@ -43,6 +43,7 @@
+ export function mergeOtlpHttpConfigurationWithDefaults(userProvidedConfiguration, fallbackConfiguration, defaultConfiguration) {
+ return {
+ ...mergeOtlpSharedConfigurationWithDefaults(userProvidedConfiguration, fallbackConfiguration, defaultConfiguration),
++ fetch: userProvidedConfiguration.fetch ?? fallbackConfiguration.fetch ?? defaultConfiguration.fetch,
+ headers: mergeHeaders(userProvidedConfiguration.headers, fallbackConfiguration.headers, defaultConfiguration.headers),
+ url: validateUserProvidedUrl(userProvidedConfiguration.url) ??
+ fallbackConfiguration.url ??
+diff --git a/build/esnext/transport/fetch-transport.js b/build/esnext/transport/fetch-transport.js
+--- a/build/esnext/transport/fetch-transport.js
++++ b/build/esnext/transport/fetch-transport.js
+@@ -42,9 +42,9 @@
+ // This creates an indirect endless loop Export -> Span -> Export
+ // By using the `__original` function the instrumentation can't intercept the call
+ // and no Span will be created breaking the vicious cycle
+- let fetchApi = globalThis.fetch;
++ let fetchApi = this._parameters.fetch ?? globalThis.fetch;
+ // @ts-expect-error -- fetch could be wrapped
+- if (typeof fetchApi.__original === 'function') {
++ if (!this._parameters.fetch && typeof fetchApi.__original === 'function') {
+ // @ts-expect-error -- fetch could be wrapped
+ fetchApi = fetchApi.__original;
+ }
+diff --git a/build/esnext/configuration/legacy-base-configuration.d.ts b/build/esnext/configuration/legacy-base-configuration.d.ts
+--- a/build/esnext/configuration/legacy-base-configuration.d.ts
++++ b/build/esnext/configuration/legacy-base-configuration.d.ts
+@@ -1,5 +1,7 @@
+ import type { HeadersFactory } from './otlp-http-configuration';
+ export interface OTLPExporterConfigBase {
++ /** Explicit browser transport; bypasses discovery of wrapped global fetch. */
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ /**
+ * Custom headers that will be attached to the HTTP request that's sent to the endpoint.
+ *
+diff --git a/build/esnext/configuration/otlp-http-configuration.d.ts b/build/esnext/configuration/otlp-http-configuration.d.ts
+--- a/build/esnext/configuration/otlp-http-configuration.d.ts
++++ b/build/esnext/configuration/otlp-http-configuration.d.ts
+@@ -2,6 +2,7 @@
+ export type HeadersFactory = () => Promise<Record<string, string>>;
+ export interface OtlpHttpConfiguration extends OtlpSharedConfiguration {
+ url: string;
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ headers: HeadersFactory;
+ }
+ /**
+diff --git a/build/esnext/transport/fetch-transport.d.ts b/build/esnext/transport/fetch-transport.d.ts
+--- a/build/esnext/transport/fetch-transport.d.ts
++++ b/build/esnext/transport/fetch-transport.d.ts
+@@ -2,6 +2,7 @@
+ import type { HeadersFactory } from '../configuration/otlp-http-configuration';
+ export interface FetchTransportParameters {
+ url: string;
++ fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+ headers: HeadersFactory;
+ }
+ /**
diff --git a/apps/web/src/components/app/GlobalHotkeys.tsx b/apps/web/src/components/app/GlobalHotkeys.tsx
index e4d726adc4..b359529126 100644
--- a/apps/web/src/components/app/GlobalHotkeys.tsx
+++ b/apps/web/src/components/app/GlobalHotkeys.tsx
@@ -13,6 +13,7 @@ import { openMacroMcpSetupModal } from '@app/features/integrations/mcp-setup/Mac
import { useAnalytics } from '@app/lib/analytics/analytics-context';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
import { inEnglish, t } from '@app/lib/i18n';
+import { beginInteraction } from '@app/observability/flow';
import { useSubscribeToKeypress } from '@app/signal/hotkeyRoot';
import { globalSplitManager } from '@app/signal/splitLayout';
import { useHandleFileUpload } from '@app/util/handleFileUpload';
@@ -220,14 +221,21 @@ export default function GlobalShortcuts() {
const handleFileUpload = useHandleFileUpload();
const snippetsFlag = useFeatureFlag(enableSnippets);
- const handleCommandMenu = () => {
+ const handleCommandMenu = (event?: KeyboardEvent) => {
const willOpen = !CommandState.isOpen();
if (willOpen) {
analytics.track('command_menu_open', { from: 'global_hotkey' });
}
- CommandState.toggle();
+ const interaction = willOpen
+ ? beginInteraction('quick_access.open', { event })
+ : undefined;
+ try {
+ CommandState.toggle();
+ } finally {
+ interaction?.end();
+ }
};
registerHotkey({
@@ -315,9 +323,9 @@ export default function GlobalShortcuts() {
CommandState.isOpen()
? t('commands.closeCommandMenu')
: t('commands.openCommandMenu'),
- keyDownHandler: () => {
+ keyDownHandler: (event) => {
console.log('## CMD K - global');
- handleCommandMenu();
+ handleCommandMenu(event);
return true;
},
displayPriority: 10,
diff --git a/apps/web/src/features/activity/views/my-activity-view.tsx b/apps/web/src/features/activity/views/my-activity-view.tsx
index fcb96ac6c8..18859d464f 100644
--- a/apps/web/src/features/activity/views/my-activity-view.tsx
+++ b/apps/web/src/features/activity/views/my-activity-view.tsx
@@ -1,5 +1,6 @@
import { ViewSidebar } from '@app/components/view-shell';
import { SoupSectionHeader } from '@app/features/next-soup/soup-view/section-header';
+import { usePending } from '@app/observability/flow';
import { SplitHeaderLeft } from '@components/app/split-layout/components/SplitHeader';
import { StaticMarkdownContext } from '@core/component/LexicalMarkdown/component/core/StaticMarkdown';
import { isTouchDevice } from '@core/mobile/isTouchDevice';
@@ -87,6 +88,11 @@ export function MyActivityView(props: {
}) {
const context = useActivityContext();
const state = createMyActivityState(context, () => props.scope);
+ usePending('activity.feed', () => state.feed().t === 'loading');
+ usePending(
+ 'activity.overview',
+ () => props.scope !== 'team' && state.overview().t === 'loading'
+ );
const [scroller, setScroller] = createSignal<HTMLDivElement>();
const [topSpacer, setTopSpacer] = createSignal<HTMLDivElement>();
const topSpacerSize = createElementSize(topSpacer);
diff --git a/apps/web/src/features/auth/useSsoLogin.test.ts b/apps/web/src/features/auth/useSsoLogin.test.ts
index d2dabd2460..e422f1916b 100644
--- a/apps/web/src/features/auth/useSsoLogin.test.ts
+++ b/apps/web/src/features/auth/useSsoLogin.test.ts
@@ -24,7 +24,10 @@ vi.mock('@app/lib/analytics/analytics-context', () => ({
useAnalytics: () => ({ track: mocks.track }),
}));
vi.mock('@solidjs/router', () => ({ useLocation: () => mocks.location }));
-vi.mock('@core/constant/servers', () => ({ SERVER_HOSTS: mocks.servers }));
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
+ SERVER_HOSTS: mocks.servers,
+}));
vi.mock('@core/mobile/isNativeMobilePlatform', () => ({
isNativeMobilePlatform: () => mocks.nativeMobile,
}));
diff --git a/apps/web/src/features/block-agent/agent-session-provider.tsx b/apps/web/src/features/block-agent/agent-session-provider.tsx
index 7ba6684933..3e4076d01b 100644
--- a/apps/web/src/features/block-agent/agent-session-provider.tsx
+++ b/apps/web/src/features/block-agent/agent-session-provider.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
/** App-facing composition for the agent session and its controllers. */
import { createInteractionController } from '@app/features/agent-interactions/primitives/create-interaction-controller';
@@ -50,13 +51,19 @@ export function AgentSessionProvider(
acquired,
} = resolveSessionId(() => props.blockId);
+ usePending('agent.provision', pending);
+
createEffect(() => {
const id = sessionId();
if (id && id !== props.blockId) props.onSessionId?.(id);
});
const userId = useUserId();
- const live = createAgentSession(sessionId, { userId, onAcquire: acquired });
+ const live = createAgentSession(sessionId, {
+ userId,
+ provisioning: pending,
+ onAcquire: acquired,
+ });
// A block opened by sending a first prompt shows that prompt, and the
// working line under it, from its very first paint. Nothing else can: the
// session does not exist until `POST /agent-sessions` answers, and the
diff --git a/apps/web/src/features/block-agent/context/create-agent-session.test.tsx b/apps/web/src/features/block-agent/context/create-agent-session.test.tsx
index fdd9059d0f..1158fe875c 100644
--- a/apps/web/src/features/block-agent/context/create-agent-session.test.tsx
+++ b/apps/web/src/features/block-agent/context/create-agent-session.test.tsx
@@ -7,9 +7,24 @@
*/
import { err, ok } from 'neverthrow';
-import { Show, Suspense } from 'solid-js';
+import { batch, createSignal, Show, Suspense } from 'solid-js';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const readiness = vi.hoisted(() => ({ painted: vi.fn(), cancelled: vi.fn() }));
+vi.mock('@app/observability/ui-operation', async (importOriginal) => {
+ const { NOOP_SPAN } = await import('@macro-inc/observability');
+ return {
+ ...(await importOriginal<
+ typeof import('@app/observability/ui-operation')
+ >()),
+ startUiOperation: () => ({
+ span: NOOP_SPAN,
+ afterPaint: readiness.painted,
+ cancel: readiness.cancelled,
+ }),
+ };
+});
+
const fold = vi.hoisted(() => ({
pushSession: vi.fn(),
readSession: vi.fn(),
@@ -50,6 +65,7 @@ vi.mock('@queries/agent-session/session-metadata-sync', () => ({
const { cleanup, render, screen } = await import('@solidjs/testing-library');
const { AgentSession } = await import('@core/agent-session/AgentSession');
const { createAgentSession } = await import('./create-agent-session');
+const { TraceFlow } = await import('@app/observability/flow');
const SESSION = '01a0ced3-b839-75ee-bc9b-7b0a11ce0789';
const bot = { id: 'bot-id', name: 'Agent', handle: 'agent' };
@@ -57,7 +73,10 @@ const session = { id: SESSION, name: 'A session', canEdit: true };
/** Reads the session row the way a pane's title does — outside any error gate. */
function Pane() {
- const live = createAgentSession(() => SESSION, { userId: () => 'me' });
+ const live = createAgentSession(() => SESSION, {
+ userId: () => 'me',
+ provisioning: () => false,
+ });
return (
<>
<h1>{live.session()?.name ?? 'untitled'}</h1>
@@ -149,3 +168,54 @@ describe('createAgentSession', () => {
expect(screen.queryByText('loading')).toBeNull();
});
});
+
+it('keeps view readiness pending through provisioning and the first transcript load', async () => {
+ const [id, setId] = createSignal<string>();
+ const [pending, setPending] = createSignal(true);
+ const log = deferred<{ bot: typeof bot; rows: never[] }>();
+ logSource.fetched.mockReturnValue(log.promise);
+ function ProvisionedPane() {
+ const live = createAgentSession(id, {
+ userId: () => 'me',
+ provisioning: pending,
+ });
+ return <h1>{live.session()?.name ?? 'Provisioning'}</h1>;
+ }
+ render(() => (
+ <TraceFlow name="view.agent">
+ <ProvisionedPane />
+ </TraceFlow>
+ ));
+ await Promise.resolve();
+ expect(readiness.painted).not.toHaveBeenCalled();
+ batch(() => {
+ setId(SESSION);
+ setPending(false);
+ });
+ await Promise.resolve();
+ expect(readiness.painted).not.toHaveBeenCalled();
+ log.resolve({ bot, rows: [] });
+ await screen.findByText('A session');
+ expect(readiness.painted).toHaveBeenCalledOnce();
+});
+
+it('settles view readiness when provisioning fails without a session id', async () => {
+ const [pending, setPending] = createSignal(true);
+ function FailedPane() {
+ createAgentSession(() => undefined, {
+ userId: () => 'me',
+ provisioning: pending,
+ });
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="view.agent">
+ <FailedPane />
+ </TraceFlow>
+ ));
+ await Promise.resolve();
+ expect(readiness.painted).not.toHaveBeenCalled();
+ setPending(false);
+ await Promise.resolve();
+ expect(readiness.painted).toHaveBeenCalledOnce();
+});
diff --git a/apps/web/src/features/block-agent/context/create-agent-session.ts b/apps/web/src/features/block-agent/context/create-agent-session.ts
index dc877a236f..30fbeeac07 100644
--- a/apps/web/src/features/block-agent/context/create-agent-session.ts
+++ b/apps/web/src/features/block-agent/context/create-agent-session.ts
@@ -1,3 +1,4 @@
+import { useFlow, usePending } from '@app/observability/flow';
/**
* The Solid face of {@link AgentSession}: the shared session for whatever id
* the block currently shows, as a reconciled ordered store of folded messages
@@ -113,6 +114,8 @@ export function createAgentSession(
options: {
/** The viewer, so a speculated prompt is attributed as the log will. */
userId: Accessor<string | undefined>;
+ /** Keeps initial readiness open while a new session is provisioned. */
+ provisioning: Accessor<boolean>;
/** This view now owns a reference; a pending navigation may release its own. */
onAcquire?: () => void;
}
@@ -129,6 +132,7 @@ export function createAgentSession(
// time, and the detach blanks the transcript and drops the caret to
// `<body>`. Absent is a state it already renders — that is the whole point
// of the placeholder — so report that for the first fetch instead.
+ const loadSpan = useFlow().span;
const openedPending = sessionId() === undefined;
const [list, setList] = createStore<FoldedMessage[]>([]);
@@ -202,7 +206,7 @@ export function createAgentSession(
const live = createMemo(() => {
const id = sessionId();
if (!id) return undefined;
- const session = AgentSession.acquire(id);
+ const session = loadSpan.run(() => AgentSession.acquire(id));
const unsubscribe = session.subscribe(applyEvents);
onCleanup(() => {
unsubscribe();
@@ -287,6 +291,11 @@ export function createAgentSession(
}
);
+ usePending(
+ 'agent.transcript',
+ () => options.provisioning() || resource.loading
+ );
+
async function settleInBackground(
session: AgentSession,
renameRefreshAtStart: number
diff --git a/apps/web/src/features/block-agent/context/pending-session.test.tsx b/apps/web/src/features/block-agent/context/pending-session.test.tsx
index c5461602f4..a5153786af 100644
--- a/apps/web/src/features/block-agent/context/pending-session.test.tsx
+++ b/apps/web/src/features/block-agent/context/pending-session.test.tsx
@@ -78,6 +78,7 @@ function Destination(props: { id: string }) {
const resolved = resolveSessionId(() => props.id);
const live = createAgentSession(resolved.sessionId, {
userId: () => 'me',
+ provisioning: resolved.pending,
onAcquire: resolved.acquired,
});
return <p>{resolved.error() ?? live.session()?.name}</p>;
diff --git a/apps/web/src/features/block-canvas/canvas-next-document.tsx b/apps/web/src/features/block-canvas/canvas-next-document.tsx
index 36f2b3a92d..24a762c655 100644
--- a/apps/web/src/features/block-canvas/canvas-next-document.tsx
+++ b/apps/web/src/features/block-canvas/canvas-next-document.tsx
@@ -1,3 +1,4 @@
+import { useFlow, usePending } from '@app/observability/flow';
import { ENABLE_MENTION_TRACKING } from '@core/constant/featureFlags';
import { useUserId } from '@core/context/user';
import { getDisplayName, tryMacroId } from '@core/user';
@@ -65,20 +66,25 @@ function CanvasDocumentSession(
const activePointers = new Set<number>();
const userId = useUserId();
const openedBy = userId();
- const sync = canvasSyncSource(documentId, userId);
+ const flow = useFlow();
+ const sync = canvasSyncSource(documentId, userId, flow.span);
const canEdit = () =>
props.canEdit &&
!props.isNested &&
userId() === openedBy &&
sync.canWrite();
- const session = createCanvasSession({
- documentId,
- initial,
- requireShared: props.shared,
- userId: userId(),
- canEdit,
- ...sync,
- });
+ const session = flow.span.run(() =>
+ createCanvasSession({
+ documentId,
+ span: flow.span,
+ initial,
+ requireShared: props.shared,
+ userId: userId(),
+ canEdit,
+ ...sync,
+ })
+ );
+ usePending('canvas.sync', () => session.state().t === 'loading');
const sharedDoc = () => {
const state = session.state();
return state.t === 'ready' ? state.doc : undefined;
diff --git a/apps/web/src/features/block-canvas/component/CanvasDocument.tsx b/apps/web/src/features/block-canvas/component/CanvasDocument.tsx
index a40109ede0..b0f5dbae5d 100644
--- a/apps/web/src/features/block-canvas/component/CanvasDocument.tsx
+++ b/apps/web/src/features/block-canvas/component/CanvasDocument.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import {
type Accessor,
createResource,
@@ -75,6 +76,7 @@ function CanvasDocumentLoader(props: CanvasDocumentProps) {
}
}
);
+ usePending('canvas.parse', () => loaded.loading);
return (
<Show when={!loaded.loading} fallback={<Loading />}>
<Switch>
diff --git a/apps/web/src/features/block-canvas/definition.ts b/apps/web/src/features/block-canvas/definition.ts
index c501a83c11..df385e1cff 100644
--- a/apps/web/src/features/block-canvas/definition.ts
+++ b/apps/web/src/features/block-canvas/definition.ts
@@ -21,7 +21,7 @@ export const definition = defineBlock({
canvas: 'application/x-macro-canvas',
},
liveTrackingEnabled: true,
- async load(source, intent) {
+ async load(source, intent, parentSpan) {
if (source.type === 'dss') {
if (intent === 'preload') {
await fetchFileDocumentOpenContext(source.id);
@@ -32,7 +32,7 @@ export const definition = defineBlock({
}
const maybeDocument = await loadResult(
- catchToResult(() => loadCanvasDocument(source.id))
+ catchToResult(() => loadCanvasDocument(source.id, parentSpan))
);
if (maybeDocument.isErr()) return err(maybeDocument.error);
const documentResult = maybeDocument.value;
diff --git a/apps/web/src/features/block-canvas/queries/canvas-session.ts b/apps/web/src/features/block-canvas/queries/canvas-session.ts
index 282bf8f833..e4faec81d7 100644
--- a/apps/web/src/features/block-canvas/queries/canvas-session.ts
+++ b/apps/web/src/features/block-canvas/queries/canvas-session.ts
@@ -1,7 +1,3 @@
-import {
- endTrackedDocumentSpan,
- registerDocumentSpan,
-} from '@block-md/observability';
import { fireAndForget } from '@core/util/fireAndForget';
import { schema } from '@loro-mirror/core';
import { createAwareness } from '@macro-inc/collaboration/collab/awareness';
@@ -31,7 +27,7 @@ import {
WALSyncer,
} from '@macro-inc/collaboration/collab/wal';
import type { PeerPresence } from '@macro-inc/graphics/loro';
-import { Telemetry } from '@macro-inc/observability';
+import type { Span } from '@macro-inc/observability';
import type { LoroDoc } from 'loro-crdt';
import { err, errAsync, type ResultAsync } from 'neverthrow';
import {
@@ -52,6 +48,7 @@ type CanvasConnection = {
export type CanvasSessionOptions = {
documentId: string;
initial: CanvasFile;
+ span?: Span;
requireShared?: boolean;
userId?: string;
canEdit: Accessor<boolean>;
@@ -173,6 +170,7 @@ export function createCanvasSession(options: CanvasSessionOptions) {
}
const manager = new CanvasManager(schema({}), {
documentId: options.documentId,
+ parentSpan: options.span,
// The graphics backend owns the typed scene Mirror on this same document.
mirror: false,
});
@@ -294,6 +292,7 @@ export function createCanvasSession(options: CanvasSessionOptions) {
};
const engine = createSyncEngine({
loroManager: manager,
+ parentSpan: options.span,
awareness,
syncs: { live, wal },
bindings: { onRemoteState: () => {} },
@@ -432,14 +431,12 @@ export function createCanvasSession(options: CanvasSessionOptions) {
return hydration;
}
async function runInitialization() {
- const span = Telemetry.span('canvas.open');
- span.setAttr('document.id', options.documentId);
- span.setAttr('document.type', 'canvas');
- registerDocumentSpan(options.documentId, span);
+ const span = options.span;
try {
- await span.span('canvas.hydrate', hydrate);
+ if (span) await span.span('canvas.hydrate', hydrate);
+ else await hydrate();
} catch (cause) {
- span.error(cause);
+ span?.error(cause);
if (!disposed && started)
setFailure(
'Live canvas sync is unavailable. Local changes are preserved.'
@@ -452,8 +449,6 @@ export function createCanvasSession(options: CanvasSessionOptions) {
? cause.message
: 'Unable to open this canvas.',
});
- } finally {
- endTrackedDocumentSpan(span);
}
}
const initialization = initialize();
diff --git a/apps/web/src/features/block-canvas/queries/canvas-sync.ts b/apps/web/src/features/block-canvas/queries/canvas-sync.ts
index 2c78823462..bcdd597e34 100644
--- a/apps/web/src/features/block-canvas/queries/canvas-sync.ts
+++ b/apps/web/src/features/block-canvas/queries/canvas-sync.ts
@@ -3,6 +3,7 @@ import {
thrownResultErrorHasCode,
throwOnErr,
} from '@core/util/result';
+import type { Span } from '@macro-inc/observability';
import { queryClient } from '@queries/client';
import { documentLoadKeys } from '@queries/storage/documentLoad/keys';
import { fetchFileDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
@@ -14,7 +15,8 @@ import type { CanvasSessionOptions } from './canvas-session';
export function canvasSyncSource(
documentId: string,
- userId: Accessor<string | undefined>
+ userId: Accessor<string | undefined>,
+ parentSpan?: Span
): Pick<
CanvasSessionOptions,
'exists' | 'initialize' | 'connect' | 'authorize'
@@ -136,7 +138,12 @@ export function canvasSyncSource(
connect: () => {
if (!authorized)
throw new Error('Canvas synchronization requires authorization.');
- return createSyncServiceSource(documentId, token, authorization);
+ return createSyncServiceSource(
+ documentId,
+ token,
+ authorization,
+ parentSpan
+ );
},
};
}
diff --git a/apps/web/src/features/block-canvas/queries/document.ts b/apps/web/src/features/block-canvas/queries/document.ts
index 1ab882401a..16c5328620 100644
--- a/apps/web/src/features/block-canvas/queries/document.ts
+++ b/apps/web/src/features/block-canvas/queries/document.ts
@@ -1,4 +1,5 @@
import { ThrownResultError, throwOnErr } from '@core/util/result';
+import { type Span, Telemetry } from '@macro-inc/observability';
import { waitForDocumentContentReady } from '@queries/storage/document-location';
import { fetchFileDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
@@ -12,29 +13,34 @@ export type CanvasDocumentData = {
/** Resolve authorization and content location before loading a legacy seed. */
export async function loadCanvasDocument(
- documentId: string
+ documentId: string,
+ parentSpan?: Span
): Promise<CanvasDocumentData> {
- const context = await throwOnErr(() =>
- fetchFileDocumentOpenContext(documentId)
- );
- const data = {
- documentMetadata: context.documentMetadata,
- userAccessLevel: context.userAccessLevel,
- };
- const location = await waitForDocumentContentReady({ documentId });
- if (location.content.state === 'ready') {
- if (location.type === 'syncServiceContent')
- return { ...data, shared: true };
- if (location.type === 'presignedUrl' && location.presignedUrl)
- return {
- ...data,
- shared: false,
- file: await throwOnErr(() =>
- fetchBinary(location.presignedUrl, 'blob')
- ),
- };
- }
- throw new ThrownResultError([
- { code: 'INVALID', message: 'Canvas content is not ready' },
- ]);
+ return (parentSpan ?? Telemetry).span('canvas.load', async (span) => {
+ const context = await span.span('canvas.context', () =>
+ throwOnErr(() => fetchFileDocumentOpenContext(documentId))
+ );
+ const data = {
+ documentMetadata: context.documentMetadata,
+ userAccessLevel: context.userAccessLevel,
+ };
+ const location = await span.span('canvas.location', () =>
+ waitForDocumentContentReady({ documentId })
+ );
+ if (location.content.state === 'ready') {
+ if (location.type === 'syncServiceContent')
+ return { ...data, shared: true };
+ if (location.type === 'presignedUrl' && location.presignedUrl)
+ return {
+ ...data,
+ shared: false,
+ file: await span.span('canvas.download', () =>
+ throwOnErr(() => fetchBinary(location.presignedUrl, 'blob'))
+ ),
+ };
+ }
+ throw new ThrownResultError([
+ { code: 'INVALID', message: 'Canvas content is not ready' },
+ ]);
+ });
}
diff --git a/apps/web/src/features/block-channel/component/NewChannelBlockAdapter.tsx b/apps/web/src/features/block-channel/component/NewChannelBlockAdapter.tsx
index 6350f48c0d..5ee45bcdcc 100644
--- a/apps/web/src/features/block-channel/component/NewChannelBlockAdapter.tsx
+++ b/apps/web/src/features/block-channel/component/NewChannelBlockAdapter.tsx
@@ -9,6 +9,7 @@ import {
useBlockEntityCommands,
} from '@app/features/next-soup/actions';
import { createSearchParams } from '@app/lib/split-router';
+import { TraceFlow } from '@app/observability/flow';
import { URL_PARAMS } from '@block-channel/constants';
import { ChannelAttachmentsTab } from '@channel/Attachments/ChannelAttachmentsTab';
import { useChannelBotManagement } from '@channel/Bots/use-channel-bot-management';
@@ -564,31 +565,41 @@ export function NewChannelBlockAdapter(props: BlockChannelProps) {
<Switch>
<Match when={activeTab() === 'messages'}>
<Suspense fallback={<ChannelLoading />}>
- <ChannelMessages
- autofocus={canAutofocusSplitContent && !navigatedFromJK()}
- />
+ <TraceFlow name="channel.messages.view">
+ <ChannelMessages
+ autofocus={canAutofocusSplitContent && !navigatedFromJK()}
+ />
+ </TraceFlow>
</Suspense>
</Match>
<Match when={activeTab() === 'attachments'}>
- <ChannelAttachmentsTab channelId={channelId} />
+ <TraceFlow name="channel.attachments.view">
+ <ChannelAttachmentsTab channelId={channelId} />
+ </TraceFlow>
</Match>
<Match when={activeTab() === 'calls' && ENABLE_CALLS}>
- <ChannelCallsTab channelId={channelId} />
+ <TraceFlow name="channel.calls.view">
+ <ChannelCallsTab channelId={channelId} />
+ </TraceFlow>
</Match>
<Match when={activeTab() === 'participants'}>
- <ChannelParticipantsTab
- channelId={channelId}
- botManagementEnabled={botManagement.enabled()}
- onCreateBot={botManagement.openCreateBot}
- inviteBotFocusRequest={botManagement.inviteFocusRequest()}
- onOpenBot={botManagement.openBot}
- />
+ <TraceFlow name="channel.participants.view">
+ <ChannelParticipantsTab
+ channelId={channelId}
+ botManagementEnabled={botManagement.enabled()}
+ onCreateBot={botManagement.openCreateBot}
+ inviteBotFocusRequest={botManagement.inviteFocusRequest()}
+ onOpenBot={botManagement.openBot}
+ />
+ </TraceFlow>
</Match>
<Match when={activeTab() === 'call' && canUseInlineCallTab()}>
- <ChannelCallTab
- channelId={channelId}
- pendingJoin={pendingJoinCall}
- />
+ <TraceFlow name="channel.call.view">
+ <ChannelCallTab
+ channelId={channelId}
+ pendingJoin={pendingJoinCall}
+ />
+ </TraceFlow>
</Match>
</Switch>
</div>
diff --git a/apps/web/src/features/block-database/component/Block.tsx b/apps/web/src/features/block-database/component/Block.tsx
index 173ceea6b2..8a30f9e005 100644
--- a/apps/web/src/features/block-database/component/Block.tsx
+++ b/apps/web/src/features/block-database/component/Block.tsx
@@ -2,6 +2,7 @@ import { ListSkeleton } from '@app/components/view-shell/ListSkeleton';
import { openChatWithInput } from '@app/features/chat/ChatWithAgentButton';
import { toQuerySchema } from '@app/features/database-query/queries/query-source';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
+import { usePending } from '@app/observability/flow';
import { useGlobalBlockOrchestrator } from '@components/app/GlobalAppState';
import { useSplitLayout } from '@components/app/split-layout/layout';
import {
@@ -91,6 +92,7 @@ const Block: Component = () => {
);
useDatabaseTableChangedSync(() => databaseId);
const detailQuery = useDatabaseDetailQuery(() => databaseId);
+ usePending('database.detail', () => detailQuery.isLoading);
let gridEntry:
| {
tableId: string;
diff --git a/apps/web/src/features/block-database/component/DatabaseGrid.tsx b/apps/web/src/features/block-database/component/DatabaseGrid.tsx
index ef0c38a3bb..08e6ce6369 100644
--- a/apps/web/src/features/block-database/component/DatabaseGrid.tsx
+++ b/apps/web/src/features/block-database/component/DatabaseGrid.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { StaticMarkdownContext } from '@core/component/LexicalMarkdown/component/core/StaticMarkdown';
import { fireAndForget } from '@core/util/fireAndForget';
import { refreshInBackground } from '@queries/database-sql/create-database-sql-query';
@@ -259,6 +260,7 @@ function TableAdapter(props: DatabaseGridProps & { tableId: string }) {
}),
relations
);
+ usePending('database.rows', source.loading);
// Embedded grids have no database BlockContainer to subscribe for them.
// Tracking is reference-counted across grids and full database blocks.
useDatabaseSubscription(databaseId, () => refreshInBackground(source));
diff --git a/apps/web/src/features/block-email/component/Block.tsx b/apps/web/src/features/block-email/component/Block.tsx
index c7f42586f5..ca305b9278 100644
--- a/apps/web/src/features/block-email/component/Block.tsx
+++ b/apps/web/src/features/block-email/component/Block.tsx
@@ -1,6 +1,7 @@
import { displaySubject } from '@app/features/email-compose/core/subject-text';
import { createEmailThreadSource } from '@app/features/email-thread/queries/thread-source';
import { useBlockEntityCommands } from '@app/features/next-soup/actions';
+import { usePending } from '@app/observability/flow';
import { ContentLoading } from '@components/app/ContentLoading';
import { useGlobalNotificationSource } from '@components/app/GlobalAppState';
import { useBlockId } from '@core/block';
@@ -23,6 +24,7 @@ export default function BlockEmail() {
const threadQuery = useThreadQuery(threadId, () => ({
enabled: !!threadId(),
}));
+ usePending('email.thread', () => threadQuery.isLoading);
const source = createEmailThreadSource(threadId, threadQuery);
const threadData = source.thread;
diff --git a/apps/web/src/features/block-form/form-respond-page.tsx b/apps/web/src/features/block-form/form-respond-page.tsx
index 292d0996b5..67729d1539 100644
--- a/apps/web/src/features/block-form/form-respond-page.tsx
+++ b/apps/web/src/features/block-form/form-respond-page.tsx
@@ -6,6 +6,7 @@
* redirect (`withFormRespondShell` in `routes/shells.tsx`). The form itself is the shared
* `RespondView`.
*/
+import { TraceFlow, usePending } from '@app/observability/flow';
import { useUserId } from '@core/context/user';
import { fireAndForget } from '@core/util/fireAndForget';
import Eye from '@icon/system/regular/eye.svg';
@@ -46,6 +47,7 @@ function FormRespondContent(props: { formId: string }) {
openCalendarSettings: () => navigate('/scheduling'),
});
const source = context.createFormSource(() => props.formId);
+ usePending('form.detail', () => !source.detail() && !source.failure());
return (
<FormProvider value={context}>
<Layer depth={1}>
@@ -148,5 +150,17 @@ function FormRespondContent(props: { formId: string }) {
* respond.
*/
export function FormRespondPage(props: { formId: string }) {
- return <FormRespondContent formId={props.formId} />;
+ const [searchParams] = useSearchParams();
+ return (
+ <TraceFlow
+ name="view.form-respond"
+ key={() => `${props.formId}:${searchParams.preview === 'true'}`}
+ attributes={{
+ 'form.id': props.formId,
+ 'form.preview': searchParams.preview === 'true',
+ }}
+ >
+ <FormRespondContent formId={props.formId} />
+ </TraceFlow>
+ );
}
diff --git a/apps/web/src/features/block-form/views/form-page-view.tsx b/apps/web/src/features/block-form/views/form-page-view.tsx
index b7674c6fc5..82bd4e58c6 100644
--- a/apps/web/src/features/block-form/views/form-page-view.tsx
+++ b/apps/web/src/features/block-form/views/form-page-view.tsx
@@ -1,4 +1,9 @@
import { ListSkeleton } from '@app/components/view-shell/ListSkeleton';
+import {
+ beginInteraction,
+ TraceFlow,
+ usePending,
+} from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import { Button } from '@ui';
import {
@@ -141,6 +146,20 @@ function EditorPanels(
const context = useFormContext();
const collaboration = context.createLayoutCollaboration(props.detail.form.id);
props.preview.trackLayout(collaboration.flush);
+ usePending('form.layout', () => collaboration.status().kind === 'loading');
+ const changeTab = (tab: FormTab) => {
+ if (tab === props.tab) return;
+ const interaction = beginInteraction('form.tab', {
+ attributes: { 'form.tab': tab },
+ closeOnJoin: true,
+ });
+ try {
+ props.onTabChange(tab);
+ } finally {
+ // Tabs commit inside an event batch; let that flush join its new panel.
+ queueMicrotask(interaction.end);
+ }
+ };
// Authoring state and pending writes belong to the editor, across tab changes.
const builder = (
<BuilderView
@@ -168,7 +187,7 @@ function EditorPanels(
detail={props.detail}
idPrefix={props.tabsId}
tab={props.tab}
- onTabChange={props.onTabChange}
+ onTabChange={changeTab}
/>
<div
id={`${props.tabsId}-panel-${props.tab}`}
@@ -177,11 +196,17 @@ function EditorPanels(
class="min-h-0 flex-1"
>
<Switch>
- <Match when={props.tab === 'build'}>{builder}</Match>
+ <Match when={props.tab === 'build'}>
+ <TraceFlow name="form.build">{builder}</TraceFlow>
+ </Match>
<Match when={props.tab === 'responses'}>
- <ResponsesView detail={props.detail} />
+ <TraceFlow name="form.responses">
+ <ResponsesView detail={props.detail} />
+ </TraceFlow>
+ </Match>
+ <Match when={props.tab === 'share'}>
+ <TraceFlow name="form.settings">{sharing}</TraceFlow>
</Match>
- <Match when={props.tab === 'share'}>{sharing}</Match>
</Switch>
</div>
</>
@@ -189,6 +214,10 @@ function EditorPanels(
}
export function FormPageView(props: FormPageProps) {
+ usePending(
+ 'form.detail',
+ () => !props.source.detail() && !props.source.failure()
+ );
let respondScroll: HTMLDivElement | undefined;
// One per mount: the same form can be open in two splits.
const tabsId = createUniqueId();
diff --git a/apps/web/src/features/block-form/views/respond-view.test.tsx b/apps/web/src/features/block-form/views/respond-view.test.tsx
index f1b22c22aa..989dbfd9d8 100644
--- a/apps/web/src/features/block-form/views/respond-view.test.tsx
+++ b/apps/web/src/features/block-form/views/respond-view.test.tsx
@@ -1,3 +1,4 @@
+import * as uiOperations from '@app/observability/ui-operation';
import {
cleanup,
fireEvent,
@@ -6,14 +7,17 @@ import {
waitFor,
within,
} from '@solidjs/testing-library';
-import { errAsync } from 'neverthrow';
-import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { errAsync, ResultAsync } from 'neverthrow';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
import { FormProvider } from '../context/form-context';
import type { FormDetail } from '../core/form-model';
import { createMockFormContext } from '../tests/mock-context';
import { RespondView } from './respond-view';
-afterEach(cleanup);
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
// jsdom has no layout, so no scrolling into view.
beforeAll(() => {
@@ -132,6 +136,55 @@ function offsite(): FormDetail {
}
describe('RespondView', () => {
+ it('cancels only the retired view measurement while a pending submission still saves', async () => {
+ const detail = offsite();
+ detail.layout.sections = detail.layout.sections.slice(-1);
+ const { context, calls } = createMockFormContext({ detail });
+ let release!: () => void;
+ const pending = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ const submit = context.responses.submit;
+ context.responses.submit = (id, answers) =>
+ ResultAsync.fromSafePromise(pending).andThen(() => submit(id, answers));
+ const stopTelemetry = uiOperations.initializeUiOperationTelemetry();
+ const start = vi.spyOn(uiOperations, 'startUiOperation');
+ const scroll = vi.spyOn(Element.prototype, 'scrollIntoView');
+ const view = render(() => (
+ <FormProvider value={context}>
+ <RespondView
+ detail={detail}
+ compact={false}
+ refetch={async () => true}
+ />
+ </FormProvider>
+ ));
+ fireEvent.input(screen.getByLabelText('Dietary needs'), {
+ target: { value: 'Synthetic pending answer' },
+ });
+ fireEvent.click(screen.getByRole('button', { name: /Submit/ }));
+ const operation = start.mock.results[0].value;
+ const paint = vi.spyOn(operation, 'afterPaint');
+ expect(operation.ended).toBe(false);
+ try {
+ view.unmount();
+ expect(operation.ended).toBe(true);
+ release();
+ await waitFor(() => expect(calls.submitted).toHaveLength(1));
+ expect(calls.submitted[0]).toEqual([
+ {
+ question: 'q-diet',
+ value: { type: 'text', value: 'Synthetic pending answer' },
+ },
+ ]);
+ expect(paint).not.toHaveBeenCalled();
+ expect(scroll).not.toHaveBeenCalled();
+ } finally {
+ release();
+ stopTelemetry();
+ }
+ });
+
it('shows the owner’s logo, cover and accent, and Macro’s look when none is set', () => {
const plain = offsite();
const branded = offsite();
diff --git a/apps/web/src/features/block-form/views/respond-view.tsx b/apps/web/src/features/block-form/views/respond-view.tsx
index 0fa29e0975..d5b59abb72 100644
--- a/apps/web/src/features/block-form/views/respond-view.tsx
+++ b/apps/web/src/features/block-form/views/respond-view.tsx
@@ -1,4 +1,9 @@
import { ListSkeleton } from '@app/components/view-shell/ListSkeleton';
+import { usePending } from '@app/observability/flow';
+import {
+ startUiOperation,
+ type UiOperation,
+} from '@app/observability/ui-operation';
import { fireAndForget } from '@core/util/fireAndForget';
import ArrowLeft from '@icon/system/regular/arrow-left.svg';
import ArrowRight from '@icon/system/regular/arrow-right.svg';
@@ -75,7 +80,15 @@ export function RespondView(props: {
context.responses.editMine(props.detail.form.id, answers),
now: () => new Date(),
});
+ usePending('form.response', () => respond.view().kind === 'loading');
let root: HTMLDivElement | undefined;
+ let submission: UiOperation | undefined;
+ let disposed = false;
+ onCleanup(() => {
+ disposed = true;
+ submission?.cancel();
+ submission = undefined;
+ });
const form = () => props.detail.form;
// An inline card stays in Macro's look; the page wears the owner's.
@@ -100,6 +113,7 @@ export function RespondView(props: {
function revealTop() {
queueMicrotask(() => {
+ if (disposed) return;
const container = props.scrollContainer?.();
if (container) container.scrollTo({ top: 0, behavior: 'smooth' });
else root?.scrollIntoView({ block: 'start', behavior: 'smooth' });
@@ -109,6 +123,7 @@ export function RespondView(props: {
/** Bring the first refused question into view and focus it. */
function revealProblem() {
queueMicrotask(() => {
+ if (disposed) return;
const first = Object.keys(respond.problems())[0];
if (!first) return;
const field = document.getElementById(fieldId(scope, first));
@@ -117,10 +132,30 @@ export function RespondView(props: {
});
}
- async function submitAndReveal() {
- await respond.submit();
- revealProblem();
- if (respond.view().kind !== 'answering') revealTop();
+ async function submitAndReveal(event: Event) {
+ submission?.cancel();
+ const operation = startUiOperation('form.submit', {
+ event,
+ onFinish: () => {
+ if (submission === operation) submission = undefined;
+ },
+ attributes: {
+ 'form.id': props.detail.form.id,
+ 'form.preview': !!props.preview,
+ },
+ });
+ submission = operation;
+ try {
+ await operation.run(() => respond.submit());
+ if (disposed) return;
+ revealProblem();
+ if (respond.view().kind !== 'answering') revealTop();
+ if (respond.failure()) operation.finish('error');
+ else operation.afterPaint();
+ } catch (error) {
+ operation.finish('error');
+ throw error;
+ }
}
/** From the update notice: read the form again, then back to the answers. */
@@ -439,7 +474,7 @@ export function RespondView(props: {
onSubmit={(event) => {
event.preventDefault();
if (answering().isLast) {
- fireAndForget(submitAndReveal(), 'form-respond');
+ fireAndForget(submitAndReveal(event), 'form-respond');
return;
}
if (respond.next()) revealTop();
diff --git a/apps/web/src/features/block-form/views/responses-view.tsx b/apps/web/src/features/block-form/views/responses-view.tsx
index 9551aa5989..5585a810f5 100644
--- a/apps/web/src/features/block-form/views/responses-view.tsx
+++ b/apps/web/src/features/block-form/views/responses-view.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { Show } from 'solid-js';
import { StatTiles } from '../components/responses/stat-tiles';
import { useFormContext } from '../context/form-context';
@@ -22,6 +23,10 @@ export function ResponsesView(props: { detail: FormDetail }) {
() => props.detail.form.ownerId,
() => props.detail.access === 'owner'
);
+ usePending(
+ 'form.responses.summary',
+ () => summary.value() === undefined && !summary.failure()
+ );
// Sharing is owner-only, so only the owner learns the channels' reach.
const reach = (): ChannelReach => {
if (props.detail.access !== 'owner') return 'none';
diff --git a/apps/web/src/features/block-md/component/MarkdownCollabProvider.tsx b/apps/web/src/features/block-md/component/MarkdownCollabProvider.tsx
index 64653fa0cb..4c3a672ef1 100644
--- a/apps/web/src/features/block-md/component/MarkdownCollabProvider.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownCollabProvider.tsx
@@ -1,3 +1,4 @@
+import { useFlow } from '@app/observability/flow';
import { CollabProvider } from '@core/component/LexicalMarkdown/collaboration/CollabProvider';
import type { MarkdownEditorErrors } from '@core/component/LexicalMarkdown/constants';
import type { PluginManager } from '@core/component/LexicalMarkdown/plugins';
@@ -6,7 +7,6 @@ import type { NodeIdMappings } from '@macro-inc/lexical-core';
import type { LexicalEditor } from 'lexical';
import type { Accessor, Setter } from 'solid-js';
import { useMarkdownDocument } from '../context/markdown-document-context';
-import { endDocumentSpan, resumeDocumentSpan } from '../observability';
// The sync tags and force-sync command live with the generic provider now;
// re-exported here so existing md-block imports keep working.
@@ -34,6 +34,7 @@ export type MarkdownCollabProviderProps = {
* the block's document tracing spans, with the CollabStatus chrome.
*/
export function MarkdownCollabProvider(props: MarkdownCollabProviderProps) {
+ const flow = useFlow();
const { documentSource, permissions, state } = useMarkdownDocument();
const syncSource = () => {
const source = documentSource();
@@ -56,10 +57,7 @@ export function MarkdownCollabProvider(props: MarkdownCollabProviderProps) {
canEdit={permissions.canEdit}
canComment={permissions.canComment}
editorError={state.editor.error}
- observability={{
- resumeSpan: resumeDocumentSpan,
- endSpan: endDocumentSpan,
- }}
+ span={flow.span}
/>
);
}
diff --git a/apps/web/src/features/block-md/component/MarkdownDocument.tsx b/apps/web/src/features/block-md/component/MarkdownDocument.tsx
index 1a4372ec78..aad182c4bd 100644
--- a/apps/web/src/features/block-md/component/MarkdownDocument.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownDocument.tsx
@@ -1,3 +1,4 @@
+import { TraceFlow, useFlow } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import {
createLoroManager,
@@ -38,7 +39,7 @@ import {
} from '../context/markdown-document-state';
import { HistoryProvider } from '../history/HistoryContext';
import { HistoryWorkspace } from '../history/HistoryWorkspace';
-import { resumeDocumentSpan, stampLoroSnapshotState } from '../observability';
+import { stampLoroSnapshotState } from '../observability';
import type { MarkdownDocumentKind, MarkdownDocumentSource } from '../types';
import { MarkdownNameProvider } from './MarkdownNameProvider';
import { Notebook } from './Notebook';
@@ -242,6 +243,7 @@ function useMarkdownSnapshotIngest(
) {
const { documentId: getDocumentId } = useMarkdownDocument();
const documentId = getDocumentId();
+ const flow = useFlow();
const snapshotStore = new IDBSnapshotStore<RawUpdate>(
LORO_SNAPSHOT_DB_NAME,
documentId
@@ -255,7 +257,7 @@ function useMarkdownSnapshotIngest(
if (!doInitialSync) return;
options.onDataReady?.();
- const span = resumeDocumentSpan(documentId);
+ const span = flow.span;
if (options.optimisticSnapshot) {
startSnapshotIngest(span, 'optimistic', loroManager, async () => {
const seeded = await loroManager.ingest({
@@ -296,6 +298,7 @@ export function MarkdownDocumentContent(props: MarkdownDocumentContentProps) {
const loroManager = createLoroManager(MARKDOWN_LORO_SCHEMA, {
documentId,
+ parentSpan: useFlow().span,
});
useMarkdownSnapshotIngest(loroManager, props);
@@ -312,12 +315,14 @@ export function MarkdownDocumentContent(props: MarkdownDocumentContentProps) {
>
<div class="relative portal-scope touch:pt-(--mobile-content-inset-top) touch:pb-(--mobile-content-inset-bottom)">
<Suspense>
- <Notebook
- loroManager={loroManager}
- documentId={documentId}
- hotkeyScope={props.hotkeyScope}
- autoFocus={props.autoFocus ?? false}
- />
+ <TraceFlow name="doc.editor">
+ <Notebook
+ loroManager={loroManager}
+ documentId={documentId}
+ hotkeyScope={props.hotkeyScope}
+ autoFocus={props.autoFocus ?? false}
+ />
+ </TraceFlow>
</Suspense>
</div>
</Scroll>
diff --git a/apps/web/src/features/block-md/component/MarkdownEditor.tsx b/apps/web/src/features/block-md/component/MarkdownEditor.tsx
index c5de83575e..b74d7c1e8b 100644
--- a/apps/web/src/features/block-md/component/MarkdownEditor.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownEditor.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { activeElement } from '@app/signal/focus';
import { MessageCommentsProvider } from '@block-md/comments/MessageCommentsProvider';
import { URL_PARAMS } from '@block-md/constants';
@@ -231,6 +232,7 @@ export function MarkdownEditor(props: {
];
const [editorReady, setEditorReady] = createSignal<boolean>(false);
+ usePending('doc.editor.initialize', () => !editorReady() && !editorError());
const [highlightLayerRef, setHighlightLayerRef] =
createSignal<HTMLDivElement>();
diff --git a/apps/web/src/features/block-md/component/MarkdownPopup.tsx b/apps/web/src/features/block-md/component/MarkdownPopup.tsx
index e8c8369632..47288a96f1 100644
--- a/apps/web/src/features/block-md/component/MarkdownPopup.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownPopup.tsx
@@ -1,4 +1,5 @@
import { useFeatureFlag } from '@app/lib/analytics/posthog';
+import { useFlow } from '@app/observability/flow';
import { globalSplitManager } from '@app/signal/splitLayout';
import { applyAiOps } from '@block-md/ai-edit/applyAiOps';
import { MobileDrawer } from '@components/app/mobile/MobileDrawer';
@@ -112,6 +113,7 @@ export function MarkdownPopup(props: {
highlightLayerRef: HTMLDivElement;
lexicalMapping: NodeIdMappings;
}) {
+ const flow = useFlow();
const { documentId, permissions, state, persistedName, fallbackName } =
useMarkdownDocument();
const { canEdit, canComment } = permissions;
@@ -369,17 +371,20 @@ export function MarkdownPopup(props: {
// Fast mode: one model edits the whole document directly, no supervisor.
// Apply ops locally so the edit lands in this client's undo stack.
fireAndForget(
- requestAiEditWithToast(
- {
- documentId: blockId,
- prompt: `Request: ${instruction}\nUser is selecting nodes ${nodeIds.join(' ')}. Proceed with requested edit`,
- mode: 'fast',
- onOps: (ops) => applyAiOps(editor, props.lexicalMapping, ops),
- },
- () => {
- setAiEditLocation(null);
- setAiEditRunning(false);
- }
+ flow.span.span('doc.edit', (parentSpan) =>
+ requestAiEditWithToast(
+ {
+ documentId: blockId,
+ parentSpan,
+ prompt: `Request: ${instruction}\nUser is selecting nodes ${nodeIds.join(' ')}. Proceed with requested edit`,
+ mode: 'fast',
+ onOps: (ops) => applyAiOps(editor, props.lexicalMapping, ops),
+ },
+ () => {
+ setAiEditLocation(null);
+ setAiEditRunning(false);
+ }
+ )
),
'markdown-ai-edit'
);
diff --git a/apps/web/src/features/block-md/definition.ts b/apps/web/src/features/block-md/definition.ts
index 76772f9952..a68d0cb407 100644
--- a/apps/web/src/features/block-md/definition.ts
+++ b/apps/web/src/features/block-md/definition.ts
@@ -1,16 +1,11 @@
import { defineBlock, type ExtractLoadType, LoadErrors } from '@core/block';
import { ENABLE_MARKDOWN_LIVE_COLLABORATION } from '@core/constant/featureFlags';
+import { NOOP_SPAN } from '@macro-inc/observability';
import { fetchSyncDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
import { makeFileFromBlob } from '@service-storage/util/makeFileFromBlob';
import { createSyncServiceSource } from '@service-sync/source';
import { err, ok } from 'neverthrow';
import { lazy } from 'solid-js';
-import {
- endDocumentSpan,
- registerDocumentSpan,
- resumeDocumentSpan,
- startDocumentSpan,
-} from './observability';
export const definition = defineBlock({
name: 'md',
@@ -25,7 +20,7 @@ export const definition = defineBlock({
accepted: {
md: 'text/markdown',
},
- async load(source, intent) {
+ async load(source, intent, parentSpan = NOOP_SPAN) {
if (source.type === 'sync-service') {
const documentId = source.id;
if (intent === 'preload') {
@@ -35,21 +30,12 @@ export const definition = defineBlock({
});
}
- let rootSpan = resumeDocumentSpan(documentId);
- if (!rootSpan) {
- rootSpan = startDocumentSpan('doc.open');
- rootSpan.setAttr('doc.type', 'md');
- rootSpan.setAttr('document.id', documentId);
- registerDocumentSpan(documentId, rootSpan);
- }
- return rootSpan.span('doc.load', async (loadSpan) => {
+ return parentSpan.span('doc.load', async (loadSpan) => {
const context = await loadSpan.span('doc.load.context', () =>
fetchSyncDocumentOpenContext(documentId)
);
if (context.isErr()) {
loadSpan.error('load context failed');
- rootSpan.error('load context failed');
- endDocumentSpan(documentId);
return err(context.error);
}
const { token, authorization, documentMetadata, userAccessLevel } =
@@ -59,7 +45,8 @@ export const definition = defineBlock({
const { source: syncSource, doInitialSync } = createSyncServiceSource(
source.id,
token,
- authorization
+ authorization,
+ parentSpan
);
// HACK: unfortunately, most blocks still rely on a dssFile for things like
diff --git a/apps/web/src/features/block-md/observability.ts b/apps/web/src/features/block-md/observability.ts
index 21412f4696..9b14bef3df 100644
--- a/apps/web/src/features/block-md/observability.ts
+++ b/apps/web/src/features/block-md/observability.ts
@@ -1,36 +1,6 @@
-import { type Span, Telemetry } from '@macro-inc/observability';
+import type { Span } from '@macro-inc/observability';
import type { LoroDoc } from 'loro-crdt';
-const documentSpans = new Map<string, Span>();
-
-export function startDocumentSpan(name: string): Span {
- return Telemetry.span(name);
-}
-
-export function registerDocumentSpan(documentId: string, span: Span): void {
- const previous = documentSpans.get(documentId);
- if (previous !== span) previous?.end();
- documentSpans.set(documentId, span);
-}
-
-export function resumeDocumentSpan(documentId: string): Span | undefined {
- return documentSpans.get(documentId);
-}
-
-export function endDocumentSpan(documentId: string): void {
- const span = documentSpans.get(documentId);
- if (!span) return;
- documentSpans.delete(documentId);
- span.end();
-}
-
-export function endTrackedDocumentSpan(span: Span): void {
- for (const [documentId, candidate] of documentSpans) {
- if (candidate === span) documentSpans.delete(documentId);
- }
- span.end();
-}
-
export function stampLoroSnapshotState(span: Span, doc: LoroDoc): void {
const version = doc.oplogVersion();
diff --git a/apps/web/src/features/block-md/queries/markdown-document.ts b/apps/web/src/features/block-md/queries/markdown-document.ts
index 3e840c4efb..be4c04fb7f 100644
--- a/apps/web/src/features/block-md/queries/markdown-document.ts
+++ b/apps/web/src/features/block-md/queries/markdown-document.ts
@@ -1,4 +1,5 @@
import { throwOnErr } from '@core/util/result';
+import { NOOP_SPAN, type Span } from '@macro-inc/observability';
import { fetchSyncDocumentOpenContext } from '@queries/storage/documentLoad/sync-document-context';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
@@ -18,41 +19,47 @@ export type MarkdownDocumentData = ReturnType<
};
export async function loadMarkdownDocument(
- documentId: string
+ documentId: string,
+ parentSpan: Span = NOOP_SPAN
): Promise<MarkdownDocumentData> {
- const { documentMetadata, token, authorization, userAccessLevel } =
- await throwOnErr(() => fetchSyncDocumentOpenContext(documentId));
- const permissions = match(userAccessLevel)
- .with('owner', () => ({
- canComment: true,
- canEdit: true,
- isOwner: true,
- }))
- .with('edit', () => ({
- canComment: true,
- canEdit: true,
- isOwner: false,
- }))
- .with('comment', () => ({
- canComment: true,
- canEdit: false,
- isOwner: false,
- }))
- .with('view', () => ({
- canComment: false,
- canEdit: false,
- isOwner: false,
- }))
- .exhaustive(() => ({
- canComment: false,
- canEdit: false,
- isOwner: false,
- }));
+ return parentSpan.span('doc.load', async (loadSpan) => {
+ const context = await loadSpan.span('doc.load.context', () =>
+ throwOnErr(() => fetchSyncDocumentOpenContext(documentId))
+ );
+ const { documentMetadata, token, authorization, userAccessLevel } = context;
+ loadSpan.setAttr('doc.context.cached', context.fromCache);
+ const permissions = match(userAccessLevel)
+ .with('owner', () => ({
+ canComment: true,
+ canEdit: true,
+ isOwner: true,
+ }))
+ .with('edit', () => ({
+ canComment: true,
+ canEdit: true,
+ isOwner: false,
+ }))
+ .with('comment', () => ({
+ canComment: true,
+ canEdit: false,
+ isOwner: false,
+ }))
+ .with('view', () => ({
+ canComment: false,
+ canEdit: false,
+ isOwner: false,
+ }))
+ .exhaustive(() => ({
+ canComment: false,
+ canEdit: false,
+ isOwner: false,
+ }));
- return {
- ...createSyncServiceSource(documentId, token, authorization),
- metadata: documentMetadata,
- userAccessLevel,
- permissions,
- };
+ return {
+ ...createSyncServiceSource(documentId, token, authorization, parentSpan),
+ metadata: documentMetadata,
+ userAccessLevel,
+ permissions,
+ };
+ });
}
diff --git a/apps/web/src/features/calendar-view/calendar-view.tsx b/apps/web/src/features/calendar-view/calendar-view.tsx
index 4d5c5a2591..a01bd02a0a 100644
--- a/apps/web/src/features/calendar-view/calendar-view.tsx
+++ b/apps/web/src/features/calendar-view/calendar-view.tsx
@@ -9,6 +9,7 @@ import {
useNavigate,
useParams,
} from '@app/lib/split-router';
+import { usePending } from '@app/observability/flow';
import { useGlobalNotificationSource } from '@components/app/GlobalAppState';
import { useSplitPanelOrThrow } from '@components/app/split-layout/layoutUtils';
import { useUserId } from '@core/context/user';
@@ -180,6 +181,7 @@ export function CalendarView(props: CalendarViewProps) {
};
}
);
+ usePending('calendar.target', () => occurrencesQuery.isLoading);
const focusTarget = createCalendarFocusTarget(
targetRequest,
occurrencesQuery
diff --git a/apps/web/src/features/calendar/components/CalendarViewContext.tsx b/apps/web/src/features/calendar/components/CalendarViewContext.tsx
index 99571347d7..9688a435c9 100644
--- a/apps/web/src/features/calendar/components/CalendarViewContext.tsx
+++ b/apps/web/src/features/calendar/components/CalendarViewContext.tsx
@@ -1,4 +1,5 @@
import { useCalendarFocus } from '@app/features/calendar-view/calendar-focus-target';
+import { beginInteraction } from '@app/observability/flow';
import { createAssertedContextProvider } from '@core/context/createContext';
import { subscribeToTeamCalendarReset } from '@queries/calendar/team-cache';
import {
@@ -97,8 +98,16 @@ export const [CalendarViewContextProvider, useCalendarView] =
const calendarFocus = useCalendarFocus();
// A selection made while a row waits for its chip wins over that row.
const selectEvent: typeof selection.select = (...args) => {
- calendarFocus.cancelOccurrence();
- selection.select(...args);
+ // Ends one paint after the details open; a flow they mount joins it.
+ const interaction = beginInteraction('calendar.event.open', {
+ attributes: { 'calendar.event.origin': args[2] ?? 'grid' },
+ });
+ try {
+ calendarFocus.cancelOccurrence();
+ selection.select(...args);
+ } finally {
+ interaction.end();
+ }
};
// A revoked OOO agenda entry can lie outside every mounted viewport.
// Close detached selections synchronously when authorization resets data.
diff --git a/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts b/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts
index c97db72da9..a864c8ea27 100644
--- a/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts
+++ b/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { useUserId } from '@core/context/user';
import {
type CalendarOccurrenceQueryRange,
@@ -83,6 +84,13 @@ export function useCalendarOccurrenceData(
occurrencesQuery.isSuccess &&
occurrencesQuery.data?.syncStatus === CalendarSyncStatus.syncing;
+ usePending(
+ 'calendar.occurrences',
+ () =>
+ isRangeSupported() &&
+ (occurrencesQuery.isLoading ||
+ (occurrencesQuery.isSuccess && options.sourcesReady?.() === false))
+ );
return {
range: options.range,
occurrencesQuery,
diff --git a/apps/web/src/features/channel/Channel/Channel.tsx b/apps/web/src/features/channel/Channel/Channel.tsx
index 94869fdbf9..1976f43e4b 100644
--- a/apps/web/src/features/channel/Channel/Channel.tsx
+++ b/apps/web/src/features/channel/Channel/Channel.tsx
@@ -5,6 +5,8 @@ import {
import { AgentConversationsProvider } from '@app/features/agent-conversations/agent-conversations-provider';
import { AgentDmComposer } from '@app/features/agent-dms/agent-dm-composer';
import { openChatWithInput } from '@app/features/chat/ChatWithAgentButton';
+import { usePending } from '@app/observability/flow';
+import { startUiOperation } from '@app/observability/ui-operation';
import { createActivityTracker } from '@channel/activity-tracker';
import { useStartChannelCall } from '@channel/Call/use-start-channel-call';
import { DebugSuspense } from '@channel/DebugSuspense';
@@ -233,6 +235,7 @@ export function Channel(props: ChannelProps) {
() => ({ type: 'channel', id: (() => props.channelId)() }),
targetMessageController.loadAroundMessageId
);
+ usePending('channel.messages', () => messagesQuery.isLoading);
const isTargetMessageMissing = () =>
targetMessageController.loadAroundMessageId() !== undefined &&
isMissingMessageError(messagesQuery.error);
@@ -685,19 +688,26 @@ export function Channel(props: ChannelProps) {
});
const optimisticId = newMessageId();
+ // Send to the optimistic message's paint; channel.send follows delivery.
+ const sendUi = startUiOperation('message.send', {
+ attributes: { 'channel.id': channelId, 'message.id': optimisticId },
+ });
fireAndForget(
Telemetry.span('channel.send', async (span) => {
span.setAttr('message.id', optimisticId);
span.setAttr('channel.id', channelId);
try {
await sendMessageMutation.mutateAsync({
+ parentSpan: span,
parent: { type: 'channel', id: channelId },
senderId,
optimisticId,
+ onOptimisticInsert: sendUi.afterPaint,
...payload,
});
span.setAttr('composer.outcome', 'succeeded');
} catch {
+ sendUi.finish('error');
span.error('Channel send failed');
const handle = channelInputHandle();
if (
diff --git a/apps/web/src/features/channel/Channel/ChannelDetail.tsx b/apps/web/src/features/channel/Channel/ChannelDetail.tsx
index b884d70b2a..3a7e1db464 100644
--- a/apps/web/src/features/channel/Channel/ChannelDetail.tsx
+++ b/apps/web/src/features/channel/Channel/ChannelDetail.tsx
@@ -9,6 +9,7 @@ import {
import { ViewShell } from '@app/components/view-shell';
import { ChatWithAgentButton } from '@app/features/chat/ChatWithAgentButton';
import { useAnalytics } from '@app/lib/analytics/analytics-context';
+import { TraceFlow } from '@app/observability/flow';
import { ChannelAttachmentsTab } from '@channel/Attachments/ChannelAttachmentsTab';
import { useChannelBotManagement } from '@channel/Bots/use-channel-bot-management';
import { useCallContextOptional } from '@channel/Call/CallContext';
@@ -430,36 +431,46 @@ function ChannelDetailContent(props: ChannelDetailProps) {
name="ChannelDetail.messages"
fallback={<ChannelLoading />}
>
- <ChannelMessages autofocus={props.autofocus ?? false} />
+ <TraceFlow name="channel.messages.view">
+ <ChannelMessages autofocus={props.autofocus ?? false} />
+ </TraceFlow>
</DebugSuspense>
</Match>
<Match when={activeTab() === 'attachments'}>
<DebugSuspense name="ChannelDetail.attachments">
- <ChannelAttachmentsTab channelId={channelId} />
+ <TraceFlow name="channel.attachments.view">
+ <ChannelAttachmentsTab channelId={channelId} />
+ </TraceFlow>
</DebugSuspense>
</Match>
<Match when={activeTab() === 'calls' && ENABLE_CALLS}>
<DebugSuspense name="ChannelDetail.calls">
- <ChannelCallsTab channelId={channelId} />
+ <TraceFlow name="channel.calls.view">
+ <ChannelCallsTab channelId={channelId} />
+ </TraceFlow>
</DebugSuspense>
</Match>
<Match when={activeTab() === 'participants'}>
<DebugSuspense name="ChannelDetail.participants">
- <ChannelParticipantsTab
- channelId={channelId}
- botManagementEnabled={botManagement.enabled()}
- onCreateBot={botManagement.openCreateBot}
- inviteBotFocusRequest={botManagement.inviteFocusRequest()}
- onOpenBot={botManagement.openBot}
- />
+ <TraceFlow name="channel.participants.view">
+ <ChannelParticipantsTab
+ channelId={channelId}
+ botManagementEnabled={botManagement.enabled()}
+ onCreateBot={botManagement.openCreateBot}
+ inviteBotFocusRequest={botManagement.inviteFocusRequest()}
+ onOpenBot={botManagement.openBot}
+ />
+ </TraceFlow>
</DebugSuspense>
</Match>
<Match when={activeTab() === 'call' && canUseInlineCallTab()}>
<DebugSuspense name="ChannelDetail.call">
- <ChannelCallTab
- channelId={channelId}
- pendingJoin={pendingJoinCall}
- />
+ <TraceFlow name="channel.call.view">
+ <ChannelCallTab
+ channelId={channelId}
+ pendingJoin={pendingJoinCall}
+ />
+ </TraceFlow>
</DebugSuspense>
</Match>
</Switch>
diff --git a/apps/web/src/features/channel/Channel/ChannelTabContext.tsx b/apps/web/src/features/channel/Channel/ChannelTabContext.tsx
index e633437f5a..9e7b5e8f70 100644
--- a/apps/web/src/features/channel/Channel/ChannelTabContext.tsx
+++ b/apps/web/src/features/channel/Channel/ChannelTabContext.tsx
@@ -1,3 +1,4 @@
+import { beginInteraction } from '@app/observability/flow';
import {
type Accessor,
createContext,
@@ -19,9 +20,22 @@ export function ChannelTabProvider(
setActiveTab: (tab: ChannelTabId) => void;
}>
) {
+ const changeTab = (tab: ChannelTabId) => {
+ if (tab === props.activeTab()) return;
+ const interaction = beginInteraction('channel.tab', {
+ attributes: { 'channel.tab': tab },
+ closeOnJoin: true,
+ });
+ try {
+ props.setActiveTab(tab);
+ } finally {
+ // Tab controls commit their selected panel at the end of the event batch.
+ queueMicrotask(interaction.end);
+ }
+ };
return (
<ChannelTabContext.Provider
- value={{ activeTab: props.activeTab, setActiveTab: props.setActiveTab }}
+ value={{ activeTab: props.activeTab, setActiveTab: changeTab }}
>
{props.children}
</ChannelTabContext.Provider>
diff --git a/apps/web/src/features/channels-view/channels-view.tsx b/apps/web/src/features/channels-view/channels-view.tsx
index 8b1e5426b3..a300bfb5e1 100644
--- a/apps/web/src/features/channels-view/channels-view.tsx
+++ b/apps/web/src/features/channels-view/channels-view.tsx
@@ -5,6 +5,7 @@ import { MaybeSoupEntityActionDrawerManager } from '@app/features/soup';
import { withEntityNotifications } from '@app/features/soup/entity-notifications';
import { ViewTour } from '@app/features/tours/ViewTour';
import { SplitRouter } from '@app/lib/split-router';
+import { usePending } from '@app/observability/flow';
import { ChannelLoading } from '@channel/Channel/ChannelLoading';
import { useChannelByIdQuery } from '@channel/Channel/channel-entity';
import { DebugSuspense } from '@channel/DebugSuspense';
@@ -341,6 +342,10 @@ function ChannelDetailRouteContent() {
notificationSource
);
});
+ usePending(
+ 'channel.detail',
+ () => channelId() !== undefined && detail.view().status === 'loading'
+ );
const unavailable = () => detail.view().status === 'unavailable';
const retry = async () => {
try {
diff --git a/apps/web/src/features/channels-view/components/rail/ChannelFavoriteRows.test.tsx b/apps/web/src/features/channels-view/components/rail/ChannelFavoriteRows.test.tsx
index 346f9496d9..c059d2a8ab 100644
--- a/apps/web/src/features/channels-view/components/rail/ChannelFavoriteRows.test.tsx
+++ b/apps/web/src/features/channels-view/components/rail/ChannelFavoriteRows.test.tsx
@@ -70,7 +70,8 @@ vi.mock('@queries/favorites/favorites', () => ({
useReorderFavoritesMutation: () => ({ mutateAsync: drag.reorder }),
}));
vi.mock('@core/context/user', () => ({ useUserId: () => () => drag.viewer() }));
-vi.mock('@macro-inc/observability', () => ({
+vi.mock('@macro-inc/observability', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@macro-inc/observability')>()),
Telemetry: {
span: async (
_name: string,
diff --git a/apps/web/src/features/command/CommandMenu.tsx b/apps/web/src/features/command/CommandMenu.tsx
index 047435371f..4a2239390c 100644
--- a/apps/web/src/features/command/CommandMenu.tsx
+++ b/apps/web/src/features/command/CommandMenu.tsx
@@ -3,6 +3,11 @@ import { useCrmContactDiscovery } from '@app/features/crm/record-adapter';
import { useAnalytics } from '@app/lib/analytics/analytics-context';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
import { t } from '@app/lib/i18n';
+import {
+ beginInteraction,
+ TraceFlow,
+ usePending,
+} from '@app/observability/flow';
import { globalSplitManager } from '@app/signal/splitLayout';
import { useSplitLayout } from '@components/app/split-layout/layout';
import {
@@ -187,13 +192,19 @@ export function CommandMenu() {
}}
open={CommandState.isOpen()}
>
- <CommandMenuInner
- depth={2}
- onSelect={handleSelect}
- onHint={() => {
- suppressCloseAutoFocus = true;
- }}
- />
+ <TraceFlow
+ name="quick_access.results"
+ key={CommandState.query}
+ attributes={{ 'search.query_length': CommandState.query().length }}
+ >
+ <CommandMenuInner
+ depth={2}
+ onSelect={handleSelect}
+ onHint={() => {
+ suppressCloseAutoFocus = true;
+ }}
+ />
+ </TraceFlow>
</Dialog>
);
}
@@ -462,6 +473,26 @@ function CommandSearchMenu(
const pagination = defaultCommandItems?.pagination;
const isLoadingEntities = () =>
defaultCommandItems?.isLoadingEntities() ?? false;
+ const isSettling = () => defaultCommandItems?.isSettling() ?? false;
+ usePending('quick_access.sources', isSettling);
+ usePending('quick_access.debounce', () => query() !== CommandState.query());
+ const trackInput = (
+ event: InputEvent & { currentTarget: HTMLTextAreaElement }
+ ) => {
+ const interaction = beginInteraction('quick_access.input', {
+ event,
+ attributes: { 'search.query_length': event.currentTarget.value.length },
+ onFinish: (span) =>
+ span.setAttr('search.result_count', filteredItems().length),
+ });
+ try {
+ interaction.span.run(() =>
+ props.onQueryInput(event.currentTarget, event.isComposing)
+ );
+ } finally {
+ interaction.end();
+ }
+ };
const listController = createCommandListController({
items: filteredItems,
selectedIndex: CommandState.selectedIndex,
@@ -853,7 +884,7 @@ function CommandSearchMenu(
: t('commandMenu.searchPlaceholder'))
}
value={CommandState.query()}
- onInput={(e) => props.onQueryInput(e.currentTarget, e.isComposing)}
+ onInput={trackInput}
onCompositionEnd={(e) => props.onQueryInput(e.currentTarget, false)}
onKeyDown={props.onQueryKeyDown}
onKeyUp={(e) => props.onQueryKeyUp(e.currentTarget, e.isComposing)}
diff --git a/apps/web/src/features/command/Launcher.tsx b/apps/web/src/features/command/Launcher.tsx
index 9e3eac27e9..8b008afec2 100644
--- a/apps/web/src/features/command/Launcher.tsx
+++ b/apps/web/src/features/command/Launcher.tsx
@@ -12,11 +12,6 @@ import { useQuickCallsFlag } from '@app/features/meetings/use-quick-calls-flag';
import { raiseKeyboardForNewTaskTitle } from '@app/features/task-composer/new-task-title-focus';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
import { t } from '@app/lib/i18n';
-import {
- endTrackedDocumentSpan,
- registerDocumentSpan,
- startDocumentSpan,
-} from '@block-md/observability';
import { openNewChannelModal } from '@channel/CreateChannelModal';
import { useSplitLayout } from '@components/app/split-layout/layout';
import type { BlockAlias, BlockName } from '@core/block';
@@ -162,7 +157,7 @@ const createBlock = async (spec: {
loading?: boolean;
shouldInsert?: boolean;
openCreated?: OpenCreatedItem;
- /** Active creation span; registered by document id after creation. */
+ /** Active creation span, owned by the creation operation. */
span?: Span;
}) => {
const { openWithSplit } = useSplitLayout();
@@ -185,13 +180,11 @@ const createBlock = async (spec: {
const id = await createFn();
if (!id) {
span?.setAttr('error', true);
- span?.end();
split?.goBack();
return;
}
span?.setAttr('document.id', id);
- if (span) registerDocumentSpan(id, span);
if (openCreated?.({ blockName, id })) {
span?.event('doc.navigated');
@@ -286,7 +279,7 @@ export function runCreateAction(
switch (blockName) {
case 'md': {
- const span = startDocumentSpan('doc.create');
+ const span = Telemetry.span('doc.create');
span.setAttr('doc.type', 'md');
span.setAttr('doc.source', source);
span
@@ -308,9 +301,9 @@ export function runCreateAction(
)
.catch((error) => {
span.error(error);
- endTrackedDocumentSpan(span);
reportCreateBlockError(error);
- });
+ })
+ .finally(() => span.end());
return;
}
case 'spreadsheet':
diff --git a/apps/web/src/features/command/mobile/MobileSearchResults.tsx b/apps/web/src/features/command/mobile/MobileSearchResults.tsx
index 4e9f8101ed..81d7a1675e 100644
--- a/apps/web/src/features/command/mobile/MobileSearchResults.tsx
+++ b/apps/web/src/features/command/mobile/MobileSearchResults.tsx
@@ -3,6 +3,7 @@ import { openEntityInSplitFromUnifiedList } from '@app/features/next-soup/utils'
import { projectRouteId } from '@app/features/projects/core/route';
import { createSoupRowStore } from '@app/features/soup/collection/row-store';
import { t } from '@app/lib/i18n';
+import { usePending } from '@app/observability/flow';
import { MobileTopEdgeFade } from '@components/app/mobile/MobileEdgeFade';
import { MobileViewsRow } from '@components/app/mobile/MobileViewsRow';
import { useSplitLayout } from '@components/app/split-layout/layout';
@@ -50,6 +51,8 @@ function MobileNameResults(props: {
enabled: () => true,
contactDiscovery: useCrmContactDiscovery,
});
+ usePending('search.names', source.isLoadingEntities);
+ usePending('search.rank', source.isSettling);
useDatabaseDiscoverySync(() => true);
const incoming = createMemo(() =>
source.rankItems(source.items(), state.query())
@@ -135,6 +138,7 @@ function MobileNameResults(props: {
} else if (item.kind === 'user') {
const result = await directMessage.mutateAsync({
recipient_id: item.id,
+ parentSpan: span,
});
openWithSplit(
{ type: 'channel', id: result.channel_id },
@@ -216,6 +220,7 @@ function MobileFullTextResults(props: {
const state = props.session;
const category = useMobileSearchCategory(state.category);
const search = createMobileFullTextSearch(state.query, category);
+ usePending('search.full-text', search.isSettling);
const hasAuthoritativeError = () =>
!!search.error() && !isTransientRequestError(search.error());
const panel = useSplitPanelOrThrow();
diff --git a/apps/web/src/features/command/useCommandItems.ts b/apps/web/src/features/command/useCommandItems.ts
index 35d59a5316..b245d0514c 100644
--- a/apps/web/src/features/command/useCommandItems.ts
+++ b/apps/web/src/features/command/useCommandItems.ts
@@ -464,6 +464,7 @@ export function useCommandItems(
return {
items: filteredItems,
isLoadingEntities: entities.isLoadingEntities,
+ isSettling: entities.isSettling,
pagination: entities.pagination,
};
}
diff --git a/apps/web/src/features/connector-import/connector-import-dialog.tsx b/apps/web/src/features/connector-import/connector-import-dialog.tsx
index 8cb055a7c8..968cff7d96 100644
--- a/apps/web/src/features/connector-import/connector-import-dialog.tsx
+++ b/apps/web/src/features/connector-import/connector-import-dialog.tsx
@@ -43,6 +43,7 @@ function useProductionContext(
const { authorization_url } = await startMcpAuth.mutateAsync({
server_url: app.mcpUrl,
server_name: app.name,
+ parentSpan: span,
});
assignOauthUrl(popup, authorization_url);
span.setAttr('connector.outcome', 'started');
diff --git a/apps/web/src/features/crm/primitives/import-companies.ts b/apps/web/src/features/crm/primitives/import-companies.ts
index 7f667c8f32..8ce8b30312 100644
--- a/apps/web/src/features/crm/primitives/import-companies.ts
+++ b/apps/web/src/features/crm/primitives/import-companies.ts
@@ -133,9 +133,9 @@ export function createCompanyImport(
setError('Could not read that file. Please try again.');
}
}
- async function importRow(row: CompanyImportRow) {
+ async function importRow(row: CompanyImportRow, parent: Span) {
try {
- const outcome = await importer.create(row);
+ const outcome = await parent.run(() => importer.create(row));
if (outcome === 'exists') setExisting((n) => n + 1);
else setCompleted((n) => n + 1);
return true;
@@ -173,7 +173,7 @@ export function createCompanyImport(
span.setAttr('crm.import.pipeline_rows', result.added);
setPipeline({ pipeline: target, ...result });
try {
- await transfer.refresh();
+ await span.run(() => transfer.refresh());
} catch {
// The rows are saved; the pipeline's own polling shows them.
}
@@ -194,9 +194,9 @@ export function createCompanyImport(
'crm.companies.import',
async (span) => {
span.setAttr('crm.import.rows', rows().length);
- await span.span('crm.companies.import.create', () =>
+ await span.span('crm.companies.import.create', (create) =>
runConcurrently(rows(), IMPORT_CONCURRENCY, async (row) => {
- if (!(await importRow(row))) failed.add(row);
+ if (!(await importRow(row, create))) failed.add(row);
})
);
span.setAttr('crm.import.created', completed());
@@ -204,7 +204,7 @@ export function createCompanyImport(
span.setAttr('crm.import.failed', failed.size);
const saved = await importPipeline(span, signal);
try {
- await importer.refresh();
+ await span.run(() => importer.refresh());
} catch (cause) {
// The companies exist; listings catch up on their next read.
span.event('refresh_failed', {
diff --git a/apps/web/src/features/crm/views/company-detail.tsx b/apps/web/src/features/crm/views/company-detail.tsx
index 682d7da62a..293e8d6ea8 100644
--- a/apps/web/src/features/crm/views/company-detail.tsx
+++ b/apps/web/src/features/crm/views/company-detail.tsx
@@ -1,3 +1,4 @@
+import { TraceFlow, usePending } from '@app/observability/flow';
import { SidePanel } from '@components/app/side-panel';
import { createMemo, Match, onCleanup, Show, Suspense, Switch } from 'solid-js';
import { CrmListSkeleton } from '../components/list-state';
@@ -31,14 +32,31 @@ import { useCompanyQuery } from './use-crm';
* calls. Properties, sharing, and references open in the floating
* information panel.
*/
-export function Company(props: {
+type CompanyProps = {
companyId: string;
section?: CompanySection;
headerToggle?: boolean;
onHidden?: () => void;
onOpenContact?: (contact: CompanyContact) => void;
onOpenPipeline?: (pipelineId: string) => void;
-}) {
+};
+
+export function Company(props: CompanyProps) {
+ return (
+ <TraceFlow
+ name="crm.company"
+ key={() => `${props.companyId}:${props.section ?? 'overview'}`}
+ attributes={{
+ 'company.id': props.companyId,
+ 'crm.section': props.section ?? 'overview',
+ }}
+ >
+ <CompanyContent {...props} />
+ </TraceFlow>
+ );
+}
+
+function CompanyContent(props: CompanyProps) {
const context = useCrmContext();
onCleanup(
context.registerTaskComposerRecord(() => ({
@@ -48,7 +66,8 @@ export function Company(props: {
);
const listsEnabled = context.listsEnabled();
const pipelinesEnabled = context.pipelinesEnabled();
- const { company, contacts } = useCompanyQuery(() => props.companyId);
+ const { company, contacts, query } = useCompanyQuery(() => props.companyId);
+ usePending('crm.record', () => query.isLoading);
const section = () => props.section ?? 'overview';
const scope = createMemo(
(): CrmRecordScope | undefined => {
diff --git a/apps/web/src/features/crm/views/contact-detail.tsx b/apps/web/src/features/crm/views/contact-detail.tsx
index ce990b4e73..f614d8e615 100644
--- a/apps/web/src/features/crm/views/contact-detail.tsx
+++ b/apps/web/src/features/crm/views/contact-detail.tsx
@@ -1,3 +1,4 @@
+import { TraceFlow, usePending } from '@app/observability/flow';
import { SidePanel } from '@components/app/side-panel';
import { createMemo, Match, onCleanup, Show, Suspense, Switch } from 'solid-js';
import { CrmListSkeleton } from '../components/list-state';
@@ -26,16 +27,34 @@ import { useContactQuery, useIsTeamAdmin } from './use-crm';
* the other sections list its emails, files, tasks and calls. Sharing and
* references stay in the floating information panel.
*/
-export function Contact(props: {
+type ContactProps = {
contactId: string;
section?: ContactSection;
headerToggle?: boolean;
onOpenCompany?: (companyId: string) => boolean;
onOpenPipeline?: (pipelineId: string) => void;
-}) {
+};
+
+export function Contact(props: ContactProps) {
+ return (
+ <TraceFlow
+ name="crm.contact"
+ key={() => `${props.contactId}:${props.section ?? 'overview'}`}
+ attributes={{
+ 'contact.id': props.contactId,
+ 'crm.section': props.section ?? 'overview',
+ }}
+ >
+ <ContactContent {...props} />
+ </TraceFlow>
+ );
+}
+
+function ContactContent(props: ContactProps) {
const context = useCrmContext();
const pipelinesEnabled = context.pipelinesEnabled();
const contactQuery = useContactQuery(() => props.contactId);
+ usePending('crm.record', () => contactQuery.isLoading);
const contact = () => contactQuery.data;
onCleanup(
context.registerTaskComposerRecord(() => ({
diff --git a/apps/web/src/features/crm/views/default-view.tsx b/apps/web/src/features/crm/views/default-view.tsx
index fbcd3b7718..d1873468d2 100644
--- a/apps/web/src/features/crm/views/default-view.tsx
+++ b/apps/web/src/features/crm/views/default-view.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import type { CrmViewConfig } from '../core/saved-view';
import { createDefaultCrmView } from '../primitives/default-view';
import { useApplyCrmView } from './apply-view';
@@ -16,6 +17,8 @@ export function CrmDefaultViewLoader(props: {
const personal = usePersonalCrmViews();
const team = useTeamCrmViews();
const applyView = useApplyCrmView();
+ usePending('crm.personal-views', personal.isLoading);
+ usePending('crm.team-views', team.isLoading);
createDefaultCrmView({
personalLoading: personal.isLoading,
diff --git a/apps/web/src/features/crm/views/record-item-list.tsx b/apps/web/src/features/crm/views/record-item-list.tsx
index e68e58a781..cdde92914d 100644
--- a/apps/web/src/features/crm/views/record-item-list.tsx
+++ b/apps/web/src/features/crm/views/record-item-list.tsx
@@ -1,6 +1,7 @@
import { DateGroupHeading } from '@app/features/next-soup/soup-view/date-group-heading';
import { dateBucket } from '@app/features/soup/collection/date-buckets';
import { createKeyedProjection } from '@app/lib/queries/soup/create-keyed-projection';
+import { usePending } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import {
ListEntity,
@@ -99,6 +100,7 @@ export function RecordItemList(props: {
// paused requests; a disabled one shows the empty state instead.
const loading = () =>
props.pending || (props.source.isPending && props.source.isEnabled);
+ usePending('crm.items', () => Boolean(loading()));
return (
<div class="flex min-h-0 w-full flex-1 flex-col">
diff --git a/apps/web/src/features/database-query/queries/app-query-source.ts b/apps/web/src/features/database-query/queries/app-query-source.ts
index ffa47d881a..468346472f 100644
--- a/apps/web/src/features/database-query/queries/app-query-source.ts
+++ b/apps/web/src/features/database-query/queries/app-query-source.ts
@@ -2,7 +2,7 @@ import { handleAiUsageLimitError } from '@app/features/paywall/ai-usage-limit-ha
import type { TModel } from '@core/component/AI/constant';
import { databaseSqlAnswer } from '@core/database-sql/answer';
import { databaseSqlSchema } from '@core/database-sql/catalog';
-import { Telemetry } from '@macro-inc/observability';
+import { type Span, Telemetry } from '@macro-inc/observability';
import { queryClient } from '@queries/client';
import {
checkDatabaseSql,
@@ -52,6 +52,7 @@ function generateDatabaseQuery(
input: Parameters<QueryCapabilities['generate']>[0],
model: TModel
): ResultAsync<QueryProposal, QueryFailure> {
+ const parent = Telemetry.captureContext();
return ResultAsync.fromPromise(
import('@service-cognition/database-query'),
(thrown) =>
@@ -60,10 +61,12 @@ function generateDatabaseQuery(
)
)
.andThen((cognition) =>
- cognition.generateDatabaseQuery(input, model).mapErr((failure) => {
- handleAiUsageLimitError(failure.errors);
- return generationFailure(serviceError(failure.errors).message);
- })
+ parent
+ .run(() => cognition.generateDatabaseQuery(input, model))
+ .mapErr((failure) => {
+ handleAiUsageLimitError(failure.errors);
+ return generationFailure(serviceError(failure.errors).message);
+ })
)
.andThen(parseQueryProposal);
}
@@ -71,7 +74,7 @@ function generateDatabaseQuery(
/** Phase summaries remain visible in DevTools even when browser export is disabled. */
function traceQueryPhase<T>(
phase: 'generate' | 'read' | 'catalog',
- work: () => ResultAsync<T, QueryFailure>,
+ work: (span: Span) => ResultAsync<T, QueryFailure>,
attributes: Record<string, string | number | boolean> = {}
): ResultAsync<T, QueryFailure> {
const span = Telemetry.span(`database.query.${phase}`);
@@ -81,7 +84,7 @@ function traceQueryPhase<T>(
const settle = async () => {
let outcome = 'error';
try {
- const result = await span.run(work);
+ const result = await span.run(() => work(span));
outcome = result.isOk() ? 'success' : result.error.kind;
span.setAttr('database.outcome', outcome);
if (result.isErr()) span.error(result.error.kind);
@@ -124,15 +127,19 @@ export function createQueryCapabilities(
},
// A draft question may read any database the viewer can reach.
read: (sql, context) =>
- traceQueryPhase('read', () =>
+ traceQueryPhase('read', (read) =>
traceQueryPhase('catalog', viewerDatabases).andThen((databases) =>
- readDatabaseSql({
- schema: databaseSqlSchema(databases),
- sql,
- scope: context?.databaseId,
- }).map(({ catalog, outcome }) =>
- databaseSqlAnswer(outcome, catalog, databases)
- )
+ read
+ .run(() =>
+ readDatabaseSql({
+ schema: databaseSqlSchema(databases),
+ sql,
+ scope: context?.databaseId,
+ })
+ )
+ .map(({ catalog, outcome }) =>
+ databaseSqlAnswer(outcome, catalog, databases)
+ )
)
),
describe: (databaseId) =>
diff --git a/apps/web/src/features/database/components/grid-cell.tsx b/apps/web/src/features/database/components/grid-cell.tsx
index 5ff3bb6b69..c0cbd79347 100644
--- a/apps/web/src/features/database/components/grid-cell.tsx
+++ b/apps/web/src/features/database/components/grid-cell.tsx
@@ -899,6 +899,7 @@ function InlineEditor(props: {
when={renderTextEditor}
fallback={
<input
+ data-input-surface="grid-cell"
ref={(element) => {
input = element;
props.onEditorReady?.(focus);
diff --git a/apps/web/src/features/database/primitives/table-controller.ts b/apps/web/src/features/database/primitives/table-controller.ts
index 78e1c3487c..a370a2c1c4 100644
--- a/apps/web/src/features/database/primitives/table-controller.ts
+++ b/apps/web/src/features/database/primitives/table-controller.ts
@@ -167,7 +167,14 @@ export function createTableController(
if (written.isErr()) {
const failure = written.error;
const outcomeUnknown = failure.kind === 'outcome-unknown';
- if (outcomeUnknown && (await source.refresh('after-write')).isErr())
+ if (
+ outcomeUnknown &&
+ (
+ await span.span('database.rows.refresh', async () =>
+ source.refresh('after-write')
+ )
+ ).isErr()
+ )
setRefreshWarning(true);
const failed: FailedWrite = {
mutation,
diff --git a/apps/web/src/features/drive-view/components/FileDetail.test.tsx b/apps/web/src/features/drive-view/components/FileDetail.test.tsx
index a6b77e8a2f..488f4b740d 100644
--- a/apps/web/src/features/drive-view/components/FileDetail.test.tsx
+++ b/apps/web/src/features/drive-view/components/FileDetail.test.tsx
@@ -1,8 +1,10 @@
+import { TraceFlow, useFlow } from '@app/observability/flow';
+import { initializeUiOperationTelemetry } from '@app/observability/ui-operation';
import { ThrownResultError } from '@core/util/result';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import { type Accessor, createSignal, type JSX, onCleanup } from 'solid-js';
import { render } from 'solid-js/web';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const analytics = vi.hoisted(() => ({ pageView: vi.fn(), track: vi.fn() }));
vi.mock('@app/lib/analytics/analytics-context', () => ({
@@ -53,9 +55,15 @@ vi.mock('@ui', () => ({
import { FileDetailLoadGate } from './FileDetail';
let dispose: (() => void) | undefined;
+let disposeTelemetry: (() => void) | undefined;
+beforeEach(() => {
+ disposeTelemetry = initializeUiOperationTelemetry();
+});
afterEach(() => {
analytics.track.mockClear();
dispose?.();
+ disposeTelemetry?.();
+ vi.restoreAllMocks();
document.body.replaceChildren();
});
@@ -200,3 +208,46 @@ describe('file access errors', () => {
}
);
});
+
+it('holds the view flow while the shared document resource loads', async () => {
+ const pending = Promise.withResolvers<Loaded>();
+ const published = Promise.withResolvers<void>();
+ const settled = Promise.withResolvers<void>();
+ const ready = vi.fn(() => settled.resolve());
+ function ObserveReady() {
+ const span = useFlow().span;
+ const setAttr = span.setAttr.bind(span);
+ vi.spyOn(span, 'setAttr').mockImplementation((key, value) => {
+ setAttr(key, value);
+ if (key === 'ui.work_to_ready_ms') ready();
+ });
+ return null;
+ }
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ dispose = render(
+ () => (
+ <TraceFlow name="view.document">
+ <ObserveReady />
+ <FileDetailLoadGate
+ documentId="document"
+ entityType="md"
+ label="document"
+ load={() => pending.promise}
+ >
+ {() => {
+ published.resolve();
+ return <div>Loaded</div>;
+ }}
+ </FileDetailLoadGate>
+ </TraceFlow>
+ ),
+ container
+ );
+ await Promise.resolve();
+ expect(ready).not.toHaveBeenCalled();
+ pending.resolve({ userAccessLevel: 'owner' });
+ await published.promise;
+ await settled.promise;
+ expect(ready).toHaveBeenCalledOnce();
+});
diff --git a/apps/web/src/features/drive-view/components/FileDetail.tsx b/apps/web/src/features/drive-view/components/FileDetail.tsx
index 6d6ce651c5..bcd4e325c8 100644
--- a/apps/web/src/features/drive-view/components/FileDetail.tsx
+++ b/apps/web/src/features/drive-view/components/FileDetail.tsx
@@ -4,6 +4,7 @@ import {
} from '@app/features/access-requests/access-requests';
import { shareEntity } from '@app/features/access-requests/core/types';
import { useAnalytics } from '@app/lib/analytics/analytics-context';
+import { useFlow, usePending } from '@app/observability/flow';
import {
DocumentFileSidePanelSections,
SidePanel,
@@ -16,6 +17,7 @@ import {
} from '@core/component/SharePermissions';
import { fireAndForget } from '@core/util/fireAndForget';
import SpinnerIcon from '@icon/system/regular/spinner.svg';
+import type { Span } from '@macro-inc/observability';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
import { Button } from '@ui';
@@ -104,7 +106,7 @@ export function FileDetailLoadGate<
/** The block the document opens as, reported on `open_entity`. */
entityType: string;
label: string;
- load: (documentId: string) => Promise<T>;
+ load: (documentId: string, parentSpan?: Span) => Promise<T>;
/**
* Releases what a load opened, such as a markdown document's sync source,
* once its result can no longer be shown: its content replaced or removed,
@@ -115,6 +117,7 @@ export function FileDetailLoadGate<
children: (data: T) => JSX.Element;
}) {
const analytics = useAnalytics();
+ const flow = useFlow();
// Shown results are released when their content is disposed (after the
// editor it rendered); the rest here. Each result is released once.
const released = new WeakSet<T>();
@@ -128,7 +131,11 @@ export function FileDetailLoadGate<
let current: T | undefined;
const load = async (documentId: string): Promise<T | undefined> => {
const request = ++latestLoad;
- const data = await props.load(documentId);
+ const data = await flow.task('document.load', (span) => {
+ span.setAttr('doc.type', props.entityType);
+ span.setAttr('document.id', documentId);
+ return props.load(documentId, span);
+ });
// The resource ignores a superseded result; one unloaded while pending
// (access revoked) must not become current either, so a later grant finds
// nothing loaded and reloads. Nothing will show it, so release it now.
@@ -154,6 +161,7 @@ export function FileDetailLoadGate<
() => props.documentId,
load
);
+ usePending('document.resource', () => document.loading);
// Counts the open once per document, as BlockLoader does for blocks; access
// changes and retries reload the same document without reopening it.
let trackedDocumentId: string | undefined;
diff --git a/apps/web/src/features/drive-view/drive-view.tsx b/apps/web/src/features/drive-view/drive-view.tsx
index ed883c4351..ad95201d0b 100644
--- a/apps/web/src/features/drive-view/drive-view.tsx
+++ b/apps/web/src/features/drive-view/drive-view.tsx
@@ -6,6 +6,7 @@ import {
} from '@app/features/soup';
import { ViewTour } from '@app/features/tours/ViewTour';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
+import { usePending } from '@app/observability/flow';
import { useGlobalNotificationSource } from '@components/app/GlobalAppState';
import {
useSplitPanelOrThrow,
@@ -88,6 +89,7 @@ function DriveComposition(props: { route: DriveRouteState }) {
notificationSource,
})
);
+ usePending('drive.items', source.isLoading);
const actions = createDriveHostActions({
projectId: () => state.projectId(),
selectFolder: (id) => state.selectFolder(id),
diff --git a/apps/web/src/features/email-compose/primitives/attachment-links.ts b/apps/web/src/features/email-compose/primitives/attachment-links.ts
index 9dd6b5f47d..e7a197a86b 100644
--- a/apps/web/src/features/email-compose/primitives/attachment-links.ts
+++ b/apps/web/src/features/email-compose/primitives/attachment-links.ts
@@ -124,7 +124,7 @@ export function createAttachmentLinkOffer(options: {
span.setAttr('email.attachment_links.linked', valid);
if (!valid) return;
for (const document of documents) {
- options.editorFiles.makePublic(document.documentId);
+ span.run(() => options.editorFiles.makePublic(document.documentId));
}
if (editor) appendAttachmentLinks(editor, documents, current);
} finally {
diff --git a/apps/web/src/features/email-compose/primitives/draft-transfer.test.ts b/apps/web/src/features/email-compose/primitives/draft-transfer.test.ts
index d3a2a68727..68ee5d1cbe 100644
--- a/apps/web/src/features/email-compose/primitives/draft-transfer.test.ts
+++ b/apps/web/src/features/email-compose/primitives/draft-transfer.test.ts
@@ -1,4 +1,5 @@
-import { ZoneContextManager } from '@macro-inc/observability/zone';
+import { Telemetry } from '@macro-inc/observability';
+import { StackContextManager } from '@macro-inc/observability/web';
import { context, propagation, trace } from '@opentelemetry/api';
import { W3CTraceContextPropagator } from '@opentelemetry/core';
import {
@@ -6,7 +7,7 @@ import {
type ReadableSpan,
} from '@opentelemetry/sdk-trace-base';
import { transferEmailDraft } from '@queries/email/draft';
-import { afterEach, expect, it, vi } from 'vitest';
+import { afterEach, beforeAll, expect, it, vi } from 'vitest';
import type { EmailInbox } from '../context/compose-capabilities';
import { createDraftSession } from './draft-session';
import { createDraftTransfer } from './draft-transfer';
@@ -14,7 +15,7 @@ import { createDraftTransfer } from './draft-transfer';
const finished: ReadableSpan[] = [];
let open = 0;
let settled: (() => void) | undefined;
-context.setGlobalContextManager(new ZoneContextManager().enable());
+context.setGlobalContextManager(new StackContextManager().enable());
propagation.setGlobalPropagator(new W3CTraceContextPropagator());
trace.setGlobalTracerProvider(
new BasicTracerProvider({
@@ -43,6 +44,14 @@ function spansSettled() {
});
}
+beforeAll(async () => {
+ await Telemetry.init({
+ serviceName: 'test',
+ environment: 'test',
+ enabled: async () => true,
+ });
+});
+
const outlook: EmailInbox = {
id: 'outlook-inbox',
email_address: '[email protected]',
diff --git a/apps/web/src/features/email-compose/primitives/email-composer.ts b/apps/web/src/features/email-compose/primitives/email-composer.ts
index 5cec293946..b26675302b 100644
--- a/apps/web/src/features/email-compose/primitives/email-composer.ts
+++ b/apps/web/src/features/email-compose/primitives/email-composer.ts
@@ -2,6 +2,7 @@ import {
attachmentLimitBytes,
MACRO_EMAIL_SIGNATURE,
} from '@app/features/email-compose/core/constants';
+import { startUiOperation } from '@app/observability/ui-operation';
import { setEditorStateFromHtml } from '@core/component/LexicalMarkdown/utils/setEditorStateFromHtml';
import { fireAndForget } from '@core/util/fireAndForget';
import { $generateHtmlFromNodes } from '@lexical/html';
@@ -938,6 +939,14 @@ export function createEmailComposer(props: EmailComposerOptions) {
setSendPhase('preparing');
const sendOperation = ++sendOperationVersion;
const sendGeneration = identityVersion;
+ // Send to the composer's sent state; an early return cancels it.
+ const sendUi = startUiOperation('email.send', {
+ attributes: {
+ 'email.send.queued':
+ props.delivery.queueActive?.(activeInboxId()) ?? false,
+ },
+ });
+ let sent = false;
try {
// Durable sends need the latest local copy, without waiting for a server save.
const epochBeforeSave = session.epoch();
@@ -1066,6 +1075,8 @@ export function createEmailComposer(props: EmailComposerOptions) {
session.dispatch({ type: 'reset' });
setDraftGeneration(0);
afterSend(result, currentLink.id);
+ sent = true;
+ sendUi.afterPaint();
} finally {
if (
sendGeneration === identityVersion &&
@@ -1074,10 +1085,12 @@ export function createEmailComposer(props: EmailComposerOptions) {
cleanupWatermark();
}
} catch (error) {
+ sendUi.finish('error');
if (sendGeneration !== identityVersion) return;
props.notices.reportError(error);
if (!completed()) props.notices.feedback.failure('Failed to send email');
} finally {
+ if (!sent) sendUi.cancel();
if (sendOperation === sendOperationVersion) setSendPhase('idle');
}
};
diff --git a/apps/web/src/features/email-compose/primitives/emptied-draft-delete.test.ts b/apps/web/src/features/email-compose/primitives/emptied-draft-delete.test.ts
index 5817002ab8..609ec07dee 100644
--- a/apps/web/src/features/email-compose/primitives/emptied-draft-delete.test.ts
+++ b/apps/web/src/features/email-compose/primitives/emptied-draft-delete.test.ts
@@ -40,6 +40,7 @@ vi.mock('@core/constant/featureFlags', () => ({
isFeatureEnabled: () => true,
}));
vi.mock('@macro-inc/observability', () => ({
+ NOOP_SPAN: {},
Telemetry: { error: vi.fn() },
}));
vi.mock('@service-storage/graphql-soup', () => ({
diff --git a/apps/web/src/features/email-compose/views/compose-offline.test.tsx b/apps/web/src/features/email-compose/views/compose-offline.test.tsx
index 440e670bcb..5a7babb3a3 100644
--- a/apps/web/src/features/email-compose/views/compose-offline.test.tsx
+++ b/apps/web/src/features/email-compose/views/compose-offline.test.tsx
@@ -25,7 +25,8 @@ vi.mock('@queries/client', () => ({
invalidateQueries: vi.fn(async () => {}),
},
}));
-vi.mock('@macro-inc/observability', () => ({
+vi.mock('@macro-inc/observability', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@macro-inc/observability')>()),
Telemetry: { error: vi.fn(), info: vi.fn() },
}));
vi.mock('@service-storage/graphql-soup', () => ({
diff --git a/apps/web/src/features/email-view/components/EmailDetailView.tsx b/apps/web/src/features/email-view/components/EmailDetailView.tsx
index e8824a269d..bfe768ec93 100644
--- a/apps/web/src/features/email-view/components/EmailDetailView.tsx
+++ b/apps/web/src/features/email-view/components/EmailDetailView.tsx
@@ -5,6 +5,7 @@ import type { EmailThreadHost } from '@app/features/email-thread/context/email-t
import { createEmailThreadSource } from '@app/features/email-thread/queries/thread-source';
import { useBlockEntityCommands } from '@app/features/next-soup/actions';
import { createSearchParams, useRouteParams } from '@app/lib/split-router';
+import { usePending } from '@app/observability/flow';
import { emailThreadRoute } from '@app/routes/routes';
import {
EmailThreadControlGroups,
@@ -129,6 +130,7 @@ export function EmailDetailView(props: {
const threadQuery = useThreadQuery(threadId, () => ({
enabled: !!threadId(),
}));
+ usePending('email.thread', () => threadQuery.isLoading);
const source = createEmailThreadSource(threadId, threadQuery);
const threadData = source.thread;
const title = () => {
diff --git a/apps/web/src/features/email-view/components/EmailList.tsx b/apps/web/src/features/email-view/components/EmailList.tsx
index a1a625637c..73056f4981 100644
--- a/apps/web/src/features/email-view/components/EmailList.tsx
+++ b/apps/web/src/features/email-view/components/EmailList.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { QueuedSendStatus } from '../../email-compose/queued-send-status';
import '@entity/composed/ListEntity.css';
import {
@@ -127,6 +128,7 @@ export function EmailList(props: EmailListProps) {
selectedThread,
filterByTag,
} = useEmailView();
+ usePending('email.list.items', () => source.isLoading());
const panel = useSplitPanelOrThrow();
function openEntity(
diff --git a/apps/web/src/features/email-view/email-view-context.tsx b/apps/web/src/features/email-view/email-view-context.tsx
index 910b7fe5e0..49ae6dd1b2 100644
--- a/apps/web/src/features/email-view/email-view-context.tsx
+++ b/apps/web/src/features/email-view/email-view-context.tsx
@@ -14,6 +14,7 @@ import {
useNavigate,
useRouteParams,
} from '@app/lib/split-router';
+import { beginInteraction } from '@app/observability/flow';
import { usePreference } from '@app/preferences/use-preference';
import { emailSplitRoute, emailThreadRoute } from '@app/routes/routes';
import { createPreviewSelectionGuard } from '@components/app/createPreviewSelectionGuard';
@@ -354,14 +355,24 @@ export const [EmailViewProvider, useEmailView] = createAssertedContextProvider<
closeThread();
return;
}
- setState(
- produce((draft) => {
- if (draft.tab === 'reminders' || tab === 'reminders') draft.search = '';
- draft.tab = tab;
- draft.facets = {};
- })
- );
- closeThread();
+ // The list's email.list flow restarts for the tab and joins this.
+ const interaction = beginInteraction('email.tab', {
+ attributes: { 'email.tab': tab },
+ closeOnJoin: true,
+ });
+ try {
+ setState(
+ produce((draft) => {
+ if (draft.tab === 'reminders' || tab === 'reminders')
+ draft.search = '';
+ draft.tab = tab;
+ draft.facets = {};
+ })
+ );
+ closeThread();
+ } finally {
+ interaction.end();
+ }
};
const setInboxIds = (ids: string[] | undefined) => {
diff --git a/apps/web/src/features/email-view/email-view.tsx b/apps/web/src/features/email-view/email-view.tsx
index c4f9a8e556..6392e3c06e 100644
--- a/apps/web/src/features/email-view/email-view.tsx
+++ b/apps/web/src/features/email-view/email-view.tsx
@@ -5,6 +5,7 @@ import {
} from '@app/components/view-shell';
import { ViewTour } from '@app/features/tours/ViewTour';
import { SplitRouter } from '@app/lib/split-router';
+import { TraceFlow } from '@app/observability/flow';
import { usePreference } from '@app/preferences/use-preference';
import { type PillTabItem, PillTabs } from '@components/app/mobile/PillTabs';
import { SplitHeaderLeft } from '@components/app/split-layout/components/SplitHeader';
@@ -246,7 +247,9 @@ function EmailViewRoot() {
const list = () => (
<Suspense fallback={<EmailListFallback />}>
- <EmailList ref={setListElement} pane={listPane()} />
+ <TraceFlow name="email.list" key={() => state.tab}>
+ <EmailList ref={setListElement} pane={listPane()} />
+ </TraceFlow>
</Suspense>
);
diff --git a/apps/web/src/features/entity/bulk-edit/move-entities-to-folder.ts b/apps/web/src/features/entity/bulk-edit/move-entities-to-folder.ts
index a0a32a84e0..a0f888e80c 100644
--- a/apps/web/src/features/entity/bulk-edit/move-entities-to-folder.ts
+++ b/apps/web/src/features/entity/bulk-edit/move-entities-to-folder.ts
@@ -20,6 +20,7 @@ export function createMoveEntitiesToFolder(source: string) {
name: entity.name || entity.id,
})),
project: folder,
+ parentSpan: span,
});
} catch (error) {
span.setAttr('move.outcome', 'failed');
diff --git a/apps/web/src/features/entity/queries/dss.ts b/apps/web/src/features/entity/queries/dss.ts
index fe52526602..e09edfec93 100644
--- a/apps/web/src/features/entity/queries/dss.ts
+++ b/apps/web/src/features/entity/queries/dss.ts
@@ -1,3 +1,4 @@
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
/** Document-storage mutations used by entity surfaces. */
import { databaseEntityMessage } from '@app/features/database/core/write-failure';
@@ -590,9 +591,11 @@ export function createBulkMoveToProjectDssEntityMutation() {
mutationFn: async ({
entities,
project,
+ parentSpan,
}: {
entities: (EntityData & { name: string })[];
project: { id: string; name: string };
+ parentSpan?: TraceContext;
}) => {
if (!entities.every(isFolderMovable)) {
throw new Error(`Unsupported entity type provided`);
@@ -600,11 +603,13 @@ export function createBulkMoveToProjectDssEntityMutation() {
const results = await Promise.all(
entities.map((entity) =>
- moveToFolder({
- itemType: entity.type,
- id: entity.id,
- folderId: project.id,
- })
+ (parentSpan ?? Telemetry.captureContext()).run(() =>
+ moveToFolder({
+ itemType: entity.type,
+ id: entity.id,
+ folderId: project.id,
+ })
+ )
)
);
@@ -621,6 +626,7 @@ export function createBulkMoveToProjectDssEntityMutation() {
}: {
entities: (EntityData & { name: string })[];
project: { id: string; name: string };
+ parentSpan?: TraceContext;
}) => {
const moveableEntities = entities.filter(
(e): e is typeof e & { type: 'document' | 'chat' | 'email' } =>
@@ -642,7 +648,7 @@ export function createBulkMoveToProjectDssEntityMutation() {
];
},
- onSettled: (data, error, { entities, project }, context) => {
+ onSettled: (data, error, { entities, project, parentSpan }, context) => {
const failed = data?.success === false || !!error;
if (failed) {
context?.forEach((txn) => txn.rollback());
@@ -650,11 +656,13 @@ export function createBulkMoveToProjectDssEntityMutation() {
}
invalidateListedEntities(entities);
- return invalidateAfterMove(
- entities.map((e) => e.id),
- project.id,
- entities.some((e) => e.type === 'project'),
- failed
+ return (parentSpan ?? Telemetry.captureContext()).run(() =>
+ invalidateAfterMove(
+ entities.map((e) => e.id),
+ project.id,
+ entities.some((e) => e.type === 'project'),
+ failed
+ )
);
},
}));
diff --git a/apps/web/src/features/home/components/HomeList.tsx b/apps/web/src/features/home/components/HomeList.tsx
index 175eae82d1..d31d47655c 100644
--- a/apps/web/src/features/home/components/HomeList.tsx
+++ b/apps/web/src/features/home/components/HomeList.tsx
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import '@entity/composed/ListEntity.css';
import {
createListController,
@@ -113,6 +114,8 @@ export function HomeList(props: HomeListProps) {
useHomeDataSource(state)
);
+ usePending('home.items', source.isLoading);
+
const list = withSplitPanelOwner(listOwnedSlotName('controller'), () =>
createListController<HomeDataSourceItem, HomeListActivationMetadata>({
items: source.items,
diff --git a/apps/web/src/features/home/home-view.tsx b/apps/web/src/features/home/home-view.tsx
index fa50dbebf6..8fb960eae7 100644
--- a/apps/web/src/features/home/home-view.tsx
+++ b/apps/web/src/features/home/home-view.tsx
@@ -3,6 +3,7 @@ import { SidebarCreateHeader } from '@app/components/view-shell/SidebarCreateBut
import { calendarSearch } from '@app/features/calendar-view/calendar-url';
import { ViewTour } from '@app/features/tours/ViewTour';
import { createSearchParams, SplitRouter } from '@app/lib/split-router';
+import { TraceFlow } from '@app/observability/flow';
import { homeCalendarRoute } from '@app/routes/routes';
import { DebugSuspense } from '@channel/DebugSuspense';
import { useGlobalBlockOrchestrator } from '@components/app/GlobalAppState';
@@ -76,11 +77,13 @@ function HomeListPane(props: {
>
<ViewTour tour={homeTour} />
<DebugSuspense name="HomeView.list" fallback={<HomeFallback />}>
- <HomeList
- hasPreview={props.hasPreview}
- onPreviewEntityChange={props.onPreviewEntityChange}
- onPreviewActivate={showContent}
- />
+ <TraceFlow name="home.list">
+ <HomeList
+ hasPreview={props.hasPreview}
+ onPreviewEntityChange={props.onPreviewEntityChange}
+ onPreviewActivate={showContent}
+ />
+ </TraceFlow>
</DebugSuspense>
</HomeListLayout>
);
diff --git a/apps/web/src/features/local-runtime/primitives/local-runtime-setup.ts b/apps/web/src/features/local-runtime/primitives/local-runtime-setup.ts
index 0fd9269e99..0d1fb0e2eb 100644
--- a/apps/web/src/features/local-runtime/primitives/local-runtime-setup.ts
+++ b/apps/web/src/features/local-runtime/primitives/local-runtime-setup.ts
@@ -1,5 +1,5 @@
import type { MacrodDetectedAgent, MacrodStatus } from '@macro/tauri/macrod';
-import { Telemetry } from '@macro-inc/observability';
+import { type Span, Telemetry } from '@macro-inc/observability';
import { err, ok, type Result, ResultAsync } from 'neverthrow';
import { createSignal } from 'solid-js';
import {
@@ -42,15 +42,16 @@ export function createLocalRuntimeSetup(caps: SetupCapabilities) {
const attempt = async <T>(
step: SetupStep,
- work: () => Promise<T>
+ parent: Span,
+ work: (span: Span) => Promise<T>
): Promise<Result<T, string>> => {
setState({ kind: 'running', step });
// Error messages can carry local paths, so the span records only the
// outcome; the user sees the message.
- const span = Telemetry.span(`local_runtime.setup.${step}`);
+ const span = parent.span(`local_runtime.setup.${step}`);
const result = await span.run(
async () =>
- await ResultAsync.fromPromise(work(), (error) =>
+ await ResultAsync.fromPromise(work(span), (error) =>
errorMessage(error, FALLBACK_ERRORS[step])
)
);
@@ -73,9 +74,10 @@ export function createLocalRuntimeSetup(caps: SetupCapabilities) {
};
const connect = async (
- choices: SetupChoices
+ choices: SetupChoices,
+ parent: Span
): Promise<Result<MacrodStatus, string>> => {
- const found = await attempt('detect', async () => {
+ const found = await attempt('detect', parent, async () => {
const offered = await scan();
return choices.agentId
? offered.find((agent) => agent.id === choices.agentId)
@@ -88,25 +90,30 @@ export function createLocalRuntimeSetup(caps: SetupCapabilities) {
return err('no-agents');
}
- return await attempt('connect', async () => {
+ return await attempt('connect', parent, async (span) => {
await caps.startDaemon({
agent: agent.id,
workspace: choices.workspace?.trim() || undefined,
scope: 'private',
allowPermissionBypass: choices.fullAccess,
});
- return await caps.waitForRunning((phase) =>
- setState({ kind: 'running', step: 'connect', phase })
+ return await span.run(() =>
+ caps.waitForRunning((phase) =>
+ setState({ kind: 'running', step: 'connect', phase })
+ )
);
});
};
- const loadModel = async (harnessId: string): Promise<string> => {
+ const loadModel = async (
+ harnessId: string,
+ parent: Span
+ ): Promise<string> => {
let lastError: unknown;
for (let tries = 0; tries < MODEL_LOAD_ATTEMPTS; tries++) {
if (tries > 0) await caps.sleep(MODEL_LOAD_INTERVAL_MS);
const result = await ResultAsync.fromPromise(
- caps.loadModels(harnessId),
+ parent.run(() => caps.loadModels(harnessId)),
(error) => error
);
if (result.isErr()) {
@@ -122,27 +129,37 @@ export function createLocalRuntimeSetup(caps: SetupCapabilities) {
/** Reuse an agent already bound to this runtime, or create one. */
const ensureAgent = async (
status: MacrodStatus,
- choices: SetupChoices
+ choices: SetupChoices,
+ parent: Span
): Promise<ReadyAgent> => {
const harnessId = status.harnessId;
if (!harnessId) throw new Error('This computer is not connected yet.');
- const existing = (await caps.listAgents()).find(
+ const existing = (await parent.run(() => caps.listAgents())).find(
(agent) => agent.harnessId === harnessId
);
if (existing) return existing;
const name = status.agentName ?? 'Local agent';
- return await caps.createAgent({
- name,
- handle: agentHandle(name),
- description: `Runs ${name} on this computer with your own login.`,
- harnessId,
- defaultModel: await loadModel(harnessId),
- autoAcceptPermissions: choices.fullAccess,
- });
+ const defaultModel = await loadModel(harnessId, parent);
+ return await parent.run(() =>
+ caps.createAgent({
+ name,
+ handle: agentHandle(name),
+ description: `Runs ${name} on this computer with your own login.`,
+ harnessId,
+ defaultModel,
+ autoAcceptPermissions: choices.fullAccess,
+ })
+ );
};
- const finish = async (status: MacrodStatus, choices: SetupChoices) => {
- const agent = await attempt('agent', () => ensureAgent(status, choices));
+ const finish = async (
+ status: MacrodStatus,
+ choices: SetupChoices,
+ parent: Span
+ ) => {
+ const agent = await attempt('agent', parent, (span) =>
+ ensureAgent(status, choices, span)
+ );
if (agent.isErr()) return;
setState({
kind: 'ready',
@@ -165,7 +182,7 @@ export function createLocalRuntimeSetup(caps: SetupCapabilities) {
await span.run(async () => {
const status: Result<MacrodStatus, string> = connected
? ok(connected)
- : await connect(choices);
+ : await connect(choices, span);
if (status.isOk()) {
connected = status.value;
if (status.value.harnessId) {
@@ -174,7 +191,7 @@ export function createLocalRuntimeSetup(caps: SetupCapabilities) {
if (status.value.agentId) {
span.setAttr('local_runtime.agent', status.value.agentId);
}
- await finish(status.value, choices);
+ await finish(status.value, choices, span);
}
});
span.setAttr('local_runtime.outcome', state().kind);
diff --git a/apps/web/src/features/meetings/primitives/meeting-session.ts b/apps/web/src/features/meetings/primitives/meeting-session.ts
index 5e66475482..d8eb611b97 100644
--- a/apps/web/src/features/meetings/primitives/meeting-session.ts
+++ b/apps/web/src/features/meetings/primitives/meeting-session.ts
@@ -108,10 +108,14 @@ export function createMeetingSession(capabilities: MeetingSessionCapabilities) {
}
joinTrace.setAttr('meeting.join.outcome', 'cancelled');
try {
- await joinTrace.span('meeting.join.previous_session', async () => {
- await attemptLifecycle.previous;
- if (previousSession) await release(previousSession);
- });
+ await joinTrace.span(
+ 'meeting.join.previous_session',
+ async (previous) => {
+ await attemptLifecycle.previous;
+ if (previousSession)
+ await previous.run(() => release(previousSession));
+ }
+ );
if (disposed || attempt !== generation) return;
// A previous owner may still have been disconnecting when Join was
// clicked. Check the shared call state after its cleanup has finished.
@@ -135,7 +139,8 @@ export function createMeetingSession(capabilities: MeetingSessionCapabilities) {
shareToken,
};
if (disposed || attempt !== generation) {
- await release(issued);
+ const cancelledSession = issued;
+ await joinTrace.run(() => release(cancelledSession));
return;
}
issuedSession = issued;
@@ -170,7 +175,7 @@ export function createMeetingSession(capabilities: MeetingSessionCapabilities) {
issuedSession = undefined;
try {
if (capabilities.activeCallId() === issued.credentials.callId) {
- await capabilities.disconnect();
+ await joinTrace.run(() => capabilities.disconnect());
}
} catch (disconnectError) {
console.error(
@@ -178,7 +183,8 @@ export function createMeetingSession(capabilities: MeetingSessionCapabilities) {
disconnectError
);
} finally {
- await release(issued);
+ const cancelledSession = issued;
+ await joinTrace.run(() => release(cancelledSession));
}
}
if (disposed || attempt !== generation) return;
diff --git a/apps/web/src/features/next-soup/soup-view/soup-view.tsx b/apps/web/src/features/next-soup/soup-view/soup-view.tsx
index 2453bd8fa1..a8a83487f7 100644
--- a/apps/web/src/features/next-soup/soup-view/soup-view.tsx
+++ b/apps/web/src/features/next-soup/soup-view/soup-view.tsx
@@ -60,6 +60,7 @@ import {
SoupEntityContextMenu,
} from '@app/features/soup';
import { DEBUG_SETTING_KEYS, useDebugSetting } from '@app/lib/debugSettings';
+import { usePending } from '@app/observability/flow';
import { usePreference } from '@app/preferences/use-preference';
import { useGlobalNotificationSource } from '@components/app/GlobalAppState';
import { HeaderActionGroup } from '@components/app/HeaderActionGroup';
@@ -610,6 +611,9 @@ const SoupViewListContent = (props: SoupViewListProps) => {
isFetchingGroupPage,
groupPageError,
} = useSoupView();
+ usePending('list.items', source.isLoading);
+ usePending('list.search.remote', isSearchServiceLoading);
+ usePending('list.search.local', isLocalSearchSettling);
const { hasActiveRefinements, hasHiddenItems, resetToTabDefaults } =
useFilterRefinements();
diff --git a/apps/web/src/features/next-soup/utils.ts b/apps/web/src/features/next-soup/utils.ts
index 3bb75bfe7c..151458dcfe 100644
--- a/apps/web/src/features/next-soup/utils.ts
+++ b/apps/web/src/features/next-soup/utils.ts
@@ -27,6 +27,7 @@ import {
scopeChannelNotificationsForEntity,
} from '@app/features/soup/entity-notifications';
import { replacePaneSearchParams } from '@app/lib/split-router';
+import { beginInteraction } from '@app/observability/flow';
import { globalSplitManager } from '@app/signal/splitLayout';
import { CALENDAR_BLOCK_ID } from '@block-calendar/types';
import {
@@ -629,6 +630,22 @@ export const getRowClickFallbackLocation = (
export const openEntityInSplitFromUnifiedList = async (
entity: EntityData,
options: OpenEntityOptions
+): Promise<void> => {
+ // From the row action to the opened view's paint: the navigation it commits
+ // and the view it mounts join this interaction.
+ const interaction = beginInteraction('list.open', {
+ attributes: { 'entity.type': entity.type },
+ });
+ try {
+ await openEntity(entity, options);
+ } finally {
+ interaction.end();
+ }
+};
+
+const openEntity = async (
+ entity: EntityData,
+ options: OpenEntityOptions
): Promise<void> => {
const { allowDuplicate, openInNewSplit, splitHandle, mergeHistory } = options;
let { location } = options;
diff --git a/apps/web/src/features/notifications/tests/spreadsheet-comment-navigation.test.ts b/apps/web/src/features/notifications/tests/spreadsheet-comment-navigation.test.ts
index 13fa070149..444193ca5d 100644
--- a/apps/web/src/features/notifications/tests/spreadsheet-comment-navigation.test.ts
+++ b/apps/web/src/features/notifications/tests/spreadsheet-comment-navigation.test.ts
@@ -83,7 +83,9 @@ const traces = vi.hoisted(() => {
const spans: RecordedSpan[] = [];
return spans;
});
-vi.mock('@macro-inc/observability', () => {
+vi.mock('@macro-inc/observability', async (importOriginal) => {
+ const actual =
+ await importOriginal<typeof import('@macro-inc/observability')>();
async function runSpan<T>(
name: string,
parent: string | undefined,
@@ -113,7 +115,9 @@ vi.mock('@macro-inc/observability', () => {
}
}
return {
+ ...actual,
Telemetry: {
+ ...actual.Telemetry,
span: <T>(name: string, operation: (span: ObservedSpan) => Promise<T>) =>
runSpan(name, undefined, operation),
},
diff --git a/apps/web/src/features/reviews-view/reviews-view.tsx b/apps/web/src/features/reviews-view/reviews-view.tsx
index b2891f42fe..a2c8f3c9b5 100644
--- a/apps/web/src/features/reviews-view/reviews-view.tsx
+++ b/apps/web/src/features/reviews-view/reviews-view.tsx
@@ -17,6 +17,7 @@ import {
useNavigate,
useParams,
} from '@app/lib/split-router';
+import { usePending } from '@app/observability/flow';
import { reviewsPrRoute, reviewsSplitRoute } from '@app/routes/routes';
import { PR_ORIGIN_TOOLS } from '@block-pr/data/pr-origin';
import {
@@ -177,6 +178,7 @@ function ReviewsRoot() {
}),
listEnabled
);
+ usePending('reviews.items', source.isLoading);
const facets = useReviewsFacetsQuery();
const changeFilter = (
group: ReviewsFilterId,
diff --git a/apps/web/src/features/routines/queries/templates.ts b/apps/web/src/features/routines/queries/templates.ts
index 18a8a480a2..df1774ec7e 100644
--- a/apps/web/src/features/routines/queries/templates.ts
+++ b/apps/web/src/features/routines/queries/templates.ts
@@ -1,5 +1,6 @@
import { verifyBlockName } from '@core/constant/allBlocks';
import { throwOnErr } from '@core/util/result';
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
import { queryClient } from '@queries/client';
import {
getItemPreview,
@@ -75,6 +76,7 @@ function setTemplate(scheduleId: string, template: RoutineTemplate | null) {
export async function publishRoutineTemplate(
scheduleId: string
): Promise<RoutineTemplate> {
+ const parent = Telemetry.captureContext();
const [routine, shared] = await Promise.all([
queryClient.fetchQuery(routineQueryOptions(scheduleId)),
queryClient.fetchQuery(routineTemplateQueryOptions(scheduleId)),
@@ -85,7 +87,7 @@ export async function publishRoutineTemplate(
shared,
});
const template = await throwOnErr(() =>
- scheduledActionClient.shareTemplate({ scheduleId, body })
+ parent.run(() => scheduledActionClient.shareTemplate({ scheduleId, body }))
);
setTemplate(scheduleId, template);
return template;
@@ -108,12 +110,27 @@ export function useActivateTemplateMutation(
callbacks?: MutationCallbacks<
ScheduledAction,
Error,
- { templateId: string; body: ActionConfiguration }
+ {
+ templateId: string;
+ body: ActionConfiguration;
+ parentSpan?: TraceContext;
+ }
>
) {
return useMutation(() => ({
- mutationFn: (args: { templateId: string; body: ActionConfiguration }) =>
- throwOnErr(() => scheduledActionClient.activateTemplate(args)),
+ mutationFn: (args: {
+ templateId: string;
+ body: ActionConfiguration;
+ parentSpan?: TraceContext;
+ }) =>
+ (args.parentSpan ?? Telemetry.captureContext()).run(() =>
+ throwOnErr(() =>
+ scheduledActionClient.activateTemplate({
+ templateId: args.templateId,
+ body: args.body,
+ })
+ )
+ ),
...withCallbacks(
{
onSuccess: async (_routine, { templateId }) => {
@@ -127,7 +144,8 @@ export function useActivateTemplateMutation(
]);
},
},
- callbacks
+ callbacks,
+ (variables) => variables.parentSpan
),
}));
}
diff --git a/apps/web/src/features/routines/routine-template.tsx b/apps/web/src/features/routines/routine-template.tsx
index e16edc4c54..ac9804e1cb 100644
--- a/apps/web/src/features/routines/routine-template.tsx
+++ b/apps/web/src/features/routines/routine-template.tsx
@@ -127,6 +127,7 @@ function ActivateTemplate(
const routine = await mutation.mutateAsync({
templateId: props.template.id,
body,
+ parentSpan: span,
});
if (!routine.id) throw new Error('Activated routine has no ID');
span.setAttr('routine.id', routine.id);
diff --git a/apps/web/src/features/settings/Account.tsx b/apps/web/src/features/settings/Account.tsx
index 363a3fc39f..042fd7e268 100644
--- a/apps/web/src/features/settings/Account.tsx
+++ b/apps/web/src/features/settings/Account.tsx
@@ -1,6 +1,7 @@
import { useAnalytics } from '@app/lib/analytics/analytics-context';
import type { AccountDeletionReason } from '@app/lib/analytics/app-events';
import { useFeatureFlag } from '@app/lib/analytics/posthog';
+import { usePending } from '@app/observability/flow';
import { useHasPaidAccess } from '@core/auth';
import { useLogout } from '@core/auth/logout';
import { toast } from '@core/component/Toast/Toast';
@@ -320,6 +321,7 @@ function AccountPlanCard() {
const { openSettings } = useSettingsState();
const hasPaid = useHasPaidAccess();
const summary = useAiBillingSummaryQuery();
+ usePending('settings.plan', () => summary.isLoading);
// Wait for the summary before falling back to the license, so a Max plan
// doesn't flash as Pro while it loads.
const tier = () =>
diff --git a/apps/web/src/features/settings/Email.tsx b/apps/web/src/features/settings/Email.tsx
index b7303b7cb8..2c2839569e 100644
--- a/apps/web/src/features/settings/Email.tsx
+++ b/apps/web/src/features/settings/Email.tsx
@@ -73,7 +73,7 @@ export function useConnectInbox(): (provider?: EmailProvider) => void {
toast.failure('New Outlook connections are temporarily unavailable.');
return;
}
- await startAddInbox({ provider });
+ await span.run(() => startAddInbox({ provider }));
span.setAttr('email.link.outcome', 'started');
} finally {
addingInbox = false;
diff --git a/apps/web/src/features/universal-input/browser-test/command-input.browser.e2e.ts b/apps/web/src/features/universal-input/browser-test/command-input.browser.e2e.ts
index 01dfb8828a..39897bb571 100644
--- a/apps/web/src/features/universal-input/browser-test/command-input.browser.e2e.ts
+++ b/apps/web/src/features/universal-input/browser-test/command-input.browser.e2e.ts
@@ -342,3 +342,99 @@ test('Escape closes the calendar date picker before the Command K composer', asy
page.getByRole('textbox', { name: 'Your input', exact: true })
).toBeVisible();
});
+
+test('rapid search inputs cancel old flows and hold the latest through debounce', async ({
+ page,
+}) => {
+ const spans: {
+ name: string;
+ traceId: string;
+ spanId: string;
+ parentSpanId?: string;
+ startTimeUnixNano: string;
+ endTimeUnixNano: string;
+ attributes: {
+ key: string;
+ value: { stringValue?: string; intValue?: string };
+ }[];
+ }[] = [];
+ await page.route('**/traces', async (route) => {
+ const data = route.request().postDataJSON();
+ for (const resource of data.resourceSpans ?? [])
+ for (const scope of resource.scopeSpans ?? []) spans.push(...scope.spans);
+ await route.fulfill({ json: {} });
+ });
+ await page.goto('/?command-menu&trace');
+ await page
+ .getByRole('button', { name: 'Open Command K', exact: true })
+ .click();
+ const input = page.getByPlaceholder('Search...', { exact: true });
+ // Dispatch in one task: the debounce is continuously pending across keys.
+ await input.evaluate((element) => {
+ if (!(element instanceof HTMLTextAreaElement))
+ throw new Error('Expected search textarea');
+ for (const value of ['p', 'pr', 'project']) {
+ element.value = value;
+ element.dispatchEvent(
+ new InputEvent('input', { bubbles: true, data: value })
+ );
+ }
+ });
+ await expect(input).toHaveValue('project');
+ await expect
+ .poll(
+ () => spans.filter((span) => span.name === 'quick_access.input').length,
+ { timeout: 15000 }
+ )
+ .toBe(3);
+ const inputs = spans.filter((span) => span.name === 'quick_access.input');
+ const latest = inputs.find((span) =>
+ span.attributes.some(
+ (attr) =>
+ attr.key === 'search.query_length' && Number(attr.value.intValue) === 7
+ )
+ );
+ expect(latest).toBeDefined();
+ expect(
+ spans.some(
+ (span) =>
+ span.name === 'quick_access.debounce' &&
+ span.traceId === latest!.traceId
+ )
+ ).toBe(true);
+ expect(
+ spans.some(
+ (span) =>
+ span.name === 'quick_access.results' && span.traceId === latest!.traceId
+ )
+ ).toBe(true);
+ const results = spans.filter((span) => span.name === 'quick_access.results');
+ expect(
+ results.filter((span) =>
+ span.attributes.some(
+ (attr) =>
+ attr.key === 'flow.outcome' && attr.value.stringValue === 'cancelled'
+ )
+ ).length
+ ).toBeGreaterThanOrEqual(2);
+ const latestResults = results.find(
+ (span) => span.parentSpanId === latest!.spanId
+ );
+ expect(latestResults).toBeDefined();
+ const debounce = spans.find(
+ (span) =>
+ span.name === 'quick_access.debounce' &&
+ span.parentSpanId === latestResults!.spanId
+ );
+ expect(debounce).toBeDefined();
+ expect(
+ (Number(debounce!.endTimeUnixNano) - Number(debounce!.startTimeUnixNano)) /
+ 1e6
+ ).toBeGreaterThanOrEqual(50);
+ await test.info().attach('rapid-input-traces', {
+ body: JSON.stringify(spans, null, 2),
+ contentType: 'application/json',
+ });
+ await page.keyboard.press('Escape');
+ await expect(page.getByRole('dialog')).toHaveCount(0);
+});
diff --git a/apps/web/src/features/universal-input/browser-test/main.tsx b/apps/web/src/features/universal-input/browser-test/main.tsx
index d770f1e6bf..7de55e4390 100644
--- a/apps/web/src/features/universal-input/browser-test/main.tsx
+++ b/apps/web/src/features/universal-input/browser-test/main.tsx
@@ -1,8 +1,30 @@
+import { initializeUiOperationTelemetry } from '@app/observability/ui-operation';
import { UserMention } from '@core/component/LexicalMarkdown/component/decorator/UserMention';
import { setDecorator, UserMentionNode } from '@macro-inc/lexical-core';
+import { Telemetry } from '@macro-inc/observability';
+import {
+ createWebTracingProvider,
+ StackContextManager,
+} from '@macro-inc/observability/web';
import { render } from 'solid-js/web';
import { UniversalInputFixture } from './fixture';
+if (new URLSearchParams(location.search).has('trace')) {
+ const config = {
+ serviceName: 'command-fixture',
+ environment: 'test',
+ tracesUrl: `${location.origin}/traces`,
+ contextManager: new StackContextManager(),
+ enabled: async () => true,
+ };
+ initializeUiOperationTelemetry();
+ await Telemetry.init({
+ ...config,
+ tracingProvider: (resource, getUserId, sampling) =>
+ createWebTracingProvider(config, resource, getUserId, sampling),
+ });
+}
+
setDecorator(UserMentionNode, UserMention);
render(() => <UniversalInputFixture />, document.getElementById('root')!);
diff --git a/apps/web/src/lib/core/agent-session/AgentSession.ts b/apps/web/src/lib/core/agent-session/AgentSession.ts
index 21616bd8f2..4bac5514d4 100644
--- a/apps/web/src/lib/core/agent-session/AgentSession.ts
+++ b/apps/web/src/lib/core/agent-session/AgentSession.ts
@@ -948,7 +948,23 @@ export class AgentSession {
prompt.observe(events, delivery);
if (prompt.ended) this.prompts.delete(prompt);
}
+ const projectionStartedAt = performance.now();
for (const listener of this.listeners) listener(events);
+ if (snapshot) {
+ this.trace.projected(
+ projectionStartedAt,
+ events.reduce(
+ (count, event) =>
+ count +
+ (event.kind === 'metadata'
+ ? 0
+ : event.kind === 'replace'
+ ? event.messages.length
+ : 1),
+ 0
+ )
+ );
+ }
});
// A failed push must not poison the chain for every input after it.
this.chain = run.catch((error: unknown) => {
diff --git a/apps/web/src/lib/core/agent-session/load-telemetry.ts b/apps/web/src/lib/core/agent-session/load-telemetry.ts
index 25c1dc34e2..6f96ea71ae 100644
--- a/apps/web/src/lib/core/agent-session/load-telemetry.ts
+++ b/apps/web/src/lib/core/agent-session/load-telemetry.ts
@@ -93,6 +93,8 @@ export type LoadStage =
| 'log_fetch'
/** The fetched log was folded; the surface can show the truth. */
| 'fold'
+ /** Snapshot events were projected into the surface's stores. */
+ | 'projection'
/** A surface painted the cached transcript. */
| 'warm_render'
/** A surface painted the fetched transcript. */
@@ -232,6 +234,12 @@ export class SessionLoadTrace {
this.stage('fold', foldStartedAt);
}
+ /** Listener projection is synchronous work inside the historical fold stage. */
+ projected(startedAt: number, messages: number): void {
+ if (this.#ended) return;
+ this.stage('projection', startedAt, { projection_messages: messages });
+ }
+
/**
* The read was refused and tried again, because this tab had created the
* session moments earlier and the refusal reads as a create that has not
diff --git a/apps/web/src/lib/core/auth/logout.test.ts b/apps/web/src/lib/core/auth/logout.test.ts
index a57cd28eea..351d005ea3 100644
--- a/apps/web/src/lib/core/auth/logout.test.ts
+++ b/apps/web/src/lib/core/auth/logout.test.ts
@@ -34,7 +34,8 @@ vi.mock('@queries/email/send-queue', () => ({
vi.mock('@queries/email/outbox-session', () => ({
setEmailOutboxSession: vi.fn(),
}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'auth-logout': 'https://auth.example.com/oauth2/logout' },
}));
vi.mock('@core/util/platform', async (importOriginal) => ({
diff --git a/apps/web/src/lib/core/auth/session-refresh.ts b/apps/web/src/lib/core/auth/session-refresh.ts
new file mode 100644
index 0000000000..bf88ceee87
--- /dev/null
+++ b/apps/web/src/lib/core/auth/session-refresh.ts
@@ -0,0 +1,170 @@
+import { perfMark } from '@app/observability/perf-marks';
+import { SERVER_HOSTS } from '@core/constant/servers';
+import { err, ok, type Result } from 'neverthrow';
+import type { ResultError } from '../util/result';
+import {
+ type BaseFetchErrorCode,
+ type ErrorResponseHandler,
+ safeFetch,
+} from '../util/safeFetch';
+
+type TokenResult = Result<void, ResultError<BaseFetchErrorCode>[]>;
+
+let tokenPromise: Promise<TokenResult> | null = null;
+let refreshedAt: number | undefined;
+// Proactive socket setup can reuse a just-refreshed cookie. A server 401 must
+// always force a new refresh, regardless of this short reuse window.
+const RECENT_SESSION_REFRESH_MS = 30_000;
+
+// Once /jwt/refresh definitively rejects the session, cache that failure so
+// subsequent 401s short-circuit instead of each firing another doomed refresh.
+// An anonymous visitor on a public link otherwise triggers one refresh per
+// authenticated app-chrome query. Only a definitive rejection latches:
+// transient failures (proxy errors, outages) must never be remembered as
+// "logged out". Cleared by unsetTokenPromise on login, by TTL expiry, and when
+// the app regains visibility/connectivity — on native the webview lives for
+// days without a reload, so a permanent latch turns one bad response into a
+// forced re-login.
+let refreshUnavailable: TokenResult | null = null;
+let refreshUnavailableAt = 0;
+const REFRESH_UNAVAILABLE_TTL_MS = 60_000;
+
+// Bumped on every reset. A refresh started before a reset carries the older
+// generation, so once the session has moved on (e.g. a login) it can neither
+// re-latch refreshUnavailable nor clear a newer tokenPromise on completion.
+let refreshGeneration = 0;
+
+function clearRefreshLatch() {
+ refreshUnavailable = null;
+}
+
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+ window.addEventListener('online', clearRefreshLatch);
+ document.addEventListener('visibilitychange', () => {
+ if (document.visibilityState === 'visible') clearRefreshLatch();
+ });
+}
+
+// The auth service's definitive "this session cannot be refreshed" bodies
+// (RefreshError and the token-extraction middleware in authentication_service
+// return these as text/plain 400s). Any other non-2xx on /jwt/refresh — proxy
+// 400s, 408/429, 5xx — is transient and must not latch.
+const REFRESH_REJECTED_BODIES = new Set([
+ 'invalid refresh token',
+ 'no access token to refresh',
+ 'no refresh token to refresh',
+]);
+
+const classifyRefreshError: ErrorResponseHandler<never> = async (response) => {
+ if (response.status === 401) {
+ return { code: 'UNAUTHORIZED', message: 'Unauthorized access' };
+ }
+ if (response.status === 400) {
+ let body = '';
+ try {
+ body = (await response.text()).trim();
+ } catch {}
+ if (REFRESH_REJECTED_BODIES.has(body)) {
+ return { code: 'UNAUTHORIZED', message: body };
+ }
+ }
+ return {
+ code: 'HTTP_ERROR',
+ message: `HTTP error! status: ${response.status}`,
+ };
+};
+
+/**
+ * Proactive session setup shares a recent successful refresh. Authentication
+ * failures must call fetchToken directly so a 401 always reaches the server.
+ */
+export async function ensureFreshSession(): Promise<TokenResult> {
+ if (tokenPromise) return tokenPromise;
+ const age = refreshedAt === undefined ? undefined : Date.now() - refreshedAt;
+ if (age !== undefined && age >= 0 && age < RECENT_SESSION_REFRESH_MS) {
+ return ok(undefined);
+ }
+ return fetchToken();
+}
+
+/** Force a refresh after a server rejects the current credentials. */
+export async function fetchToken(): Promise<TokenResult> {
+ if (refreshUnavailable != null) {
+ if (Date.now() - refreshUnavailableAt < REFRESH_UNAVAILABLE_TTL_MS) {
+ return refreshUnavailable;
+ }
+ refreshUnavailable = null;
+ }
+ if (tokenPromise == null) {
+ const generation = refreshGeneration;
+ refreshedAt = undefined;
+ tokenPromise = (async () => {
+ perfMark('auth.refresh-start', { generation });
+ try {
+ const result = await safeFetch(
+ `${SERVER_HOSTS['auth-service']}/jwt/refresh`,
+ {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ Accept: 'application/json',
+ },
+ cache: 'no-store',
+ credentials: 'include',
+ },
+ classifyRefreshError
+ );
+
+ perfMark('auth.refresh-end', { generation, ok: result.isOk() });
+ if (result.isErr()) {
+ const failure = err(result.error);
+ if (
+ generation === refreshGeneration &&
+ result.error.some((e) => e.code === 'UNAUTHORIZED')
+ ) {
+ refreshUnavailable = failure;
+ refreshUnavailableAt = Date.now();
+ }
+ return failure;
+ }
+
+ if (generation === refreshGeneration) refreshedAt = Date.now();
+ return ok(undefined);
+ } finally {
+ if (generation === refreshGeneration) {
+ tokenPromise = null;
+ }
+ }
+ })();
+ }
+ return tokenPromise;
+}
+
+/**
+ * Bypasses any latched refresh failure and asks the auth service directly
+ * whether the session can still be refreshed. Returns true only on a
+ * definitive rejection. Callers about to destroy local session state must use
+ * this instead of trusting a possibly-stale latched UNAUTHORIZED.
+ */
+export async function confirmSessionExpired(): Promise<boolean> {
+ refreshUnavailable = null;
+ const result = await fetchToken();
+ return result.isErr() && result.error.some((e) => e.code === 'UNAUTHORIZED');
+}
+
+/**
+ * Unsets the token promise, forcing a new token to be fetched on the next request.
+ * This can be useful in situations where you know the token has become invalid.
+ *
+ * @example
+ * import { unsetTokenPromise } from './path-to-this-module';
+ *
+ * // After logging out the user
+ * unsetTokenPromise();
+ */
+export function unsetTokenPromise() {
+ refreshedAt = undefined;
+ refreshGeneration++;
+ tokenPromise = null;
+ refreshUnavailable = null;
+}
diff --git a/apps/web/src/lib/core/block.ts b/apps/web/src/lib/core/block.ts
index 15f20aecd6..806a3e7fce 100644
--- a/apps/web/src/lib/core/block.ts
+++ b/apps/web/src/lib/core/block.ts
@@ -8,6 +8,7 @@ import type {
LiveSyncSource,
SyncError,
} from '@macro-inc/collaboration/collab/source';
+import type { Span } from '@macro-inc/observability';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
import type { GetDocumentResponseData } from '@service-storage/generated/schemas/getDocumentResponseData';
@@ -293,7 +294,8 @@ export type LoadFunction<
S extends Source | P = Source | P,
> = (
source: NoInfer<S>,
- intent: Intent
+ intent: Intent,
+ parentSpan?: Span
) => Promise<
Result<S extends Source ? T | P : T, ResultError<keyof typeof LoadErrors>[]>
>;
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx
index 6781d15b6c..6e2a1c5b1c 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/collaboration/CollabProvider.tsx
@@ -72,14 +72,6 @@ import {
type MutatedNodes = UpdateListenerPayload['mutatedNodes'];
-/** Hooks into the caller's tracing, all optional. */
-export type CollabObservability = {
- /** Resume the caller's open span for this session id, if any. */
- resumeSpan?: (id: string) => Span | undefined;
- /** End the caller's span for this session id. */
- endSpan?: (id: string) => void;
-};
-
export type CollabProviderProps = {
editor: LexicalEditor;
pluginManager: PluginManager;
@@ -106,7 +98,8 @@ export type CollabProviderProps = {
canComment: Accessor<boolean | undefined>;
/** External error state; the engine stops when it becomes non-null. */
editorError: Accessor<MarkdownEditorErrors | null>;
- observability?: CollabObservability;
+ /** Caller-owned load context; the provider never ends it. */
+ span?: Span;
/** Optional status UI (e.g. the md block's CollabStatus chrome). */
statusChrome?: JSX.Element;
};
@@ -134,10 +127,6 @@ export function CollabProvider(props: CollabProviderProps) {
if (!syncSource()) return null;
- const resumeSpan = (id: string): Span | undefined =>
- props.observability?.resumeSpan?.(id);
- const endSpan = (id: string): void => props.observability?.endSpan?.(id);
-
const awareness = createAwareness(
loroManager.peerIdStr,
userId(),
@@ -152,6 +141,7 @@ export function CollabProvider(props: CollabProviderProps) {
const walSyncer = createWALSyncSource(syncSource()!);
const syncEngine = createSyncEngine({
loroManager,
+ parentSpan: props.span,
awareness,
syncs: { wal: walSyncer, live: syncSource()! },
bindings: {
@@ -509,7 +499,7 @@ export function CollabProvider(props: CollabProviderProps) {
message:
'editor init: no state from loroManager — editor will NOT become ready (skeleton stays)',
});
- endSpan(syncSource()!.documentId);
+ props.span?.error('Editor initial state is missing');
return;
}
@@ -551,8 +541,8 @@ export function CollabProvider(props: CollabProviderProps) {
message:
'editor init: initializeEditorWithVersionedState failed',
});
+ props.span?.error('Editor initialization failed');
props.setEditorError(initError);
- endSpan(syncSource()!.documentId);
return;
}
}
@@ -564,9 +554,7 @@ export function CollabProvider(props: CollabProviderProps) {
props.editor.dispatchCommand(FORCE_SYNC_COMMAND, undefined);
}
props.setEditorReady(true);
- const documentId = syncSource()!.documentId;
- resumeSpan(documentId)?.event('editor.ready');
- endSpan(documentId);
+ props.span?.event('editor.ready');
logSyncService({
documentId: syncSource()!.documentId,
level: 'info',
@@ -597,8 +585,6 @@ export function CollabProvider(props: CollabProviderProps) {
onCleanup(() => {
syncEngine.stop();
walSyncer.destroy();
- const documentId = syncSource()?.documentId;
- if (documentId) endSpan(documentId);
});
return (
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts
index 292931a735..a60497fd26 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts
@@ -250,7 +250,7 @@ async function handleRoutineMention(
const { publishRoutineTemplate } = await import(
'@app/features/routines/queries/templates'
);
- await publishRoutineTemplate(routine.id);
+ await span.run(() => publishRoutineTemplate(routine.id));
return true;
} catch {
span.error('Sharing the routine failed');
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.test.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.test.ts
new file mode 100644
index 0000000000..f4a6e1afc6
--- /dev/null
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.test.ts
@@ -0,0 +1,20 @@
+import { initializePlatformFetch } from '@core/util/platformFetch';
+import { expect, it, vi } from 'vitest';
+import { fetchTrendingGifs, searchGifs } from './klipy';
+
+it('sends public GIF requests directly through the browser transport', async () => {
+ const browser = vi
+ .fn<typeof fetch>()
+ .mockImplementation(async () => Response.json({ results: [] }));
+ const native = vi.fn<typeof fetch>();
+ initializePlatformFetch(browser);
+ vi.stubGlobal('fetch', native);
+ try {
+ await fetchTrendingGifs();
+ await searchGifs('example');
+ expect(browser).toHaveBeenCalledTimes(2);
+ expect(native).not.toHaveBeenCalled();
+ } finally {
+ vi.unstubAllGlobals();
+ }
+});
diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.ts
index 2c0c0c9dbf..36ad3bfae7 100644
--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.ts
+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/gif/klipy.ts
@@ -1,3 +1,4 @@
+import { webviewFetch } from '@core/util/platformFetch';
import { z } from 'zod';
// Klipy keys are meant to ship in the client: its terms require requests to
@@ -62,7 +63,7 @@ async function fetchGifs(
contentfilter: CONTENT_FILTER,
...params,
});
- const response = await fetch(`${KLIPY_BASE_URL}/${endpoint}?${query}`);
+ const response = await webviewFetch(`${KLIPY_BASE_URL}/${endpoint}?${query}`);
if (!response.ok) {
throw new Error(`Klipy API error: ${response.status}`);
}
diff --git a/apps/web/src/lib/core/constant/developmentProxy.ts b/apps/web/src/lib/core/constant/developmentProxy.ts
index cb3ec6e002..5df1db1af9 100644
--- a/apps/web/src/lib/core/constant/developmentProxy.ts
+++ b/apps/web/src/lib/core/constant/developmentProxy.ts
@@ -6,6 +6,8 @@ export const DEVELOPMENT_PROXY_TARGETS = {
pdf: 'https://pdf-service-dev.macro.com',
sync: 'https://sync-service-dev3.macroverse.workers.dev',
editing: 'https://ai-editing-worker-dev.macroverse.workers.dev',
+ // The machine's local LGTM collector (`just run_local` starts it).
+ otlp: 'http://localhost:4318',
} as const;
export const DEVELOPMENT_PROXY_PREFIX = '/__macro_dev';
diff --git a/apps/web/src/lib/core/constant/servers.ts b/apps/web/src/lib/core/constant/servers.ts
index 4d942fcce0..8f6190d706 100644
--- a/apps/web/src/lib/core/constant/servers.ts
+++ b/apps/web/src/lib/core/constant/servers.ts
@@ -217,6 +217,28 @@ function selectSyncServiceHost():
export const SYNC_SERVICE_HOSTS = selectSyncServiceHost();
+// Desktop HTTP services share the native session cookie jar. Navigation-only
+// destinations and WebSocket endpoints do not define HTTP transport prefixes.
+const nativeSessionServices = {
+ 'auth-service': SERVER_HOSTS['auth-service'],
+ 'auth-logout': undefined,
+ 'pdf-service': SERVER_HOSTS['pdf-service'],
+ 'document-storage-service': SERVER_HOSTS['document-storage-service'],
+ 'websocket-service': undefined,
+ 'cognition-service': SERVER_HOSTS['cognition-service'],
+ 'connection-gateway': undefined,
+ 'notification-service': SERVER_HOSTS['notification-service'],
+ 'static-file': SERVER_HOSTS['static-file'],
+ 'unfurl-service': SERVER_HOSTS['unfurl-service'],
+ contacts: SERVER_HOSTS['contacts'],
+ 'email-service': SERVER_HOSTS['email-service'],
+ 'calendar-service': SERVER_HOSTS['calendar-service'],
+ 'image-proxy-service': SERVER_HOSTS['image-proxy-service'],
+ 'scheduled-action': SERVER_HOSTS['scheduled-action'],
+ 'agent-harness': SERVER_HOSTS['agent-harness'],
+ preview: SERVER_HOSTS['preview'],
+} satisfies Record<keyof Servers, string | undefined>;
+
/**
* The DSS host to use for sync-service permission tokens.
* When the sync service is remote, permission tokens must come from the remote DSS
@@ -227,6 +249,12 @@ export const SYNC_PERMISSION_TOKEN_DSS_HOST =
? serverHostRemote['document-storage-service']
: SERVER_HOSTS['document-storage-service'];
+export const NATIVE_SESSION_SERVICE_URLS = [
+ ...Object.values(nativeSessionServices).filter((url) => url !== undefined),
+ SYNC_SERVICE_HOSTS.worker,
+ SYNC_PERMISSION_TOKEN_DSS_HOST,
+];
+
/** Hosts the email service may have embedded in sent mail. Development
* proxies rewrite `SERVER_HOSTS`, while the backend embeds its direct URL. */
export const EMAIL_SERVICE_EMBEDDED_HOSTS: readonly string[] = [
diff --git a/apps/web/src/lib/core/context/quickAccess/projected-list.ts b/apps/web/src/lib/core/context/quickAccess/projected-list.ts
index 32aa82eb01..0d0ade0f97 100644
--- a/apps/web/src/lib/core/context/quickAccess/projected-list.ts
+++ b/apps/web/src/lib/core/context/quickAccess/projected-list.ts
@@ -167,6 +167,8 @@ export function createProjectedList<T extends { id: string }>(options: {
fetchedPages < pageBudget &&
(pageCount > 0 || !foundNewRow)
);
+ span.setAttr('search.page_count', fetchedPages);
+ span.setAttr('search.materialized_count', merged.size);
request.cursor = cursor;
request.pages = pages;
setError(undefined);
diff --git a/apps/web/src/lib/core/internal/BlockLoader.test.tsx b/apps/web/src/lib/core/internal/BlockLoader.test.tsx
index be5430465e..0ffdb9088a 100644
--- a/apps/web/src/lib/core/internal/BlockLoader.test.tsx
+++ b/apps/web/src/lib/core/internal/BlockLoader.test.tsx
@@ -1,7 +1,9 @@
+import { TraceFlow, useFlow } from '@app/observability/flow';
+import { initializeUiOperationTelemetry } from '@app/observability/ui-operation';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import { cleanup, fireEvent, render } from '@solidjs/testing-library';
import { err, ok } from 'neverthrow';
-import { createEffect, createSignal, on, Show } from 'solid-js';
+import { createEffect, createSignal, lazy, on, Show } from 'solid-js';
import { afterEach, beforeEach, expect, it, vi } from 'vitest';
vi.mock('@core/context/user', () => ({ useIsAuthenticated: () => () => true }));
@@ -51,8 +53,14 @@ import {
} from '../signal/load';
import { BlockLoader, blockDataSignal } from './BlockLoader';
-afterEach(cleanup);
+let disposeTelemetry: (() => void) | undefined;
+afterEach(() => {
+ cleanup();
+ disposeTelemetry?.();
+ vi.restoreAllMocks();
+});
beforeEach(() => {
+ disposeTelemetry = initializeUiOperationTelemetry();
nested = true;
analytics.track.mockClear();
analytics.pageView.mockClear();
@@ -410,3 +418,53 @@ it('reports no open for a block without open history by default', async () => {
);
expect(analytics.pageView).not.toHaveBeenCalled();
});
+
+it('holds the enclosing view until both data and component code are ready', async () => {
+ const data = Promise.withResolvers<{ id: string }>();
+ const code = Promise.withResolvers<void>();
+ const published = Promise.withResolvers<void>();
+ const settled = Promise.withResolvers<void>();
+ const ready = vi.fn(() => settled.resolve());
+ function ObserveReady() {
+ const span = useFlow().span;
+ const setAttr = span.setAttr.bind(span);
+ vi.spyOn(span, 'setAttr').mockImplementation((key, value) => {
+ setAttr(key, value);
+ if (key === 'ui.work_to_ready_ms') ready();
+ });
+ return null;
+ }
+ render(() => {
+ createEffect(() => {
+ if (blockDataSignal.get()) published.resolve();
+ });
+ return (
+ <TraceFlow name="view.document">
+ <ObserveReady />
+ <BlockLoader
+ id="document"
+ source={{ type: 'dss', id: 'document' }}
+ definition={{
+ name: 'email',
+ description: 'Email',
+ accepted: {},
+ component: lazy(async () => {
+ await code.promise;
+ return { default: () => null };
+ }),
+ load: async () => ok(await data.promise),
+ }}
+ />
+ </TraceFlow>
+ );
+ });
+ await Promise.resolve();
+ expect(ready).not.toHaveBeenCalled();
+ data.resolve({ id: 'document' });
+ await Promise.resolve();
+ expect(ready).not.toHaveBeenCalled();
+ code.resolve();
+ await published.promise;
+ await settled.promise;
+ expect(ready).toHaveBeenCalledOnce();
+});
diff --git a/apps/web/src/lib/core/internal/BlockLoader.tsx b/apps/web/src/lib/core/internal/BlockLoader.tsx
index b04a43decb..9494ece63e 100644
--- a/apps/web/src/lib/core/internal/BlockLoader.tsx
+++ b/apps/web/src/lib/core/internal/BlockLoader.tsx
@@ -1,6 +1,7 @@
import { useSharedAccessUpdates } from '@app/features/access-requests/access-requests';
import { shareEntity } from '@app/features/access-requests/core/types';
import { useAnalytics } from '@app/lib/analytics/analytics-context';
+import { useFlow, usePending } from '@app/observability/flow';
import { useIsAuthenticated } from '@core/context/user';
import type { OwnedBlockHandle } from '@core/orchestrator';
import { Telemetry } from '@macro-inc/observability';
@@ -57,6 +58,11 @@ export function BlockLoader<
T extends BlockDefinition<D, BlockName, P, L>,
>(props: BlockLoaderProps<D, P, L, T>): JSX.Element {
const authenticated = useIsAuthenticated();
+ const flow = useFlow();
+ usePending(
+ 'block.publish',
+ () => !blockDataSignal.get() && !blockErrorSignal.get()
+ );
const setData = blockDataSignal.set;
const setError = blockErrorSignal.set;
const setLiveTrackingEnabled = blockLiveTrackingEnabledSignal.set;
@@ -126,7 +132,18 @@ export function BlockLoader<
// Tracked before the first await so a failure view can re-run the load.
retryToken();
const result = await loadBlockDataAfterComponentPreload(
- () => props.definition.load(props.source, 'initial'),
+ () =>
+ flow.task('block.data', async (span) => {
+ span.setAttr('block.type', props.definition.name);
+ span.setAttr('document.id', props.id);
+ const result = await props.definition.load(
+ props.source,
+ 'initial',
+ span
+ );
+ if (result.isErr()) span.error('Block data could not load');
+ return result;
+ }),
props.definition.component.preload
);
if (result.isErr()) {
diff --git a/apps/web/src/lib/core/util/fetchWithToken-tracing.test.ts b/apps/web/src/lib/core/util/fetchWithToken-tracing.test.ts
new file mode 100644
index 0000000000..890e247b0e
--- /dev/null
+++ b/apps/web/src/lib/core/util/fetchWithToken-tracing.test.ts
@@ -0,0 +1,119 @@
+import { type Span, Telemetry } from '@macro-inc/observability';
+import { StackContextManager } from '@macro-inc/observability/web';
+import { context, propagation, trace } from '@opentelemetry/api';
+import { W3CTraceContextPropagator } from '@opentelemetry/core';
+import {
+ BasicTracerProvider,
+ InMemorySpanExporter,
+ SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { withCallbacks } from '@queries/utils';
+import { MutationObserver, QueryClient } from '@tanstack/query-core';
+import { afterEach, beforeAll, expect, it, vi } from 'vitest';
+import { fetchWithToken, unsetTokenPromise } from './fetchWithToken';
+
+context.setGlobalContextManager(new StackContextManager().enable());
+propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+const exporter = new InMemorySpanExporter();
+trace.setGlobalTracerProvider(
+ new BasicTracerProvider({
+ spanProcessors: [new SimpleSpanProcessor(exporter)],
+ })
+);
+beforeAll(() =>
+ Telemetry.init({
+ serviceName: 'test',
+ environment: 'test',
+ enabled: async () => true,
+ })
+);
+afterEach(() => {
+ vi.unstubAllGlobals();
+ unsetTokenPromise();
+ exporter.reset();
+});
+
+it('keeps a refresh and retried request under the admitted action with synchronous context', async () => {
+ unsetTokenPromise();
+ const request = vi
+ .fn<typeof fetch>()
+ .mockResolvedValueOnce(Response.json({}, { status: 401 }))
+ .mockResolvedValueOnce(Response.json({}))
+ .mockResolvedValueOnce(Response.json({ saved: true }));
+ vi.stubGlobal('fetch', request);
+ const action = Telemetry.span('save.action');
+ const pending = action.run(() =>
+ fetchWithToken(`${window.location.origin}/resource`)
+ );
+ const other = Telemetry.span('unrelated.action');
+ other.run(() => Telemetry.span('unrelated.child').end());
+ other.end();
+ expect((await pending).isOk()).toBe(true);
+ action.end();
+ expect(request).toHaveBeenCalledTimes(3);
+ const spans = exporter.getFinishedSpans();
+ const root = spans.find((span) => span.name === 'save.action')!;
+ const requests = spans.filter((span) => span.name.startsWith('http '));
+ expect(requests).toHaveLength(3);
+ for (const span of requests) {
+ expect(span.parentSpanContext?.spanId).toBe(root.spanContext().spanId);
+ expect(span.spanContext().traceId).toBe(root.spanContext().traceId);
+ }
+ const resources = request.mock.calls.filter(([url]) =>
+ String(url).endsWith('/resource')
+ );
+ expect(resources).toHaveLength(2);
+ for (const [, init] of resources) {
+ expect(new Headers(init?.headers).get('traceparent')?.split('-')[1]).toBe(
+ root.spanContext().traceId
+ );
+ }
+});
+
+it('restores a queued mutation parent for default and override callbacks after awaits', async () => {
+ const client = new QueryClient();
+ type Input = { parentSpan: Span };
+ const observer = new MutationObserver(client, {
+ mutationFn: async (input: Input) =>
+ input.parentSpan.run(() =>
+ Telemetry.span('mutation.request', async () => 42)
+ ),
+ ...withCallbacks<number, Error, Input>(
+ {
+ onSuccess: async () => {
+ await Promise.resolve();
+ Telemetry.span('default.local').end();
+ },
+ },
+ {
+ onSuccess: () => {
+ Telemetry.span('override.refresh').end();
+ },
+ onSettled: () => {
+ Telemetry.span('settled.refresh').end();
+ },
+ },
+ (input) => input.parentSpan
+ ),
+ });
+ const root = Telemetry.span('mutation.action');
+ expect(await observer.mutate({ parentSpan: root })).toBe(42);
+ root.end();
+ const spans = exporter.getFinishedSpans();
+ const action = spans.find((span) => span.name === 'mutation.action')!;
+ for (const name of [
+ 'mutation.request',
+ 'override.refresh',
+ 'settled.refresh',
+ ]) {
+ expect(
+ spans.find((span) => span.name === name)?.parentSpanContext?.spanId
+ ).toBe(action.spanContext().spanId);
+ }
+ // A callback's own continuation still needs an explicit parent; the helper
+ // guarantees callback admission, without patching async execution.
+ expect(
+ spans.find((span) => span.name === 'default.local')?.parentSpanContext
+ ).toBeUndefined();
+ client.clear();
+});
diff --git a/apps/web/src/lib/core/util/fetchWithToken.spec.ts b/apps/web/src/lib/core/util/fetchWithToken.spec.ts
index 8d3b7c0ce0..eb115a581f 100644
--- a/apps/web/src/lib/core/util/fetchWithToken.spec.ts
+++ b/apps/web/src/lib/core/util/fetchWithToken.spec.ts
@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import {
confirmSessionExpired,
+ ensureFreshSession,
fetchToken,
fetchWithToken,
unsetTokenPromise,
@@ -67,6 +68,56 @@ describe('fetchWithToken refresh latch', () => {
const refreshCalls = () =>
mockFetch.mock.calls.filter(([input]) => isRefresh(input)).length;
+ test('reuses a recent successful refresh only for proactive socket setup', async () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(100_000);
+ mockFetch.mockResolvedValue(jsonResponse(200));
+ await fetchToken();
+ await ensureFreshSession();
+ await ensureFreshSession();
+ expect(refreshCalls()).toBe(1);
+ await fetchToken();
+ expect(refreshCalls()).toBe(2);
+ vi.setSystemTime(130_000);
+ await ensureFreshSession();
+ expect(refreshCalls()).toBe(3);
+ unsetTokenPromise();
+ await ensureFreshSession();
+ expect(refreshCalls()).toBe(4);
+ });
+
+ test('does not reuse a refresh after the clock moves backwards', async () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(100_000);
+ mockFetch.mockResolvedValue(jsonResponse(200));
+ await ensureFreshSession();
+ vi.setSystemTime(90_000);
+ await ensureFreshSession();
+ expect(refreshCalls()).toBe(2);
+ });
+
+ test('a 401 forces refresh even after successful socket setup', async () => {
+ mockFetch.mockImplementation(async (input) =>
+ isRefresh(input) ? jsonResponse(200) : jsonResponse(401)
+ );
+ await ensureFreshSession();
+ await fetchWithToken(RESOURCE_URL);
+ expect(refreshCalls()).toBe(2);
+ });
+
+ test('a reset prevents an old successful refresh from being reused', async () => {
+ const response = deferred<Response>();
+ mockFetch
+ .mockReturnValueOnce(response.promise)
+ .mockResolvedValue(jsonResponse(200));
+ const oldRefresh = fetchToken();
+ unsetTokenPromise();
+ response.resolve(jsonResponse(200));
+ await oldRefresh;
+ await ensureFreshSession();
+ expect(refreshCalls()).toBe(2);
+ });
+
test('fires at most one doomed refresh across sequential 401s', async () => {
mockFetch.mockImplementation((input) =>
Promise.resolve(
diff --git a/apps/web/src/lib/core/util/fetchWithToken.ts b/apps/web/src/lib/core/util/fetchWithToken.ts
index 496c6038dc..5330e1058c 100644
--- a/apps/web/src/lib/core/util/fetchWithToken.ts
+++ b/apps/web/src/lib/core/util/fetchWithToken.ts
@@ -1,10 +1,17 @@
-import { perfMark } from '@app/observability/perf-marks';
import { ENABLE_BEARER_TOKEN_AUTH } from '@core/constant/featureFlags';
-import { SERVER_HOSTS } from '@core/constant/servers';
import { Telemetry } from '@macro-inc/observability';
import { fetchWithAuth } from '@service-auth/fetch';
-import { err, ok, type Result } from 'neverthrow';
+import { err, type Result } from 'neverthrow';
+import { fetchToken } from '../auth/session-refresh';
+
+export {
+ confirmSessionExpired,
+ ensureFreshSession,
+ fetchToken,
+ unsetTokenPromise,
+} from '../auth/session-refresh';
+
import type { ObjectLike, ResultError } from './result';
import {
type BaseFetchErrorCode,
@@ -52,126 +59,6 @@ function fetchWithCredentials<
);
}
-type TokenResult = Result<void, ResultError<FetchWithTokenErrorCode>[]>;
-
-let tokenPromise: Promise<TokenResult> | null = null;
-
-// Once /jwt/refresh definitively rejects the session, cache that failure so
-// subsequent 401s short-circuit instead of each firing another doomed refresh.
-// An anonymous visitor on a public link otherwise triggers one refresh per
-// authenticated app-chrome query. Only a definitive rejection latches:
-// transient failures (proxy errors, outages) must never be remembered as
-// "logged out". Cleared by unsetTokenPromise on login, by TTL expiry, and when
-// the app regains visibility/connectivity — on native the webview lives for
-// days without a reload, so a permanent latch turns one bad response into a
-// forced re-login.
-let refreshUnavailable: TokenResult | null = null;
-let refreshUnavailableAt = 0;
-const REFRESH_UNAVAILABLE_TTL_MS = 60_000;
-
-// Bumped on every reset. A refresh started before a reset carries the older
-// generation, so once the session has moved on (e.g. a login) it can neither
-// re-latch refreshUnavailable nor clear a newer tokenPromise on completion.
-let refreshGeneration = 0;
-
-function clearRefreshLatch() {
- refreshUnavailable = null;
-}
-
-if (typeof window !== 'undefined' && typeof document !== 'undefined') {
- window.addEventListener('online', clearRefreshLatch);
- document.addEventListener('visibilitychange', () => {
- if (document.visibilityState === 'visible') clearRefreshLatch();
- });
-}
-
-// The auth service's definitive "this session cannot be refreshed" bodies
-// (RefreshError and the token-extraction middleware in authentication_service
-// return these as text/plain 400s). Any other non-2xx on /jwt/refresh — proxy
-// 400s, 408/429, 5xx — is transient and must not latch.
-const REFRESH_REJECTED_BODIES = new Set([
- 'invalid refresh token',
- 'no access token to refresh',
- 'no refresh token to refresh',
-]);
-
-const classifyRefreshError: ErrorResponseHandler<never> = async (response) => {
- if (response.status === 400) {
- let body = '';
- try {
- body = (await response.text()).trim();
- } catch {}
- if (REFRESH_REJECTED_BODIES.has(body)) {
- return { code: 'UNAUTHORIZED', message: body };
- }
- }
- return {
- code: 'HTTP_ERROR',
- message: `HTTP error! status: ${response.status}`,
- };
-};
-
-export async function fetchToken(): Promise<TokenResult> {
- if (refreshUnavailable != null) {
- if (Date.now() - refreshUnavailableAt < REFRESH_UNAVAILABLE_TTL_MS) {
- return refreshUnavailable;
- }
- refreshUnavailable = null;
- }
- if (tokenPromise == null) {
- const generation = refreshGeneration;
- tokenPromise = (async () => {
- perfMark('auth.refresh-start');
- try {
- const result = await fetchWithCredentials(
- `${SERVER_HOSTS['auth-service']}/jwt/refresh`,
- {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- Accept: 'application/json',
- },
- cache: 'no-store',
- errorResponseHandler: classifyRefreshError,
- }
- );
-
- perfMark('auth.refresh-end', { ok: result.isOk() });
- if (result.isErr()) {
- const failure = err(result.error);
- if (
- generation === refreshGeneration &&
- result.error.some((e) => e.code === 'UNAUTHORIZED')
- ) {
- refreshUnavailable = failure;
- refreshUnavailableAt = Date.now();
- }
- return failure;
- }
-
- return ok(undefined);
- } finally {
- if (generation === refreshGeneration) {
- tokenPromise = null;
- }
- }
- })();
- }
- return tokenPromise;
-}
-
-/**
- * Bypasses any latched refresh failure and asks the auth service directly
- * whether the session can still be refreshed. Returns true only on a
- * definitive rejection. Callers about to destroy local session state must use
- * this instead of trusting a possibly-stale latched UNAUTHORIZED.
- */
-export async function confirmSessionExpired(): Promise<boolean> {
- refreshUnavailable = null;
- const result = await fetchToken();
- return result.isErr() && result.error.some((e) => e.code === 'UNAUTHORIZED');
-}
-
/**
* Performs a fetch request with automatic token refresh on unauthorized errors.
*
@@ -203,8 +90,15 @@ export async function fetchWithToken<
input: RequestInfo,
init?: FetchWithTokenInit<CustomErrorCode>
): Promise<Result<T, ResultError<BaseFetchErrorCode | CustomErrorCode>[]>> {
+ const requestInit = {
+ ...init,
+ trace: {
+ ...init?.trace,
+ parentSpan: init?.trace?.parentSpan ?? Telemetry.captureContext(),
+ },
+ };
if (ENABLE_BEARER_TOKEN_AUTH) {
- const result = await fetchWithAuth<T, CustomErrorCode>(input, init);
+ const result = await fetchWithAuth<T, CustomErrorCode>(input, requestInit);
if (result.isErr()) {
Telemetry.error('fetchWithToken: fetchWithAuth failed', {
input: telemetryUrl(input),
@@ -216,13 +110,18 @@ export async function fetchWithToken<
return result;
}
- let result = await fetchWithCredentials<T, CustomErrorCode>(input, init);
+ let result = await fetchWithCredentials<T, CustomErrorCode>(
+ input,
+ requestInit
+ );
if (
result.isErr() &&
result.error.some((error) => error.code === 'UNAUTHORIZED')
) {
- const tokenResult = await fetchToken();
+ const tokenResult = await requestInit.trace.parentSpan.run(() =>
+ fetchToken()
+ );
if (tokenResult.isErr()) {
// A definitive rejection already carries UNAUTHORIZED; transient refresh
// failures surface as-is so callers don't treat an outage as a dead
@@ -231,24 +130,8 @@ export async function fetchWithToken<
}
// Retry the original request
- result = await fetchWithCredentials<T, CustomErrorCode>(input, init);
+ result = await fetchWithCredentials<T, CustomErrorCode>(input, requestInit);
}
return result;
}
-
-/**
- * Unsets the token promise, forcing a new token to be fetched on the next request.
- * This can be useful in situations where you know the token has become invalid.
- *
- * @example
- * import { unsetTokenPromise } from './path-to-this-module';
- *
- * // After logging out the user
- * unsetTokenPromise();
- */
-export function unsetTokenPromise() {
- refreshGeneration++;
- tokenPromise = null;
- refreshUnavailable = null;
-}
diff --git a/apps/web/src/lib/core/util/platformFetch.test.ts b/apps/web/src/lib/core/util/platformFetch.test.ts
new file mode 100644
index 0000000000..4b6c88e0d5
--- /dev/null
+++ b/apps/web/src/lib/core/util/platformFetch.test.ts
@@ -0,0 +1,125 @@
+import { convertFileSrc, invoke } from '@tauri-apps/api/core';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+const nativeFetch = vi.hoisted(() => vi.fn<typeof fetch>());
+const platform = vi.hoisted(() => ({ native: true }));
+vi.mock('../constant/servers', () => ({
+ NATIVE_SESSION_SERVICE_URLS: [
+ new URL('/auth', document.baseURI).href,
+ 'http://127.0.0.1:3006/sync',
+ ],
+}));
+vi.mock('./platform', () => ({ isTauri: () => platform.native }));
+vi.mock('@tauri-apps/plugin-http', () => ({ fetch: nativeFetch }));
+
+import {
+ createPlatformFetch,
+ initializePlatformFetch,
+ platformFetch,
+ webviewFetch,
+} from './platformFetch';
+
+beforeEach(() => {
+ platform.native = true;
+ vi.stubGlobal('__TAURI_INTERNALS__', {
+ convertFileSrc: (path: string) =>
+ `ipc://localhost/${encodeURIComponent(path)}`,
+ });
+ nativeFetch.mockReset().mockResolvedValue(new Response('native'));
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+it.each([
+ 'ipc://localhost/',
+ 'http://ipc.localhost/',
+ 'https://ipc.localhost/',
+])(
+ 'keeps real invoke dispatch on the browser-owned IPC endpoint %s',
+ async (endpoint) => {
+ vi.stubGlobal('__TAURI_INTERNALS__', {
+ convertFileSrc: (path: string) =>
+ `${endpoint}${encodeURIComponent(path)}`,
+ invoke: async (command: string, args: unknown) => {
+ const response = await fetch(convertFileSrc(command, 'ipc'), {
+ method: 'POST',
+ body: JSON.stringify(args),
+ });
+ return response.json();
+ },
+ });
+ const browser = vi
+ .fn<typeof fetch>()
+ .mockImplementation(async () => Response.json({ available: true }));
+ nativeFetch.mockImplementation(async () => {
+ // Bound the broken recursive path so this regression cannot exhaust memory.
+ if (nativeFetch.mock.calls.length > 1)
+ throw new Error('Recursive IPC fetch');
+ await invoke('plugin:http|fetch', {});
+ return Response.json({ available: true });
+ });
+ vi.stubGlobal('fetch', initializePlatformFetch(browser));
+ await expect(invoke('read_desktop_diagnostics')).resolves.toEqual({
+ available: true,
+ });
+ expect(browser).toHaveBeenCalledTimes(1);
+ expect(nativeFetch).not.toHaveBeenCalled();
+ }
+);
+
+it.each([
+ '/asset.wasm',
+ 'data:text/plain,hello',
+ 'blob:http://localhost/image',
+])('keeps browser-compatible %s off the bridge', async (url) => {
+ const browser = vi
+ .fn<typeof fetch>()
+ .mockResolvedValue(new Response('browser'));
+ expect(await (await createPlatformFetch(browser)(url)).text()).toBe(
+ 'browser'
+ );
+ expect(nativeFetch).not.toHaveBeenCalled();
+});
+
+it('keeps remote authentication and arbitrary email images on the native transport', async () => {
+ const browser = vi.fn<typeof fetch>();
+ const request = createPlatformFetch(browser);
+ await request('https://gateway.example/auth', { credentials: 'include' });
+ await request('https://images.example/image?localhost=true');
+ await request('http://127.0.0.1:3006/dev');
+ await request('http://[::1]:3006/dev');
+ await request('ipc://other-host/command');
+ await request('https://ipc.localhost.example/command');
+ expect(nativeFetch).toHaveBeenCalledTimes(6);
+ expect(browser).not.toHaveBeenCalled();
+});
+
+it('uses the captured browser fetch after the global override', async () => {
+ const browser = vi
+ .fn<typeof fetch>()
+ .mockResolvedValue(new Response('browser'));
+ const request = initializePlatformFetch(browser);
+ vi.stubGlobal('fetch', request);
+ try {
+ await fetch(new URL('/asset.wasm', document.baseURI));
+ await platformFetch('https://gateway.example/auth');
+ await webviewFetch('https://public-api.example/search');
+ expect(browser).toHaveBeenCalledTimes(2);
+ expect(nativeFetch).toHaveBeenCalledTimes(1);
+ } finally {
+ vi.unstubAllGlobals();
+ }
+});
+
+it('keeps configured local and same-origin APIs on the native cookie jar', async () => {
+ const browser = vi
+ .fn<typeof fetch>()
+ .mockResolvedValue(new Response('browser'));
+ const request = createPlatformFetch(browser);
+ await request(new URL('/auth/login/passwordless', document.baseURI));
+ await request('http://127.0.0.1:3006/sync/snapshot');
+ expect(nativeFetch).toHaveBeenCalledTimes(2);
+ expect(browser).not.toHaveBeenCalled();
+ await request(new URL('/auth-assets/icon.png', document.baseURI));
+ expect(browser).toHaveBeenCalledTimes(1);
+});
diff --git a/apps/web/src/lib/core/util/platformFetch.ts b/apps/web/src/lib/core/util/platformFetch.ts
index 427ca22848..3bfcd7f907 100644
--- a/apps/web/src/lib/core/util/platformFetch.ts
+++ b/apps/web/src/lib/core/util/platformFetch.ts
@@ -1,26 +1,58 @@
+import { convertFileSrc } from '@tauri-apps/api/core';
+import { NATIVE_SESSION_SERVICE_URLS } from '../constant/servers';
import { isTauri } from './platform';
-async function acquireFetch() {
- // @ts-ignore: tauri adds this on the window instance
- if (isTauri()) {
- const { fetch } = await import('@tauri-apps/plugin-http');
- return fetch;
- }
- return window.fetch;
+const nativeServices = NATIVE_SESSION_SERVICE_URLS.map((url) => new URL(url));
+let originalFetch: typeof fetch | undefined;
+
+/** Called by the entry point before installing the desktop global override. */
+export function initializePlatformFetch(
+ webviewFetch: typeof fetch
+): typeof fetch {
+ originalFetch = webviewFetch;
+ return createPlatformFetch(webviewFetch);
}
-// async function acquireWebsocket() {
-// if (isTauri()) {
-// const ws = await import("@tauri-apps/plugin-websocket");
-// return ws
-// }
-// return WebSocket
-// }
+/** Explicit browser transport for APIs that require the webview's origin. */
+export const webviewFetch: typeof fetch = (input, init) =>
+ (originalFetch ?? globalThis.fetch)(input, init);
-// export const connectPlatformWebsocket: ReturnType<typeof WebSocket["conne"]
+/** Native HTTP owns the desktop session cookie jar and bypasses remote CORS. */
+export function createPlatformFetch(
+ webviewFetch: typeof window.fetch
+): typeof window.fetch {
+ // Tauri sends invoke calls through global fetch. Preserve its webview-owned
+ // endpoint or native HTTP recursively invokes itself and expands each payload.
+ const ipc = isTauri() ? new URL(convertFileSrc('', 'ipc')) : undefined;
+ return async (input, init) => {
+ if (!isTauri()) return webviewFetch(input, init);
+ const url = new URL(
+ input instanceof Request ? input.url : String(input),
+ document.baseURI
+ );
+ // Service URLs own authentication even when a development proxy happens to
+ // share the page origin or use loopback. Webview and reqwest jars differ.
+ const service = nativeServices.some(
+ (base) =>
+ url.origin === base.origin &&
+ (url.pathname === base.pathname ||
+ url.pathname.startsWith(`${base.pathname.replace(/\/$/, '')}/`))
+ );
+ // Assets share the webview origin; authenticated service prefixes take
+ // precedence even when the development proxy shares that origin.
+ if (
+ (ipc && url.protocol === ipc.protocol && url.host === ipc.host) ||
+ (!service && url.origin === new URL(document.baseURI).origin) ||
+ url.protocol === 'data:' ||
+ url.protocol === 'blob:'
+ ) {
+ return webviewFetch(input, init);
+ }
+ const { fetch } = await import('@tauri-apps/plugin-http');
+ return fetch(input, init);
+ };
+}
-// wrapper around window.fetch which just forwards args to fetch on the web.
-// In tauri environments this forwards requests into the tauri http client
-export const platformFetch: typeof window.fetch = (url, opts) => {
- return acquireFetch().then((f) => f(url, opts));
-};
+// Native startup installs the transport explicitly; all callers share it.
+export const platformFetch: typeof fetch = (input, init) =>
+ globalThis.fetch(input, init);
diff --git a/apps/web/src/lib/core/util/safeFetch-telemetry.test.ts b/apps/web/src/lib/core/util/safeFetch-telemetry.test.ts
index 4cd03f87e7..566fe5126d 100644
--- a/apps/web/src/lib/core/util/safeFetch-telemetry.test.ts
+++ b/apps/web/src/lib/core/util/safeFetch-telemetry.test.ts
@@ -9,14 +9,18 @@ const mocks = vi.hoisted(() => ({
error: vi.fn(),
end: vi.fn(),
},
- clientSpan: vi.fn(),
+ startSpan: vi.fn(),
}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { calls: 'https://gateway.example' },
SYNC_SERVICE_HOSTS: { worker: 'https://sync.example' },
}));
vi.mock('@macro-inc/observability', () => ({
- Telemetry: { clientSpan: mocks.clientSpan },
+ Telemetry: {
+ span: mocks.startSpan,
+ captureContext: () => ({ run: <T>(work: () => T) => work() }),
+ },
}));
vi.mock('./platformFetch', () => ({ platformFetch: mocks.fetch }));
@@ -24,7 +28,7 @@ import { safeFetch } from './safeFetch';
beforeEach(() => {
vi.clearAllMocks();
- mocks.clientSpan.mockReturnValue(mocks.span);
+ mocks.startSpan.mockReturnValue(mocks.span);
});
describe('safeFetch capability URL privacy', () => {
@@ -39,11 +43,12 @@ describe('safeFetch capability URL privacy', () => {
expect(mocks.fetch.mock.calls[0][1].headers.Authorization).toBe(
'Bearer scoped-token'
);
- expect(mocks.clientSpan).toHaveBeenCalledWith(
- 'http POST /dss/call/join/:shareToken/leave'
+ expect(mocks.startSpan).toHaveBeenCalledWith(
+ 'http POST /dss/call/join/:shareToken/leave',
+ { kind: 'client' }
);
const telemetry = JSON.stringify([
- mocks.clientSpan.mock.calls,
+ mocks.startSpan.mock.calls,
mocks.span.setAttr.mock.calls,
mocks.span.error.mock.calls,
]);
diff --git a/apps/web/src/lib/core/util/safeFetch.ts b/apps/web/src/lib/core/util/safeFetch.ts
index 7cebc42eca..a9da1ed39d 100644
--- a/apps/web/src/lib/core/util/safeFetch.ts
+++ b/apps/web/src/lib/core/util/safeFetch.ts
@@ -1,5 +1,5 @@
import { SERVER_HOSTS, SYNC_SERVICE_HOSTS } from '@core/constant/servers';
-import { type Span, Telemetry } from '@macro-inc/observability';
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
import { err, ok, type Result } from 'neverthrow';
import { match } from 'ts-pattern';
import { platformFetch } from './platformFetch';
@@ -48,9 +48,9 @@ function tracedFetch(
const path = redactLinkTokens(url.pathname);
const span = traceOptions?.parentSpan
? traceOptions.parentSpan.run(() =>
- Telemetry.clientSpan(`http ${method} ${path}`)
+ Telemetry.span(`http ${method} ${path}`, { kind: 'client' })
)
- : Telemetry.clientSpan(`http ${method} ${path}`);
+ : Telemetry.span(`http ${method} ${path}`, { kind: 'client' });
const started = performance.now();
span.setAttr('http.method', method);
// Path only: query strings can carry tokens.
@@ -177,7 +177,7 @@ export interface RetryConfig {
/** Trace context and response classification, never forwarded to fetch. */
export interface SafeFetchTraceOptions {
/** Restore the action's parent after async auth or mutation scheduling. */
- parentSpan?: Span;
+ parentSpan?: TraceContext;
/** Non-OK responses that should not mark the HTTP span as failed. */
expectedStatusCodes?: readonly number[];
}
@@ -282,7 +282,11 @@ export async function safeFetch<
init?: SafeFetchInit,
errorResponseHandler?: ErrorResponseHandler<CustomErrorCode>
): Promise<Result<T, ResultError<BaseFetchErrorCode | CustomErrorCode>[]>> {
- const { retry, trace, ...fetchInit } = init || {};
+ const { retry, trace: suppliedTrace, ...fetchInit } = init || {};
+ const trace = {
+ ...suppliedTrace,
+ parentSpan: suppliedTrace?.parentSpan ?? Telemetry.captureContext(),
+ };
const maxTries = retry?.maxTries ?? 1;
const delay = retry?.delay ?? 0;
type ErrorCode = BaseFetchErrorCode | CustomErrorCode;
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
index 01a061983a..4eedd0625c 100644
--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts
@@ -80,6 +80,7 @@ import {
type QueryRevalidationWire,
type ReadResult,
} from '../protocol';
+import { classifyCacheError } from '../telemetry';
import { createDeferredQueryRereads } from './deferred-query-rereads';
import {
createDocumentQueryReader,
@@ -1247,8 +1248,14 @@ export function normalizedCacheExchange(
span?: Span
): Promise<boolean> {
let applied = true;
+ span?.setAttr('cache.effect_count', effects.length);
for (const effect of effects) {
if (!isCurrent()) return false;
+ const effectSpan = span?.span(
+ effect.kind === 'write'
+ ? 'graphql.subscription.cache_write'
+ : 'graphql.subscription.cache_delete'
+ );
try {
if (effect.kind === 'write') {
await host.writeQuery({
@@ -1263,9 +1270,14 @@ export function normalizedCacheExchange(
} catch (error) {
applied = false;
span?.error('Subscription cache effect failed');
+ span?.setAttr('cache.failure', classifyCacheError(error));
+ effectSpan?.setAttr('cache.failure', classifyCacheError(error));
// One failed cache effect must neither skip later effects nor
// prevent delivery of the original operation result.
+ effectSpan?.error('Subscription cache effect failed');
options.onCacheError?.(error, op);
+ } finally {
+ effectSpan?.end();
}
}
return applied && isCurrent();
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
index 32cd5639ce..ceb83255b7 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts
@@ -1,3 +1,4 @@
+import { Telemetry } from '@macro-inc/observability';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const invokeMock = vi.hoisted(() => vi.fn());
@@ -45,6 +46,8 @@ describe('createTauriCacheHost', () => {
afterEach(async () => {
await vi.dynamicImportSettled();
+ vi.useRealTimers();
+ vi.restoreAllMocks();
});
beforeEach(() => {
@@ -58,6 +61,86 @@ describe('createTauriCacheHost', () => {
});
});
+ it('samples request tracing without creating a span for each notification', async () => {
+ const span = vi.spyOn(Telemetry, 'span');
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.readQuery({ query: '{ x }' });
+ // Initialization, queue probe, read.
+ expect(span.mock.calls).toEqual([
+ ['graphql_cache.ipc.request', { sampling: 'perf' }],
+ ['graphql_cache.ipc.request', { sampling: 'perf' }],
+ ['graphql_cache.ipc.request', { sampling: 'perf' }],
+ ]);
+ const notify = eventCallbacks.get('graphql-cache://cache-changed')!;
+ for (let revision = 1; revision <= 100; revision++) {
+ notify({ payload: { revision: String(revision) } });
+ }
+ expect(span).toHaveBeenCalledTimes(3);
+ host.dispose();
+ });
+
+ it('coalesces identical pending reads, but preserves operation registration and write barriers', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.readQuery({ query: '{ warm }' });
+ invokeMock.mockClear();
+ let release = () => {};
+ const gate = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ invokeMock.mockImplementation(async (command: string) => {
+ if (command === 'graphql_cache_read') await gate;
+ return { kind: 'miss' };
+ });
+ const first = host.readQuery({ opKey: 1, query: '{ x }' });
+ const duplicate = host.readQuery({ opKey: 1, query: '{ x }' });
+ const otherOperation = host.readQuery({ opKey: 2, query: '{ x }' });
+ await host.writeQuery({ query: '{ x }', data: {} });
+ const afterWrite = host.readQuery({ opKey: 1, query: '{ x }' });
+ release();
+ await Promise.all([first, duplicate, otherOperation, afterWrite]);
+ expect(
+ invokeMock.mock.calls.filter(
+ ([command]) => command === 'graphql_cache_read'
+ )
+ ).toHaveLength(3);
+ await host.readQuery({ opKey: 1, query: '{ x }' });
+ expect(
+ invokeMock.mock.calls.filter(
+ ([command]) => command === 'graphql_cache_read'
+ )
+ ).toHaveLength(4);
+ host.dispose();
+ });
+
+ it('invalidates pending read reuse when native changes arrive', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.readQuery({ query: '{ warm }' });
+ invokeMock.mockClear();
+ let release = () => {};
+ const gate = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ let started = () => {};
+ const invoked = new Promise<void>((resolve) => {
+ started = resolve;
+ });
+ invokeMock.mockImplementation(async () => {
+ started();
+ await gate;
+ return { kind: 'miss' };
+ });
+ const first = host.readQuery({ query: '{ x }' });
+ await invoked;
+ eventCallbacks.get('graphql-cache://cache-changed')!({
+ payload: { revision: INITIAL_CACHE_REVISION },
+ });
+ const second = host.readQuery({ query: '{ x }' });
+ release();
+ await Promise.all([first, second]);
+ expect(invokeMock).toHaveBeenCalledTimes(2);
+ host.dispose();
+ });
+
it('reads the database generation after native initialization', async () => {
const generation = '00000000-0000-4000-8000-000000000001';
invokeMock.mockImplementation(async (command: string) =>
@@ -894,6 +977,7 @@ describe('createTauriCacheHost', () => {
});
it('delivers only own-client op keys from the broadcast event', async () => {
+ vi.useFakeTimers();
const host = createTauriCacheHost({ scope: 'scope-1' });
const seen: number[][] = [];
host.onOpsAffected((opKeys) => seen.push(opKeys));
@@ -910,15 +994,71 @@ describe('createTauriCacheHost', () => {
keys: ['A:1'],
},
});
+ await vi.advanceTimersByTimeAsync(0);
expect(seen).toEqual([[5, 8]]);
// No delivery when nothing matches this client.
eventCallbacks.get('graphql-cache://ops-affected')?.({
payload: { opIds: ['other-client:9'], keys: ['A:1'] },
});
+ await vi.advanceTimersByTimeAsync(0);
expect(seen).toEqual([[5, 8]]);
});
+ it('coalesces invalidations and preserves ordered patches and disposal', async () => {
+ vi.useFakeTimers();
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ const seen = vi.fn();
+ host.onOpsAffected(seen);
+ const notify = eventCallbacks.get('graphql-cache://ops-affected')!;
+ for (let i = 0; i < 100; i++) {
+ notify({ payload: { opIds: [`${host.clientId}:5`] } });
+ }
+ expect(seen).not.toHaveBeenCalled();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(seen).toHaveBeenCalledExactlyOnceWith([5]);
+ seen.mockClear();
+ notify({ payload: { opIds: [`${host.clientId}:6`] } });
+ const patches = [{ kind: 'invalidate', key: 'Entity:1' }];
+ notify({
+ payload: { opIds: [`${host.clientId}:5`], fieldChanges: patches },
+ });
+ expect(seen.mock.calls).toEqual([[[6]], [[5], patches]]);
+ notify({ payload: { opIds: [`${host.clientId}:7`] } });
+ host.dispose();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(seen).toHaveBeenCalledTimes(2);
+ });
+
+ it.each([
+ { event: 'cache-changed', payload: { revision: '7', reset: true } },
+ { event: 'cache-hydrated', payload: { revision: '7' } },
+ {
+ event: 'mutation-settled',
+ payload: { transactionId: '1', status: 'committed' },
+ },
+ ])(
+ 'flushes invalidations before $event observers run',
+ ({ event, payload }) => {
+ vi.useFakeTimers();
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ const seen: string[] = [];
+ host.onOpsAffected(() => seen.push('affected'));
+ host.onCacheChanged(() => seen.push('changed'), {
+ includeHydration: true,
+ });
+ host.onCacheGenerationChanged(() => seen.push('generation'));
+ host.onMutationSettled(() => seen.push('settled'));
+ eventCallbacks.get('graphql-cache://ops-affected')!({
+ payload: { opIds: [`${host.clientId}:5`] },
+ });
+ eventCallbacks.get(`graphql-cache://${event}`)!({ payload });
+ expect(seen[0]).toBe('affected');
+ expect(seen.length).toBeGreaterThan(1);
+ host.dispose();
+ }
+ );
+
it('delivers cache change notifications', async () => {
const host = createTauriCacheHost({ scope: 'scope-1' });
let calls = 0;
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
index f05a177a3a..930c721aa2 100644
--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts
@@ -10,10 +10,12 @@ import type { MutationInspection } from '../protocol';
*/
import { fireAndForget } from '@core/util/fireAndForget';
+import { Telemetry } from '@macro-inc/observability';
import { invoke } from '@tauri-apps/api/core';
import { emit, listen, type UnlistenFn } from '@tauri-apps/api/event';
import type {
AffectedOperationsResult,
+ CacheChangeHints,
CachedQueryInstanceWire,
CachedQueryVariantWire,
CacheRevision,
@@ -28,7 +30,7 @@ import type {
EntityFilterCacheArgs,
EntityFilterCacheResult,
HydrationResult,
- HydrationSearchChanges,
+ LiveQueryUpdate,
MutationClaim,
MutationSettlement,
ReadRecordsByKeysArgs,
@@ -74,13 +76,12 @@ const MUTATION_SETTLED_EVENT = 'graphql-cache://mutation-settled';
type OpsAffectedPayload = {
fieldChanges?: RecordFieldChange[];
opIds: string[];
- keys: string[];
};
type CacheChangedPayload = {
revision: string;
reset?: boolean;
-} & HydrationSearchChanges;
+} & CacheChangeHints;
// Older native binaries omit the advancement bit and still receive OTA JS.
type NativeHydrationResult = HydrationResult & { revisionAdvanced?: boolean };
@@ -100,6 +101,9 @@ export interface TauriHostOptions {
const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
const ENTITY_FILTER_COMMAND = 'graphql_cache_entity_filter';
+const ENTITY_FILTER_RESUME_COMMAND = 'graphql_cache_entity_filter_resume';
+// Match the engine view bound. Retention is only a request-size optimization.
+const LIVE_QUERY_CAPACITY = 32;
const WATCH_COMMAND = 'graphql_cache_watch';
const CALENDAR_RANGE_COMMAND = 'graphql_cache_calendar_range';
const CALENDAR_COMMIT_COMMAND = 'graphql_cache_calendar_commit';
@@ -161,47 +165,91 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
return true;
}
- function request<T>(
+ // Only identical in-flight reads share a result. Any intervening command or
+ // native notification is a barrier: never reuse a read across a write/reset.
+ const pendingReads = new Map<string, Promise<ReadResult>>();
+ const liveQueries = new Map<
+ string,
+ { descriptor: string; registrationId?: string }
+ >();
+
+ const pendingAffected = new Set<number>();
+ let affectedTimer: ReturnType<typeof setTimeout> | undefined;
+
+ function flushAffected() {
+ clearTimeout(affectedTimer);
+ affectedTimer = undefined;
+ if (!pendingAffected.size) return;
+ const keys = [...pendingAffected];
+ pendingAffected.clear();
+ for (const cb of affectedSubscribers) cb(keys);
+ }
+
+ async function request<T>(
command: string,
args: Record<string, unknown>,
timeout = true
): Promise<T> {
- return new Promise<T>((resolve, reject) => {
- const timer = timeout
- ? setTimeout(() => {
- reject(new Error(`graphql cache ipc timeout: ${command}`));
- }, requestTimeoutMs)
+ if (command !== 'graphql_cache_read') pendingReads.clear();
+ const span = Telemetry.span('graphql_cache.ipc.request', {
+ sampling: 'perf',
+ });
+ span.setAttr('graphql_cache.ipc.command', command);
+ const traceparent = span.traceparent();
+ const wireArgs = traceparent ? { ...args, traceparent } : args;
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ let timedOut = false;
+ try {
+ const operation = span.run(() => invoke<T>(command, wireArgs));
+ const deadline = timeout
+ ? new Promise<never>((_, reject) => {
+ timer = setTimeout(() => {
+ timedOut = true;
+ reject(new Error(`graphql cache ipc timeout: ${command}`));
+ }, requestTimeoutMs);
+ })
: undefined;
- invoke<T>(command, args).then(
- (value) => {
- if (timer !== undefined) clearTimeout(timer);
- resolve(value);
- },
- (error) => {
- if (timer !== undefined) clearTimeout(timer);
- // Command errors cross the boundary as strings; normalize to
- // Error for parity with worker-host rejections.
- reject(error instanceof Error ? error : new Error(String(error)));
- }
+ const value = await (deadline
+ ? Promise.race([operation, deadline])
+ : operation);
+ span.setAttr('graphql_cache.ipc.outcome', 'ok');
+ return value;
+ } catch (error) {
+ span.setAttr('graphql_cache.ipc.outcome', timedOut ? 'timeout' : 'error');
+ span.error(
+ timedOut
+ ? 'Native cache request timed out'
+ : 'Native cache request failed'
);
- });
+ // Native command errors cross the boundary as strings.
+ throw error instanceof Error ? error : new Error(String(error));
+ } finally {
+ clearTimeout(timer);
+ span.end();
+ }
}
// Failure tolerated: reads/writes still work, only push-driven
// re-execution is lost — same degradation as a broken worker port.
const unlistenOps: Promise<UnlistenFn | undefined> =
listen<OpsAffectedPayload>(OPS_AFFECTED_EVENT, (event) => {
+ pendingReads.clear();
+
const prefix = `${clientId}:`;
const opKeys = event.payload.opIds
.filter((id) => id.startsWith(prefix))
.map((id) => Number(id.slice(prefix.length)))
.filter((n) => Number.isFinite(n));
- if (opKeys.length > 0) {
- for (const cb of affectedSubscribers) {
- if (isRecordFieldChanges(event.payload.fieldChanges))
- cb(opKeys, event.payload.fieldChanges);
- else cb(opKeys);
- }
+ if (opKeys.length === 0) return;
+ if (isRecordFieldChanges(event.payload.fieldChanges)) {
+ // Patches are ordered data, so deliver them immediately after earlier
+ // invalidations. Only conservative reread notifications can coalesce.
+ flushAffected();
+ for (const cb of affectedSubscribers)
+ cb(opKeys, event.payload.fieldChanges);
+ } else {
+ for (const key of opKeys) pendingAffected.add(key);
+ affectedTimer ??= setTimeout(flushAffected, 0);
}
}).catch((error) => {
console.warn('graphql cache ops-affected listener failed', error);
@@ -209,6 +257,8 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
});
const unlistenSettlements: Promise<UnlistenFn | undefined> =
listen<MutationSettlement>(MUTATION_SETTLED_EVENT, (event) => {
+ pendingReads.clear();
+ flushAffected();
for (const cb of settlementSubscribers) cb(event.payload);
}).catch((error) => {
console.warn('graphql cache mutation-settled listener failed', error);
@@ -217,20 +267,25 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
const unlistenCacheChanges: Promise<UnlistenFn | undefined> =
listen<CacheChangedPayload>(CACHE_CHANGED_EVENT, (event) => {
+ pendingReads.clear();
+ flushAffected();
const revision = parseCacheRevision(event.payload.revision);
observeRevision(revision);
if (event.payload.reset) {
+ liveQueries.clear();
for (const cb of generationChangeSubscribers) cb({ storage: 'reset' });
}
for (const cb of cacheChangeSubscribers) {
if (
event.payload.reset ||
- event.payload.searchChangedBuckets === undefined
+ (event.payload.searchChangedBuckets === undefined &&
+ event.payload.unchangedViews === undefined)
)
cb(revision);
else
cb(revision, {
searchChangedBuckets: event.payload.searchChangedBuckets,
+ unchangedViews: event.payload.unchangedViews,
});
}
}).catch((error) => {
@@ -243,14 +298,15 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
return await listen<CacheChangedPayload>(
CACHE_HYDRATED_EVENT,
(event) => {
+ pendingReads.clear();
+ flushAffected();
const revision = parseCacheRevision(event.payload.revision);
observeRevision(revision);
for (const cb of hydrationSubscribers) {
- if (event.payload.searchChangedBuckets === undefined) cb(revision);
- else
- cb(revision, {
- searchChangedBuckets: event.payload.searchChangedBuckets,
- });
+ cb(revision, {
+ searchChangedBuckets: event.payload.searchChangedBuckets,
+ unchangedViews: event.payload.unchangedViews,
+ });
}
}
);
@@ -327,13 +383,23 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
async readQuery(args: CacheReadArgs): Promise<ReadResult> {
await ready;
- return await request<ReadResult>('graphql_cache_read', {
+ const wireArgs = {
opId: args.opKey === undefined ? undefined : opId(args.opKey),
query: args.query,
operationName: args.operationName,
variables: args.variables,
entityResolvers: args.entityResolvers,
- });
+ };
+ const key = JSON.stringify(wireArgs);
+ const pending = pendingReads.get(key);
+ if (pending) return pending;
+ const reading = request<ReadResult>('graphql_cache_read', wireArgs);
+ pendingReads.set(key, reading);
+ try {
+ return await reading;
+ } finally {
+ if (pendingReads.get(key) === reading) pendingReads.delete(key);
+ }
},
async watchQuery(args) {
@@ -360,6 +426,13 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
): Promise<ReadRecordsByKeysResult> {
const keys = validateRecordSelectionKeys(args.keys);
await ready;
+ if (keys.length === 0) {
+ // Preserve a fresh revision fence without sending an unused fragment.
+ const revision = parseCacheRevision(
+ await request<string>('graphql_cache_current_revision', {})
+ );
+ return { revision, records: [] };
+ }
const result = await request<ReadRecordsByKeysResult>(
'graphql_cache_read_records_by_keys',
{
@@ -385,9 +458,53 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
await ready;
if (entityFilterUnavailable) return { kind: 'unsupported' };
try {
- return await request<EntityFilterCacheResult>(ENTITY_FILTER_COMMAND, {
- request: args,
- });
+ const live = args.liveQuery;
+ if (live?.release) liveQueries.delete(live.id);
+ let registration:
+ | { descriptor: string; registrationId?: string }
+ | undefined;
+ if (live && !live.release) {
+ const descriptor = JSON.stringify({
+ ...args,
+ liveQuery: { ...live, since: undefined },
+ });
+ registration = liveQueries.get(live.id);
+ if (registration?.descriptor !== descriptor)
+ registration = { descriptor };
+ liveQueries.delete(live.id);
+ liveQueries.set(live.id, registration);
+ if (liveQueries.size > LIVE_QUERY_CAPACITY) {
+ const oldest = liveQueries.keys().next().value;
+ if (oldest !== undefined) liveQueries.delete(oldest);
+ }
+ if (registration.registrationId) {
+ const update = await request<LiveQueryUpdate | null>(
+ ENTITY_FILTER_RESUME_COMMAND,
+ {
+ id: live.id,
+ registrationId: registration.registrationId,
+ since: live.since,
+ }
+ );
+ if (update !== null) return update;
+ }
+ }
+ const result = await request<EntityFilterCacheResult>(
+ ENTITY_FILTER_COMMAND,
+ {
+ request: args,
+ }
+ );
+ // A source change, release, reset or disposal may have happened in flight.
+ if (
+ live &&
+ registration &&
+ liveQueries.get(live.id) === registration &&
+ result.kind === 'live-query'
+ ) {
+ registration.registrationId = result.registrationId;
+ }
+ return result;
} catch (error) {
// Match Tauri's exact unknown-command response, not storage, validation,
// ACL or timeout failures. Preserve the pre-OTA behavior on old binaries.
@@ -482,6 +599,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
if (result.revisionAdvanced === false || !newlyObserved) return result;
try {
await emit(CACHE_HYDRATED_EVENT, {
+ ...(result.unchangedViews !== undefined
+ ? { unchangedViews: result.unchangedViews }
+ : {}),
revision: result.revision,
...(result.searchChangedBuckets !== undefined
? { searchChangedBuckets: result.searchChangedBuckets }
@@ -689,6 +809,10 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {
},
dispose() {
+ clearTimeout(affectedTimer);
+ pendingAffected.clear();
+ pendingReads.clear();
+ liveQueries.clear();
affectedSubscribers.clear();
cacheChangeSubscribers.clear();
hydrationSubscribers.clear();
diff --git a/apps/web/src/lib/graphql-cache/host/tauri-live-query.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-live-query.test.ts
new file mode 100644
index 0000000000..3600aa842e
--- /dev/null
+++ b/apps/web/src/lib/graphql-cache/host/tauri-live-query.test.ts
@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { invoke, listen } = vi.hoisted(() => ({
+ invoke: vi.fn(),
+ listen: vi.fn(),
+}));
+vi.mock('@tauri-apps/api/core', () => ({ invoke }));
+vi.mock('@tauri-apps/api/event', () => ({ listen, emit: vi.fn() }));
+
+import {
+ type EntityFilterCacheArgs,
+ type LiveQueryUpdate,
+ parseCacheRevision,
+} from '../protocol';
+import { createTauriCacheHost } from './tauri-host';
+
+const args: EntityFilterCacheArgs = {
+ filters: {},
+ sortMethod: 'UPDATED_AT',
+ sortDirection: 'DESC',
+ limit: 25,
+ liveQuery: {
+ id: 'view',
+ document: 'fragment Item on GraphqlSoupDocument { id }',
+ fragmentName: 'Item',
+ },
+};
+const update: LiveQueryUpdate = {
+ kind: 'live-query',
+ registrationId: 'registration-1',
+ revision: parseCacheRevision('10'),
+ reset: true,
+ keys: [],
+ upserts: [],
+ patches: [],
+ removed: [],
+ retainedKeys: [],
+ optimistic: false,
+};
+
+describe('native retained view transport', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ listen.mockResolvedValue(() => {});
+ invoke.mockImplementation(async (command: string) =>
+ command.startsWith('graphql_cache_entity_filter') ? update : null
+ );
+ });
+ afterEach(() => vi.restoreAllMocks());
+
+ it('resumes a registered specification and registers again after engine eviction', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.entityFilter(args);
+ const next = {
+ ...args,
+ liveQuery: { ...args.liveQuery!, since: update.revision },
+ };
+ await host.entityFilter(next);
+ expect(invoke).toHaveBeenLastCalledWith(
+ 'graphql_cache_entity_filter_resume',
+ {
+ id: 'view',
+ registrationId: 'registration-1',
+ since: update.revision,
+ }
+ );
+ invoke
+ .mockResolvedValueOnce(null)
+ .mockResolvedValueOnce({ ...update, registrationId: 'registration-2' });
+ await expect(host.entityFilter(next)).resolves.toEqual({
+ ...update,
+ registrationId: 'registration-2',
+ });
+ await host.entityFilter(next);
+ expect(invoke).toHaveBeenLastCalledWith(
+ 'graphql_cache_entity_filter_resume',
+ {
+ id: 'view',
+ registrationId: 'registration-2',
+ since: update.revision,
+ }
+ );
+ host.dispose();
+ });
+
+ it('sends a changed specification in full and preserves older installed binaries', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.entityFilter(args);
+ const changed = { ...args, baseline: [] };
+ const { registrationId: _, ...legacy } = update;
+ invoke.mockResolvedValue(legacy);
+ await host.entityFilter(changed);
+ await host.entityFilter(changed);
+ expect(invoke.mock.calls.slice(-2)).toEqual([
+ ['graphql_cache_entity_filter', { request: changed }],
+ ['graphql_cache_entity_filter', { request: changed }],
+ ]);
+ host.dispose();
+ });
+
+ it('does not revive a released registration when its request finishes late', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.readQuery({ query: '{ warm }' });
+ let finish = (_value: LiveQueryUpdate) => {};
+ invoke.mockImplementationOnce(
+ () =>
+ new Promise<LiveQueryUpdate>((resolve) => {
+ finish = resolve;
+ })
+ );
+ const first = host.entityFilter(args);
+ await vi.dynamicImportSettled();
+ await host.entityFilter({
+ ...args,
+ liveQuery: { ...args.liveQuery!, release: true },
+ });
+ finish(update);
+ await first;
+ await host.entityFilter(args);
+ expect(invoke).toHaveBeenLastCalledWith('graphql_cache_entity_filter', {
+ request: args,
+ });
+ host.dispose();
+ });
+
+ it('bounds retained descriptors and clears them after reset', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ await host.entityFilter(args);
+ for (let id = 0; id < 32; id++) {
+ await host.entityFilter({
+ ...args,
+ liveQuery: { ...args.liveQuery!, id: String(id) },
+ });
+ }
+ await host.entityFilter(args);
+ expect(invoke).toHaveBeenLastCalledWith('graphql_cache_entity_filter', {
+ request: args,
+ });
+ const callback = listen.mock.calls.find(
+ ([name]) => name === 'graphql-cache://cache-changed'
+ )![1];
+ callback({ payload: { revision: '11', reset: true } });
+ await host.entityFilter(args);
+ expect(invoke).toHaveBeenLastCalledWith('graphql_cache_entity_filter', {
+ request: args,
+ });
+ host.dispose();
+ });
+
+ it('reads a fresh revision without transmitting a fragment for empty selections', async () => {
+ const host = createTauriCacheHost({ scope: 'scope-1' });
+ invoke.mockImplementation(async (command: string) =>
+ command === 'graphql_cache_current_revision' ? '42' : null
+ );
+ await expect(
+ host.readRecordsByKeys({
+ document: args.liveQuery!.document,
+ fragmentName: 'Item',
+ keys: [],
+ })
+ ).resolves.toEqual({ revision: '42', records: [] });
+ expect(invoke).toHaveBeenLastCalledWith(
+ 'graphql_cache_current_revision',
+ {}
+ );
+ expect(
+ invoke.mock.calls.some(
+ ([command]) => command === 'graphql_cache_read_records_by_keys'
+ )
+ ).toBe(false);
+ host.dispose();
+ });
+});
diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.ts
index bf17042f61..f5a0943366 100644
--- a/apps/web/src/lib/graphql-cache/host/types.ts
+++ b/apps/web/src/lib/graphql-cache/host/types.ts
@@ -10,6 +10,7 @@ import type { IdentityBindingWire, MutationInspection } from '../protocol';
import type { EntityResolverWire } from '../exchange/entity-resolvers';
import type {
AffectedOperationsResult,
+ CacheChangeHints,
CachedQueryInstanceWire,
CachedQueryVariantWire,
CacheReadPriority,
@@ -25,7 +26,6 @@ import type {
EntityFilterCacheArgs,
EntityFilterCacheResult,
HydrationResult,
- HydrationSearchChanges,
MutationClaim,
MutationSettlement,
OptimisticLinkPatchWire,
@@ -108,8 +108,8 @@ export interface InitialMutationClaimArgs {
export type CacheChangeListener = (
revision: CacheRevision,
- /** Undefined for ordinary writes/resets and older runtimes: refresh conservatively. */
- searchChanges?: HydrationSearchChanges
+ /** Missing metadata/proof IDs mean unknown; resets always refresh. */
+ changes?: CacheChangeHints
) => void;
export type CacheChangeOptions = {
diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.ts
index 8f2041c16b..1433ead8a5 100644
--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts
+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts
@@ -313,11 +313,10 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
if (isCachePush(msg)) {
if (msg.kind === 'cache-hydrated') {
for (const cb of hydrationSubscribers) {
- if (msg.searchChangedBuckets === undefined) cb(msg.revision);
- else
- cb(msg.revision, {
- searchChangedBuckets: msg.searchChangedBuckets,
- });
+ cb(msg.revision, {
+ searchChangedBuckets: msg.searchChangedBuckets,
+ unchangedViews: msg.unchangedViews,
+ });
}
return;
}
@@ -327,11 +326,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {
cb({ storage: 'reset' });
}
for (const cb of cacheChangeSubscribers) {
- if (msg.reset || msg.searchChangedBuckets === undefined)
+ if (
+ msg.reset ||
+ (msg.searchChangedBuckets === undefined &&
+ msg.unchangedViews === undefined)
+ )
cb(msg.revision);
else
cb(msg.revision, {
searchChangedBuckets: msg.searchChangedBuckets,
+ unchangedViews: msg.unchangedViews,
});
}
return;
diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.ts
index 28f87d0b4e..6a00607d72 100644
--- a/apps/web/src/lib/graphql-cache/protocol.ts
+++ b/apps/web/src/lib/graphql-cache/protocol.ts
@@ -140,6 +140,8 @@ export type EntityFilterCacheResult =
| LiveQueryUpdate
| {
kind: 'mail-page';
+ /** Complete engine-owned window; absent on older native runtimes. */
+ observationId?: string;
revision: CacheRevision;
keys: string[];
/** Server members with incomplete local metadata; absent on older native hosts. */
@@ -172,6 +174,10 @@ export type EntityFilterCacheResult =
export type LiveQueryUpdate = {
kind: 'live-query';
+ /** Native specification identity; absent from older installed binaries. */
+ registrationId?: string;
+ /** Immutable observation of this exact evaluated window; legacy hosts omit it. */
+ observationId?: string;
revision: CacheRevision;
reset: boolean;
/** Omitted when the existing order remains valid. */
@@ -600,12 +606,18 @@ export type CachedQueryInstanceWire = CachedQueryVariantWire & {
value?: unknown;
};
-/** Missing metadata means unknown (older runtimes); [] proves no search change. */
-export type HydrationSearchChanges = {
+/** Optional engine evidence. Missing fields preserve conservative invalidation. */
+export type CacheChangeHints = {
+ /** Windows proven unchanged. Missing IDs mean unknown, never unchanged. */
+ unchangedViews?: string[];
+ /** Known changed Quick Access buckets; [] proves no search change. */
searchChangedBuckets?: string[];
};
-export type HydrationResult = HydrationSearchChanges &
+/** Previous name, kept until the cache worker adopts CacheChangeHints. */
+export type HydrationSearchChanges = CacheChangeHints;
+
+export type HydrationResult = CacheChangeHints &
(
| { kind: 'data'; data: unknown; revision: CacheRevision }
| { kind: 'void'; revision: CacheRevision }
@@ -619,7 +631,7 @@ export type RecordFieldChange =
}
| { kind: 'invalidate'; key: string };
-export type WriteResult = HydrationSearchChanges & {
+export type WriteResult = CacheChangeHints & {
/** Effective view changes. Missing metadata requires a conservative reread. */
fieldChanges?: RecordFieldChange[];
/** Bindings omitted while committing an otherwise normalizable response. */
@@ -963,11 +975,11 @@ export type CachePush =
kind: 'cache-changed';
revision: CacheRevision;
reset?: boolean;
- } & HydrationSearchChanges)
+ } & CacheChangeHints)
| ({
kind: 'cache-hydrated';
revision: CacheRevision;
- } & HydrationSearchChanges)
+ } & CacheChangeHints)
| { kind: 'mutation-settled'; settlement: MutationSettlement };
export type WorkerMessage = CacheResponse | CachePush;
@@ -1094,16 +1106,26 @@ export function isCachePush(value: unknown): value is CachePush {
'revision',
'reset',
'searchChangedBuckets',
+ 'unchangedViews',
]) &&
isCacheRevision(value.revision) &&
(value.reset === undefined || typeof value.reset === 'boolean') &&
+ (value.unchangedViews === undefined ||
+ isWireStringArray(value.unchangedViews)) &&
(value.searchChangedBuckets === undefined ||
isWireStringArray(value.searchChangedBuckets))
);
case 'cache-hydrated':
return (
- hasOnlyWireKeys(value, ['kind', 'revision', 'searchChangedBuckets']) &&
+ hasOnlyWireKeys(value, [
+ 'kind',
+ 'revision',
+ 'searchChangedBuckets',
+ 'unchangedViews',
+ ]) &&
isCacheRevision(value.revision) &&
+ (value.unchangedViews === undefined ||
+ isWireStringArray(value.unchangedViews)) &&
(value.searchChangedBuckets === undefined ||
isWireStringArray(value.searchChangedBuckets))
);
diff --git a/apps/web/src/lib/queries/calendar/occurrences.ts b/apps/web/src/lib/queries/calendar/occurrences.ts
index fd23d3f77b..c40f277b19 100644
--- a/apps/web/src/lib/queries/calendar/occurrences.ts
+++ b/apps/web/src/lib/queries/calendar/occurrences.ts
@@ -272,22 +272,24 @@ export async function invalidateCalendarOccurrences(
* a refetch that skipped the delta could reread a stale covered week.
*/
export async function syncCalendarOccurrences() {
- const controller = activeCalendarSyncController();
- await Telemetry.span('calendar.occurrences_delta_sync', async (span) => {
- span.setAttr('calendar.transport', controller ? 'graphql' : 'rest');
- if (!controller) return;
- try {
- await controller.runDelta();
- span.setAttr('calendar.delta.outcome', 'synced');
- } catch (error) {
- span.setAttr('calendar.delta.outcome', 'failed');
- span.error('Calendar delta sync failed');
- console.warn('Calendar delta sync failed', error);
- }
+ return Telemetry.span('calendar.occurrences_sync', async (parent) => {
+ const controller = activeCalendarSyncController();
+ await parent.span('calendar.occurrences_delta_sync', async (span) => {
+ span.setAttr('calendar.transport', controller ? 'graphql' : 'rest');
+ if (!controller) return;
+ try {
+ await controller.runDelta();
+ span.setAttr('calendar.delta.outcome', 'synced');
+ } catch (error) {
+ span.setAttr('calendar.delta.outcome', 'failed');
+ span.error('Calendar delta sync failed');
+ console.warn('Calendar delta sync failed', error);
+ }
+ });
+ return parent.span('calendar.occurrences_refetch', () =>
+ queryClient.invalidateQueries({
+ queryKey: calendarKeys.occurrences._def,
+ })
+ );
});
- return Telemetry.span('calendar.occurrences_refetch', () =>
- queryClient.invalidateQueries({
- queryKey: calendarKeys.occurrences._def,
- })
- );
}
diff --git a/apps/web/src/lib/queries/channel/get-or-create-dm.ts b/apps/web/src/lib/queries/channel/get-or-create-dm.ts
index 59be37696d..2b599f5009 100644
--- a/apps/web/src/lib/queries/channel/get-or-create-dm.ts
+++ b/apps/web/src/lib/queries/channel/get-or-create-dm.ts
@@ -1,5 +1,6 @@
import { fireAndForget } from '@core/util/fireAndForget';
import { throwOnErr } from '@core/util/result';
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
import { type MutationCallbacks, withCallbacks } from '@queries/utils';
import {
type GetOrCreateChannelResponse,
@@ -11,6 +12,7 @@ import { invalidateListChannels } from './channels';
type GetOrCreateDmResponse = GetOrCreateChannelResponse;
type GetOrCreateDirectMessageParams = {
+ parentSpan?: TraceContext;
recipient_id: string;
};
@@ -29,9 +31,11 @@ export function useGetOrCreateDirectMessageMutation(
gcTime: 0,
mutationFn: async (vars: GetOrCreateDirectMessageParams) => {
return await throwOnErr(async () =>
- storageServiceClient.getOrCreateDirectMessage({
- recipient_id: vars.recipient_id,
- })
+ (vars.parentSpan ?? Telemetry.captureContext()).run(() =>
+ storageServiceClient.getOrCreateDirectMessage({
+ recipient_id: vars.recipient_id,
+ })
+ )
);
},
...withCallbacks<
@@ -47,7 +51,8 @@ export function useGetOrCreateDirectMessageMutation(
onSettled: () =>
fireAndForget(invalidateListChannels(), 'channel-list'),
},
- callbacks
+ callbacks,
+ (variables) => variables.parentSpan
),
}));
}
diff --git a/apps/web/src/lib/queries/channel/tests/picture.test.tsx b/apps/web/src/lib/queries/channel/tests/picture.test.tsx
index 48dddf657f..465939cb23 100644
--- a/apps/web/src/lib/queries/channel/tests/picture.test.tsx
+++ b/apps/web/src/lib/queries/channel/tests/picture.test.tsx
@@ -19,7 +19,8 @@ vi.mock('../../client', () => ({
return client;
},
}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
staticFileSizedEndpoint: (id: string) => `/file/${id}`,
}));
vi.mock('../../preview/dataloader', () => ({
diff --git a/apps/web/src/lib/queries/client.ts b/apps/web/src/lib/queries/client.ts
index c95bcacd8c..4cd54e59d7 100644
--- a/apps/web/src/lib/queries/client.ts
+++ b/apps/web/src/lib/queries/client.ts
@@ -7,6 +7,7 @@ import { isPlatform } from '@core/util/platform';
import { thrownResultErrorHasCode } from '@core/util/result';
import { onlineManager } from '@tanstack/query-core';
import { QueryClient } from '@tanstack/solid-query';
+import { traceQueriesToFlows } from './flow-trace';
import { setupQueryPersistence } from './persistence';
import { createQueryPersistenceScopes } from './persistence-scopes';
import { initSoupNormalizer } from './soup/normalized-cache/normalizer';
@@ -33,6 +34,8 @@ export const queryClient = new QueryClient({
},
});
+traceQueriesToFlows(queryClient);
+
if (isPlatform(['ios', 'android'])) {
// Use the native default network path on both mobile platforms.
onlineManager.setEventListener((setOnline) =>
diff --git a/apps/web/src/lib/queries/email/draft.ts b/apps/web/src/lib/queries/email/draft.ts
index 27aa76b155..1319270b01 100644
--- a/apps/web/src/lib/queries/email/draft.ts
+++ b/apps/web/src/lib/queries/email/draft.ts
@@ -1,7 +1,7 @@
import { DraftTransferAborted } from '@app/features/email-compose/context/compose-capabilities';
import { fireAndForget } from '@core/util/fireAndForget';
import { throwOnErr } from '@core/util/result';
-import { Telemetry } from '@macro-inc/observability';
+import { type Span, Telemetry } from '@macro-inc/observability';
import { invalidateAllSoup, refetchSoupEntity } from '@queries/soup/cache';
import { emailClient } from '@service-email/client';
import type {
@@ -188,7 +188,7 @@ export function transferEmailDraft(input: {
fireAndForget(
span.span('email.draft_transfer.refresh', async (refresh) => {
try {
- await refreshTransferredThreads(result);
+ await refreshTransferredThreads(result, refresh);
} catch (error) {
refresh.error('Draft transfer refresh failed');
throw error;
@@ -200,18 +200,23 @@ export function transferEmailDraft(input: {
});
}
-async function refreshTransferredThreads(result: TransferDraftResponse) {
+async function refreshTransferredThreads(
+ result: TransferDraftResponse,
+ parent: Span
+) {
await getGraphqlCacheHost()?.deleteRecords([
`GraphqlSoupEmailMessage:${result.source_id}`,
]);
await Promise.all([
- refreshEmailThreadCache(result.source_thread_id),
- refreshEmailThreadCache(result.thread_id),
+ parent.run(() => refreshEmailThreadCache(result.source_thread_id)),
+ parent.run(() => refreshEmailThreadCache(result.thread_id)),
]);
for (const threadId of [result.source_thread_id, result.thread_id]) {
- await queryClient.invalidateQueries({
- queryKey: emailKeys.threadMessages(threadId).queryKey,
- });
+ await parent.run(() =>
+ queryClient.invalidateQueries({
+ queryKey: emailKeys.threadMessages(threadId).queryKey,
+ })
+ );
}
invalidateAllSoup();
}
diff --git a/apps/web/src/lib/queries/email/queued-sends.test.ts b/apps/web/src/lib/queries/email/queued-sends.test.ts
index 0e23e21071..47a31a5fd1 100644
--- a/apps/web/src/lib/queries/email/queued-sends.test.ts
+++ b/apps/web/src/lib/queries/email/queued-sends.test.ts
@@ -11,6 +11,7 @@ const mocks = vi.hoisted(() => ({
info: vi.fn(),
}));
vi.mock('@macro-inc/observability', () => ({
+ NOOP_SPAN: {},
Telemetry: { info: mocks.info, warn: mocks.warn },
}));
vi.mock('./send-queue', async (original) => ({
diff --git a/apps/web/src/lib/queries/flow-trace.test.ts b/apps/web/src/lib/queries/flow-trace.test.ts
new file mode 100644
index 0000000000..1b881f1e1b
--- /dev/null
+++ b/apps/web/src/lib/queries/flow-trace.test.ts
@@ -0,0 +1,45 @@
+import { QueryClient } from '@tanstack/solid-query';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { traceQueriesToFlows } from './flow-trace';
+
+const { flow } = vi.hoisted(() => ({
+ flow: { open: true, active: [] as string[] },
+}));
+
+vi.mock('@app/observability/flow', () => ({
+ useFlowTrace: () =>
+ flow.open
+ ? {
+ run<T>(work: () => T): T {
+ flow.active.push('view.home');
+ try {
+ return work();
+ } finally {
+ flow.active.pop();
+ }
+ },
+ }
+ : undefined,
+}));
+
+describe('traceQueriesToFlows', () => {
+ afterEach(() => {
+ flow.open = true;
+ });
+
+ it('starts query functions in the flow that defaulted their options', async () => {
+ const client = new QueryClient();
+ traceQueriesToFlows(client);
+ const startedIn: (string | undefined)[] = [];
+ const queryFn = async () => {
+ startedIn.push(flow.active.at(-1));
+ return 1;
+ };
+
+ await client.fetchQuery({ queryKey: ['inside'], queryFn });
+ flow.open = false;
+ await client.fetchQuery({ queryKey: ['outside'], queryFn });
+
+ expect(startedIn).toEqual(['view.home', undefined]);
+ });
+});
diff --git a/apps/web/src/lib/queries/flow-trace.ts b/apps/web/src/lib/queries/flow-trace.ts
new file mode 100644
index 0000000000..308234b2a5
--- /dev/null
+++ b/apps/web/src/lib/queries/flow-trace.ts
@@ -0,0 +1,23 @@
+import { useFlowTrace } from '@app/observability/flow';
+import type { QueryClient } from '@tanstack/solid-query';
+
+/**
+ * Runs each query function in the trace of the view that created the query,
+ * so its requests join that view's load (see `Flow.run`). Observers default
+ * their options during component setup, where the flow is in scope; options
+ * defaulted elsewhere, and refetches after the view settled, are untouched.
+ */
+export function traceQueriesToFlows(client: QueryClient): void {
+ const defaultQueryOptions = client.defaultQueryOptions.bind(client);
+ client.defaultQueryOptions = ((options) => {
+ const defaulted = defaultQueryOptions(options);
+ if (options._defaulted) return defaulted;
+ const parent = useFlowTrace();
+ const queryFn = defaulted.queryFn;
+ if (!parent || typeof queryFn !== 'function') return defaulted;
+ return {
+ ...defaulted,
+ queryFn: (context) => parent.run(() => queryFn(context)),
+ };
+ }) as QueryClient['defaultQueryOptions'];
+}
diff --git a/apps/web/src/lib/queries/mcp-servers.ts b/apps/web/src/lib/queries/mcp-servers.ts
index 29df0e899c..b2d5368f84 100644
--- a/apps/web/src/lib/queries/mcp-servers.ts
+++ b/apps/web/src/lib/queries/mcp-servers.ts
@@ -1,4 +1,5 @@
import { throwOnErr } from '@core/util/result';
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
import { queryClient } from '@queries/client';
import { cognitionApiServiceClient } from '@service-cognition/client';
import type {
@@ -123,9 +124,15 @@ export function useDeleteMcpServerMutation() {
export function useStartMcpAuthMutation() {
return useMutation(() => ({
- mutationFn: async (request: StartAuthRequest) =>
+ mutationFn: async ({
+ parentSpan,
+ ...request
+ }: StartAuthRequest & { parentSpan?: TraceContext }) =>
throwOnErr(
- async () => await cognitionApiServiceClient.startMcpAuth(request)
+ async () =>
+ await (parentSpan ?? Telemetry.captureContext()).run(() =>
+ cognitionApiServiceClient.startMcpAuth(request)
+ )
),
}));
}
diff --git a/apps/web/src/lib/queries/messages/mutations.ts b/apps/web/src/lib/queries/messages/mutations.ts
index b4dd16bb61..06e1216697 100644
--- a/apps/web/src/lib/queries/messages/mutations.ts
+++ b/apps/web/src/lib/queries/messages/mutations.ts
@@ -4,7 +4,7 @@ import { toast } from '@core/component/Toast/Toast';
import type { DateValue } from '@core/util/date';
import { fireAndForget } from '@core/util/fireAndForget';
import { markMessageSent } from '@core/util/message-send-motion';
-import { Telemetry } from '@macro-inc/observability';
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
import {
messageReferencesCrmRecord,
refreshCrmAssociatedSoupQueries,
@@ -401,12 +401,15 @@ export function newMessageId(): string {
}
type SendMessageParams = {
+ parentSpan?: TraceContext;
parent: MessageParent;
message: PostMessage;
optimisticAttachments?: readonly OptimisticPostMessageAttachment[];
/** From `newMessageId`; the message's final id, not a placeholder. */
optimisticId: string;
senderId: string;
+ /** Called once the optimistic message is in the timeline. */
+ onOptimisticInsert?: () => void;
};
type SendMessageContext = {
@@ -432,11 +435,13 @@ export function useSendMessageMutation(
mutationFn: async (vars: SendMessageParams) => {
// The server keeps optimisticId as the message id, so the optimistic
// message never changes id; it is also the nonce the server echoes.
- return entityMessagesClient.post(vars.parent, {
- ...vars.message,
- id: vars.optimisticId,
- nonce: vars.optimisticId,
- });
+ return (vars.parentSpan ?? Telemetry.captureContext()).run(() =>
+ entityMessagesClient.post(vars.parent, {
+ ...vars.message,
+ id: vars.optimisticId,
+ nonce: vars.optimisticId,
+ })
+ );
},
...withCallbacks<
EntityMessage,
@@ -457,6 +462,7 @@ export function useSendMessageMutation(
optimisticAttachments: vars.optimisticAttachments,
...vars.message,
});
+ vars.onOptimisticInsert?.();
const updatedAt =
vars.parent.type === 'channel'
? optimisticUpdateSoupItemUpdatedAt(
@@ -541,7 +547,8 @@ export function useSendMessageMutation(
);
},
},
- callbacks
+ callbacks,
+ (variables) => variables.parentSpan
),
}));
}
diff --git a/apps/web/src/lib/queries/pipedream-connectors.ts b/apps/web/src/lib/queries/pipedream-connectors.ts
index b503ef3a45..487f8f8947 100644
--- a/apps/web/src/lib/queries/pipedream-connectors.ts
+++ b/apps/web/src/lib/queries/pipedream-connectors.ts
@@ -433,10 +433,12 @@ async function connectOverlaidApp(
const deadline = Date.now() + OVERLAY_AUTH_TIMEOUT_MS;
while (Date.now() < deadline && currentUserId() === userId) {
const closed = popup?.closed ?? false;
- const servers = await queryClient.fetchQuery({
- ...mcpServersQueryOptions(),
- staleTime: 0,
- });
+ const servers = await consent.run(() =>
+ queryClient.fetchQuery({
+ ...mcpServersQueryOptions(),
+ staleTime: 0,
+ })
+ );
if (overlaidSlugsConnected([overlay], servers).length > 0) {
return 'connected';
}
diff --git a/apps/web/src/lib/queries/soup/graphql/cache-activity-telemetry.test.ts b/apps/web/src/lib/queries/soup/graphql/cache-activity-telemetry.test.ts
new file mode 100644
index 0000000000..6a4d2f1b09
--- /dev/null
+++ b/apps/web/src/lib/queries/soup/graphql/cache-activity-telemetry.test.ts
@@ -0,0 +1,62 @@
+import { expect, it, vi } from 'vitest';
+import { createSoupCacheTelemetry } from './cache-activity-telemetry';
+
+it('bounds exports by time across all active views and preserves totals', () => {
+ let time = 0;
+ const report = vi.fn();
+ const telemetry = createSoupCacheTelemetry({ now: () => time, report });
+ for (let i = 0; i < 10_000; i++) {
+ telemetry.record('predicate', { durationMs: 2, rows: 20, patches: 1 });
+ telemetry.record('local', { durationMs: 3, retries: 1 });
+ }
+ expect(report).not.toHaveBeenCalled();
+ time = 300_000;
+ telemetry.record('local', { error: true, durationMs: 5 });
+ expect(report).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ 'cache.summary_interval_ms': 300_000,
+ 'cache.predicate.count': 10_000,
+ 'cache.predicate.duration_total_ms': 20_000,
+ 'cache.predicate.duration_max_ms': 2,
+ 'cache.predicate.rows_total': 200_000,
+ 'cache.predicate.patches': 10_000,
+ 'cache.local.count': 10_001,
+ 'cache.local.duration_total_ms': 30_005,
+ 'cache.local.duration_max_ms': 5,
+ 'cache.local.errors': 1,
+ 'cache.local.retries': 10_000,
+ })
+ );
+ telemetry.record('predicate', { discarded: true });
+ expect(report).toHaveBeenCalledTimes(1);
+ time = 600_000;
+ telemetry.record('generation');
+ expect(report).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ 'cache.predicate.count': 1,
+ 'cache.predicate.discarded': 1,
+ })
+ );
+ expect(report.mock.calls[1][0]).not.toHaveProperty('cache.local.count');
+});
+
+it('isolates exporter failure and retries retained counters at the next interval', () => {
+ let time = 0;
+ const report = vi.fn().mockImplementationOnce(() => {
+ throw new Error('offline exporter');
+ });
+ const telemetry = createSoupCacheTelemetry({ now: () => time, report });
+ time = 300_000;
+ expect(() => telemetry.record('local', { rows: 20 })).not.toThrow();
+ for (let i = 0; i < 100; i++) telemetry.record('local', { rows: 20 });
+ expect(report).toHaveBeenCalledTimes(1);
+ time = 600_000;
+ telemetry.record('local', { rows: 20 });
+ expect(report).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ 'cache.summary_interval_ms': 600_000,
+ 'cache.local.count': 102,
+ 'cache.local.rows_total': 2_040,
+ })
+ );
+});
diff --git a/apps/web/src/lib/queries/soup/graphql/cache-activity-telemetry.ts b/apps/web/src/lib/queries/soup/graphql/cache-activity-telemetry.ts
new file mode 100644
index 0000000000..e4dff8607f
--- /dev/null
+++ b/apps/web/src/lib/queries/soup/graphql/cache-activity-telemetry.ts
@@ -0,0 +1,89 @@
+import { Telemetry } from '@macro-inc/observability';
+
+type Activity =
+ | 'predicate'
+ | 'local'
+ | 'authority-network'
+ | 'authority-failed-network'
+ | 'authority-local'
+ | 'authority-stale-fallback'
+ | 'stale-fallback'
+ | 'generation';
+
+type Sample = {
+ durationMs?: number;
+ rows?: number;
+ upserts?: number;
+ patches?: number;
+ removed?: number;
+ retries?: number;
+ error?: boolean;
+ incomplete?: boolean;
+ discarded?: boolean;
+};
+
+const SUMMARY_INTERVAL_MS = 5 * 60_000;
+
+/** One bounded owner for routine cache activity, shared by all Soup views.
+ * Initial loading belongs to usePending. Updates only change numeric counters;
+ * the next active sample after five minutes emits one summary. No per-view
+ * timers, span trees, query names, revisions, or entity identifiers are retained.
+ */
+export function createSoupCacheTelemetry({
+ now = () => performance.now(),
+ report = (attributes: Record<string, number>) =>
+ Telemetry.info('graphql_cache.soup_updates.summary', attributes),
+}: {
+ now?: () => number;
+ report?: (attributes: Record<string, number>) => void;
+} = {}) {
+ const counters = new Map<Activity, Record<string, number>>();
+ let startedAt = now();
+ let nextReportAt = startedAt + SUMMARY_INTERVAL_MS;
+
+ return {
+ record(activity: Activity, sample: Sample = {}): void {
+ const counts = counters.get(activity) ?? {};
+ counts.count = (counts.count ?? 0) + 1;
+ for (const key of ['upserts', 'patches', 'removed', 'retries'] as const)
+ counts[key] = (counts[key] ?? 0) + (sample[key] ?? 0);
+ counts.incomplete =
+ (counts.incomplete ?? 0) + Number(sample.incomplete ?? false);
+ counts.errors = (counts.errors ?? 0) + Number(sample.error ?? false);
+ counts.discarded =
+ (counts.discarded ?? 0) + Number(sample.discarded ?? false);
+ if (sample.durationMs !== undefined) {
+ counts.duration_total_ms =
+ (counts.duration_total_ms ?? 0) + sample.durationMs;
+ counts.duration_max_ms = Math.max(
+ counts.duration_max_ms ?? 0,
+ sample.durationMs
+ );
+ }
+ if (sample.rows !== undefined) {
+ counts.rows_total = (counts.rows_total ?? 0) + sample.rows;
+ counts.rows_max = Math.max(counts.rows_max ?? 0, sample.rows);
+ }
+ counters.set(activity, counts);
+ const time = now();
+ if (time < nextReportAt) return;
+ nextReportAt = time + SUMMARY_INTERVAL_MS;
+ const attributes: Record<string, number> = {
+ 'cache.summary_interval_ms': time - startedAt,
+ };
+ for (const [kind, values] of counters)
+ for (const [key, value] of Object.entries(values))
+ attributes[`cache.${kind}.${key}`] = value;
+ try {
+ report(attributes);
+ counters.clear();
+ startedAt = time;
+ } catch {
+ // Keep the counters for the next interval. Export failure must never
+ // reject a cache read or retry logging at the cache-update frequency.
+ }
+ },
+ };
+}
+
+export const soupCacheTelemetry = createSoupCacheTelemetry();
diff --git a/apps/web/src/lib/queries/soup/graphql/create-grouped-soup-live-query.test.ts b/apps/web/src/lib/queries/soup/graphql/create-grouped-soup-live-query.test.ts
index 94621e3768..0006774826 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-grouped-soup-live-query.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-grouped-soup-live-query.test.ts
@@ -41,17 +41,6 @@ vi.mock('../../../service-clients/service-storage/graphql-soup', () => ({
getGraphqlSoupCacheHost: mocks.host,
getGraphqlSoupClient: mocks.client,
}));
-vi.mock('@macro-inc/observability', () => ({
- Telemetry: {
- span: () => ({
- setAttr: vi.fn(),
- error: vi.fn(),
- end: vi.fn(),
- run: (operation: () => unknown) => operation(),
- }),
- error: vi.fn(),
- },
-}));
const cleanups: Array<() => void> = [];
afterEach(() => {
diff --git a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
index b5bd3a1c4d..29d51b386e 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts
@@ -1,7 +1,8 @@
import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { Telemetry } from '@macro-inc/observability';
import { gql } from '@urql/core';
import { createComputed, createRoot, createSignal } from 'solid-js';
-import { afterEach, expect, it } from 'vitest';
+import { afterEach, expect, it, vi } from 'vitest';
import { selectRecords } from '../../../graphql-cache/exchange/record-selection';
import { createNoopCacheHost } from '../../../graphql-cache/host/noop-host';
import type {
@@ -244,3 +245,23 @@ it('does not recreate held rows when host setup reads an unrelated signal', asyn
expect(state.requests).toHaveLength(1);
expect(state.query.data()!.records).toBe(rows);
});
+
+it('does not create root performance spans for repeated cache evaluations', async () => {
+ const span = vi.spyOn(Telemetry, 'span');
+ try {
+ const state = setup();
+ state.requests[0].resolve(snapshot());
+ await flush();
+ for (let index = 1; index <= 100; index++) {
+ state.query.refresh();
+ state.requests[index].resolve(patch(String(index + 1)));
+ await flush();
+ }
+ expect(state.query.data()?.revision).toBe('101');
+ expect(span).not.toHaveBeenCalledWith('urql.reconcile', {
+ sampling: 'perf',
+ });
+ } finally {
+ span.mockRestore();
+ }
+});
diff --git a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
index 79f3068736..f09dac173e 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import {
type Accessor,
@@ -17,6 +18,7 @@ import {
type EntityFilterCacheArgs,
parseCacheRevision,
} from '../../../graphql-cache/protocol';
+import { soupCacheTelemetry } from './cache-activity-telemetry';
/** A declared source and generated fragment; no mutation-specific query updates. */
export type PredicateQueryRequest<T> = {
@@ -112,15 +114,25 @@ export function createPredicateQuery<T extends object>(options: {
while (pending && active) {
pending = false;
const observedEpoch = epoch;
+ let outcome: 'success' | 'unsupported' | 'error' | 'discarded' =
+ 'discarded';
+ let upserts = 0;
+ let patches = 0;
+ let removed = 0;
+ const startedAt = performance.now();
try {
const result = await host.entityFilter(args());
if (!active || epoch !== observedEpoch) continue;
if (result.kind !== 'live-query') {
+ outcome = 'unsupported';
unsupported = true;
pending = false;
setStatus('unsupported');
continue;
}
+ upserts = result.upserts.length;
+ patches = result.patches.length;
+ removed = result.removed.length;
const revision = parseCacheRevision(result.revision);
if (latest !== undefined && BigInt(revision) < BigInt(latest)) {
pending = true;
@@ -201,10 +213,23 @@ export function createPredicateQuery<T extends object>(options: {
setStatus('ready');
})
);
+ outcome = 'success';
} catch (cause) {
if (!active || epoch !== observedEpoch) continue;
+ outcome = 'error';
setError(() => cause);
setStatus('error');
+ } finally {
+ soupCacheTelemetry.record('predicate', {
+ durationMs: performance.now() - startedAt,
+ rows: orderedRows.length,
+ upserts,
+ patches,
+ removed,
+ error: outcome === 'error',
+ discarded: outcome === 'discarded',
+ incomplete: outcome === 'unsupported',
+ });
}
}
} finally {
@@ -254,5 +279,6 @@ export function createPredicateQuery<T extends object>(options: {
});
})
);
+ usePending('soup.cache', () => status() === 'loading');
return { data, status, error, refresh: () => requestRefresh() };
}
diff --git a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
index a1f622cee0..95777e51eb 100644
--- a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
+++ b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts
@@ -1,3 +1,4 @@
+import { usePending } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import { Telemetry } from '@macro-inc/observability';
import { until } from '@solid-primitives/promise';
@@ -50,6 +51,7 @@ import {
import { createUrqlInfiniteQuery } from '../../../urql-solid/create-urql-infinite-query';
import type { UrqlInfiniteData } from '../../../urql-solid/types';
import { registerGraphqlSoupRevalidations } from './active-queries';
+import { soupCacheTelemetry } from './cache-activity-telemetry';
import { createPredicateQuery } from './create-predicate-query';
import {
buildGraphqlEntitiesSoupInput,
@@ -211,6 +213,11 @@ export function createSoupLiveQuery(
const mailItemSelection = selectRecords(MailItemFieldsFragmentDoc);
let localRequest = 0;
let localEvaluationRunning = false;
+ const [initialLocalEvaluation, setInitialLocalEvaluation] =
+ createSignal(false);
+ usePending('soup.local', initialLocalEvaluation);
+ let initialLocalInput: GraphqlSoupInput | undefined;
+ let initialLocalGeneration: number | undefined;
let localEvaluationPending = false;
let cacheGeneration = 0;
let cacheObservation = 0;
@@ -225,22 +232,19 @@ export function createSoupLiveQuery(
// The server page fetched only to keep the server pages as deep as a local
// Mail list (fetchNextPage). It never takes over from that list.
let inStepPageIndex: number | undefined;
- let staleFallbackSpan: ReturnType<typeof Telemetry.span> | undefined;
+ let staleFallbackStartedAt: number | undefined;
const recordAuthority = (
- source: 'network' | 'failed-network' | 'local' | 'stale-fallback',
- pageIndex?: number
- ) => {
- const span = Telemetry.span('graphql_cache.soup_authority');
- span.setAttr('authority.source', source);
- if (pageIndex !== undefined)
- span.setAttr('authority.page_index', pageIndex);
- span.end();
- };
- const finishStaleFallback = (source: 'network' | 'local') => {
- staleFallbackSpan?.setAttr('authority.resumed_by', source);
- staleFallbackSpan?.end();
- staleFallbackSpan = undefined;
+ source: 'network' | 'failed-network' | 'local' | 'stale-fallback'
+ ) => soupCacheTelemetry.record(`authority-${source}`);
+ const finishStaleFallback = (discarded = false) => {
+ if (staleFallbackStartedAt !== undefined) {
+ soupCacheTelemetry.record('stale-fallback', {
+ durationMs: performance.now() - staleFallbackStartedAt,
+ discarded,
+ });
+ }
+ staleFallbackStartedAt = undefined;
};
const hasUnpersistedPages = (input: GraphqlSoupInput | undefined) =>
@@ -321,11 +325,9 @@ export function createSoupLiveQuery(
if (
networkAuthorityRevision() !== undefined &&
networkAuthorityRevision() !== revision &&
- staleFallbackSpan === undefined
+ staleFallbackStartedAt === undefined
) {
- staleFallbackSpan = Telemetry.span(
- 'graphql_cache.soup_stale_fallback'
- );
+ staleFallbackStartedAt = performance.now();
recordAuthority('stale-fallback');
}
setCurrentCacheRevision(revision);
@@ -334,16 +336,14 @@ export function createSoupLiveQuery(
{ includeHydration: true }
);
const unsubscribeGeneration = host.onCacheGenerationChanged(() => {
- const span = Telemetry.span('graphql_cache.engine_generation_changed');
- span.end();
+ soupCacheTelemetry.record('generation');
cacheGeneration += 1;
invalidateGeneration();
fireAndForget(observeCurrentRevision(), 'soup-live-query');
});
fireAndForget(observeCurrentRevision(), 'soup-live-query');
onCleanup(() => {
- staleFallbackSpan?.end();
- staleFallbackSpan = undefined;
+ finishStaleFallback(true);
cacheGeneration += 1;
unsubscribeChanges();
unsubscribeGeneration();
@@ -415,7 +415,7 @@ export function createSoupLiveQuery(
if (result.error && metadata?.source === 'live-network') {
// The exchange keeps the rows already shown; a failed response's
// partial data claims no authority over them or the local rows.
- recordAuthority('failed-network', page.pageIndex);
+ recordAuthority('failed-network');
return;
}
if (!result.data) return;
@@ -453,7 +453,7 @@ export function createSoupLiveQuery(
if (!untrack(localProjection)?.mail) setLocalProjection(undefined);
});
recordAuthority('network');
- finishStaleFallback('network');
+ finishStaleFallback();
fireAndForget(
acknowledgeNetworkPage(
page.pageIndex,
@@ -476,12 +476,14 @@ export function createSoupLiveQuery(
if (!untrack(localProjection)?.mail) setLocalProjection(undefined);
});
recordAuthority('network');
- finishStaleFallback('network');
+ finishStaleFallback();
},
select: selectPages,
};
});
+ usePending('soup.network', () => query.isLoading);
+
const isEnabled = () =>
cacheFirstEntities()
? options().enabled !== false && !options().localOnly && isSupported()
@@ -763,11 +765,20 @@ export function createSoupLiveQuery(
return;
}
localEvaluationRunning = true;
+ if (
+ initialLocalInput !== input ||
+ initialLocalGeneration !== cacheGeneration
+ ) {
+ initialLocalInput = input;
+ initialLocalGeneration = cacheGeneration;
+ setInitialLocalEvaluation(true);
+ }
localEvaluationPending = false;
fireAndForget(
(async () => {
- const span = Telemetry.span('graphql_cache.soup_local_evaluation');
+ const startedAt = performance.now();
+ let evaluatedRows = records.length;
let retryCount = 0;
let discarded = false;
let outcome: 'success' | 'incomplete' | 'error' = 'incomplete';
@@ -802,9 +813,8 @@ export function createSoupLiveQuery(
continue;
}
if (mailView) {
- span.setAttr('evaluation.through', Boolean(through));
if (result.kind === 'mail-page')
- span.setAttr('evaluation.depth', result.keys.length);
+ evaluatedRows = result.keys.length;
}
if (
mailView &&
@@ -894,11 +904,7 @@ export function createSoupLiveQuery(
});
outcome = 'success';
recordAuthority('local');
- finishStaleFallback('local');
- span.setAttr(
- 'evaluation.retained_count',
- result.retainedKeys?.length ?? 0
- );
+ finishStaleFallback();
return;
}
} catch {
@@ -909,10 +915,15 @@ export function createSoupLiveQuery(
// Only the latest request decides, after any stale-revision retries.
if (mailView && requestId === localRequest && outcome !== 'success')
setLocalMailCurrent(false);
- span.setAttr('evaluation.outcome', outcome);
- span.setAttr('evaluation.retry_count', retryCount);
- span.setAttr('evaluation.discarded', discarded);
- span.end();
+ soupCacheTelemetry.record('local', {
+ durationMs: performance.now() - startedAt,
+ rows: evaluatedRows,
+ error: outcome === 'error',
+ incomplete: outcome === 'incomplete',
+ retries: retryCount,
+ discarded,
+ });
+ setInitialLocalEvaluation(false);
localEvaluationRunning = false;
if (localEvaluationPending) {
localEvaluationPending = false;
diff --git a/apps/web/src/lib/queries/soup/graphql/grouped-items-offline.test.ts b/apps/web/src/lib/queries/soup/graphql/grouped-items-offline.test.ts
index d014a72f88..d05b869cde 100644
--- a/apps/web/src/lib/queries/soup/graphql/grouped-items-offline.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/grouped-items-offline.test.ts
@@ -11,9 +11,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
import { makeSubject } from 'wonka';
const mocks = vi.hoisted(() => ({ client: vi.fn(), local: vi.fn() }));
-vi.mock('@macro-inc/observability', () => ({
- Telemetry: { error: vi.fn() },
-}));
+
vi.mock('@app/lib/graphql-cache', () => ({
normalizedCacheResultMetadata: () => undefined,
}));
diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.ts
index be2ade5ed9..a2be44aea6 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts
@@ -30,13 +30,6 @@ const mapSoupPageToEntityListMock = vi.hoisted(() =>
);
const makeGraphqlSoupInputMock = vi.hoisted(() => vi.fn());
-vi.mock('@macro-inc/observability', () => ({
- Telemetry: {
- error: vi.fn(),
- span: vi.fn(() => ({ setAttr: vi.fn(), end: vi.fn() })),
- },
-}));
-
vi.mock('../../../graphql-cache/exchange/record-selection', () => ({
selectRecords: vi.fn((document) => ({ document })),
readRecordsByKeys: readRecordsByKeysMock,
diff --git a/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.test.ts b/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.test.ts
index 43391457ad..7b9fce212e 100644
--- a/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.test.ts
+++ b/apps/web/src/lib/queries/soup/grouped/graphql/create-graphql-grouped-soup-queries.test.ts
@@ -15,10 +15,6 @@ const mapGraphqlGroupedSoupPageMock = vi.hoisted(() =>
vi.fn((data: { page: unknown }) => data.page)
);
-vi.mock('@macro-inc/observability', () => ({
- Telemetry: { error: vi.fn() },
-}));
-
vi.mock('@queries/soup/grouped/api', () => ({
makeGroupComparator: () => (left: { key: string }, right: { key: string }) =>
left.key.localeCompare(right.key),
diff --git a/apps/web/src/lib/queries/storage/file-document.ts b/apps/web/src/lib/queries/storage/file-document.ts
index 68d4bf8c8d..b5353c41f7 100644
--- a/apps/web/src/lib/queries/storage/file-document.ts
+++ b/apps/web/src/lib/queries/storage/file-document.ts
@@ -70,24 +70,27 @@ export async function getFileDocumentBlob(
},
options?: GetFileBlobOptions
): Promise<Blob> {
+ const parent = options?.span ?? Telemetry.captureContext();
const url = await getFileDocumentUrl(data, options?.span);
options?.signal?.throwIfAborted();
- return (options?.span ?? Telemetry).span('file.transfer', async (span) => {
- span.setAttr('document.id', data.documentId);
- span.setAttr('document.version_id', data.documentVersionId);
- try {
- const blob = await throwOnErr(() =>
- options?.onProgress
- ? fetchPresignedBlobWithProgress(url, options.onProgress, {
- signal: options.signal,
- })
- : fetchPresigned(url, 'blob', { signal: options?.signal })
- );
- span.setAttr('file.size', blob.size);
- return blob;
- } catch (error) {
- if (!options?.signal?.aborted) span.error(error);
- throw error;
- }
- });
+ return parent.run(() =>
+ Telemetry.span('file.transfer', async (span) => {
+ span.setAttr('document.id', data.documentId);
+ span.setAttr('document.version_id', data.documentVersionId);
+ try {
+ const blob = await throwOnErr(() =>
+ options?.onProgress
+ ? fetchPresignedBlobWithProgress(url, options.onProgress, {
+ signal: options.signal,
+ })
+ : fetchPresigned(url, 'blob', { signal: options?.signal })
+ );
+ span.setAttr('file.size', blob.size);
+ return blob;
+ } catch (error) {
+ if (!options?.signal?.aborted) span.error(error);
+ throw error;
+ }
+ })
+ );
}
diff --git a/apps/web/src/lib/queries/utils.ts b/apps/web/src/lib/queries/utils.ts
index f9815a0071..113b89c215 100644
--- a/apps/web/src/lib/queries/utils.ts
+++ b/apps/web/src/lib/queries/utils.ts
@@ -1,3 +1,4 @@
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
import type { MutationOptions } from '@tanstack/solid-query';
/**
@@ -28,27 +29,36 @@ export function withCallbacks<
TContext = unknown,
>(
defaults: MutationCallbacks<TData, TError, TVariables, TContext>,
- overrides?: MutationCallbacks<TData, TError, TVariables, TContext>
+ overrides?: MutationCallbacks<TData, TError, TVariables, TContext>,
+ parentFor?: (variables: TVariables) => TraceContext | undefined
): MutationCallbacks<TData, TError, TVariables, TContext> {
- if (!overrides) return defaults;
+ if (!overrides && !parentFor) return defaults;
return {
onMutate: async (...args) => {
- const defaultContext = await defaults.onMutate?.(...args);
- const overrideContext = await overrides.onMutate?.(...args);
+ const parent = parentFor?.(args[0]) ?? Telemetry.captureContext();
+ const defaultContext = await parent.run(() =>
+ defaults.onMutate?.(...args)
+ );
+ const overrideContext = await parent.run(() =>
+ overrides?.onMutate?.(...args)
+ );
return (overrideContext ?? defaultContext) as TContext;
},
onSuccess: async (...args) => {
- await defaults.onSuccess?.(...args);
- await overrides.onSuccess?.(...args);
+ const parent = parentFor?.(args[1]) ?? Telemetry.captureContext();
+ await parent.run(() => defaults.onSuccess?.(...args));
+ await parent.run(() => overrides?.onSuccess?.(...args));
},
onError: async (...args) => {
- await defaults.onError?.(...args);
- await overrides.onError?.(...args);
+ const parent = parentFor?.(args[1]) ?? Telemetry.captureContext();
+ await parent.run(() => defaults.onError?.(...args));
+ await parent.run(() => overrides?.onError?.(...args));
},
onSettled: async (...args) => {
- await defaults.onSettled?.(...args);
- await overrides.onSettled?.(...args);
+ const parent = parentFor?.(args[2]) ?? Telemetry.captureContext();
+ await parent.run(() => defaults.onSettled?.(...args));
+ await parent.run(() => overrides?.onSettled?.(...args));
},
};
}
diff --git a/apps/web/src/lib/service-clients/ai-editing-worker/client.test.ts b/apps/web/src/lib/service-clients/ai-editing-worker/client.test.ts
index 10d7ce084d..69966dbb2e 100644
--- a/apps/web/src/lib/service-clients/ai-editing-worker/client.test.ts
+++ b/apps/web/src/lib/service-clients/ai-editing-worker/client.test.ts
@@ -15,14 +15,11 @@ const { failure, permissionToken, span } = vi.hoisted(() => ({
}));
vi.mock('@core/component/Toast/Toast', () => ({ toast: { failure } }));
-vi.mock('@block-md/observability', () => ({
- resumeDocumentSpan: () => undefined,
-}));
vi.mock('@service-storage/client', () => ({
getDocumentPermissionToken: permissionToken,
}));
vi.mock('@macro-inc/observability', () => ({
- Telemetry: { clientSpan: () => span },
+ Telemetry: { span: () => span },
}));
const state = useAiUsageLimitState();
@@ -120,3 +117,19 @@ test('keeps successful edits and clarification requests distinct from quota fail
expect(failure).toHaveBeenCalledWith('Which paragraph?');
expect(state.usageLimitOpen()).toBe(false);
});
+
+test('runs the edit request under its explicitly supplied parent context', async () => {
+ const { NOOP_SPAN } = await vi.importActual<
+ typeof import('@macro-inc/observability')
+ >('@macro-inc/observability');
+ const run = vi.spyOn(NOOP_SPAN, 'run');
+ const parent = NOOP_SPAN;
+ fetch.mockResolvedValue(new Response('{}', { status: 200 }));
+ await requestAiEdit({
+ documentId: 'document',
+ prompt: 'test',
+ parentSpan: parent,
+ });
+ expect(run).toHaveBeenCalledOnce();
+ expect(span.injectTraceHeaders).toHaveBeenCalledOnce();
+});
diff --git a/apps/web/src/lib/service-clients/ai-editing-worker/client.ts b/apps/web/src/lib/service-clients/ai-editing-worker/client.ts
index b34525e2b3..0c39590967 100644
--- a/apps/web/src/lib/service-clients/ai-editing-worker/client.ts
+++ b/apps/web/src/lib/service-clients/ai-editing-worker/client.ts
@@ -1,7 +1,6 @@
import type { DocumentOp } from '@ai-ops/editor';
-import { resumeDocumentSpan } from '@block-md/observability';
import { MACRO_AGENT_NAME } from '@core/constant/macroAgent';
-import { Telemetry } from '@macro-inc/observability';
+import { type Span, Telemetry } from '@macro-inc/observability';
import { getDocumentPermissionToken } from '@service-storage/client';
import { createSignal } from 'solid-js';
import { developmentProxyUrl } from '../../core/constant/developmentProxy';
@@ -108,6 +107,7 @@ export function cancelAiEdit(documentId: string): void {
export async function requestAiEdit(args: {
documentId: string;
prompt: string;
+ parentSpan?: Span;
/** Defaults to the worker's `supervised` pipeline. */
mode?: AiEditMode;
onOps?: (ops: DocumentOp[]) => void;
@@ -115,13 +115,11 @@ export async function requestAiEdit(args: {
const controller = new AbortController();
editControllers.set(args.documentId, controller);
syncActiveEditDocs();
- // Parent under the document's long-lived span when one exists, so the
- // worker's whole edit trace joins the user's editing session; the injected
- // traceparent makes the worker's request span a child of this one.
- const documentSpan = resumeDocumentSpan(args.documentId);
- const span = documentSpan
- ? documentSpan.run(() => Telemetry.clientSpan('http POST /edit'))
- : Telemetry.clientSpan('http POST /edit');
+ const span = args.parentSpan
+ ? args.parentSpan.run(() =>
+ Telemetry.span('http POST /edit', { kind: 'client' })
+ )
+ : Telemetry.span('http POST /edit', { kind: 'client' });
span.setAttr('http.method', 'POST');
span.setAttr('http.url', `${AI_EDITING_WORKER_HOST}/edit`);
span.setAttr('document.id', args.documentId);
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/client.test.ts b/apps/web/src/lib/service-clients/service-agent-harness/client.test.ts
index c34db9d1ef..e7e983cc50 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/client.test.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/client.test.ts
@@ -2,7 +2,8 @@ import { fetchWithToken } from '@core/util/fetchWithToken';
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { agentHarnessServiceClient } from './client';
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'agent-harness': 'https://harness.example.com' },
SYNC_SERVICE_HOSTS: { worker: 'https://sync.example.com' },
}));
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/reviews.ts b/apps/web/src/lib/service-clients/service-agent-harness/reviews.ts
index 1396aadc61..9b62a0ec4e 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/reviews.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/reviews.ts
@@ -14,7 +14,7 @@ export const agentReviewClient = {
);
},
async decide(session: string, review: string, decision: ReviewDecision) {
- const span = Telemetry.clientSpan('agent.review.decide');
+ const span = Telemetry.span('agent.review.decide', { kind: 'client' });
span.setAttr('agent.session.id', session);
span.setAttr('agent.review.id', review);
span.setAttr('agent.review.action', decision.action);
@@ -25,7 +25,12 @@ export const agentReviewClient = {
try {
const result = await fetchWithToken<ReviewRecord>(
`${host}/agent-sessions/${session}/reviews/${review}`,
- { method: 'POST', headers, body: JSON.stringify(decision) }
+ {
+ method: 'POST',
+ headers,
+ body: JSON.stringify(decision),
+ trace: { parentSpan: span },
+ }
);
if (result.isErr()) span.error('Review decision failed');
return result;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/universal-input.test.ts b/apps/web/src/lib/service-clients/service-agent-harness/universal-input.test.ts
index d4284e7d90..2483eb0a57 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/universal-input.test.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/universal-input.test.ts
@@ -4,7 +4,8 @@ import { err, ok } from 'neverthrow';
import { beforeEach, expect, it, vi } from 'vitest';
import { universalInputClient } from './universal-input';
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'agent-harness': 'https://harness.example.com' },
SYNC_SERVICE_HOSTS: { worker: 'https://sync.example.com' },
}));
diff --git a/apps/web/src/lib/service-clients/service-auth/fetch.ts b/apps/web/src/lib/service-clients/service-auth/fetch.ts
index e24021e45a..c6a3588a34 100644
--- a/apps/web/src/lib/service-clients/service-auth/fetch.ts
+++ b/apps/web/src/lib/service-clients/service-auth/fetch.ts
@@ -7,6 +7,7 @@ import {
safeFetch,
type TextResponse,
} from '@core/util/safeFetch';
+import { Telemetry } from '@macro-inc/observability';
import { err, ok, type Result } from 'neverthrow';
import { authServiceClient, getExpiresAt } from './client';
@@ -36,7 +37,8 @@ function requestMacroApiToken() {
return promise;
}
-export async function getMacroApiToken() {
+export async function getMacroApiToken(): Promise<string> {
+ const parent = Telemetry.captureContext();
if (LOCAL_ONLY) {
const apiToken = import.meta.env.__LOCAL_JWT__;
if (apiToken) {
@@ -46,7 +48,7 @@ export async function getMacroApiToken() {
const cachedPromise = macroApiTokenPromise;
if (!cachedPromise) {
- return requestMacroApiToken();
+ return parent.run(requestMacroApiToken);
}
const apiToken = await cachedPromise;
@@ -58,10 +60,10 @@ export async function getMacroApiToken() {
// caller was suspended awaiting it. Reuse that replacement instead of
// issuing a duplicate request.
if (macroApiTokenPromise !== cachedPromise) {
- return getMacroApiToken();
+ return parent.run(getMacroApiToken);
}
- return requestMacroApiToken();
+ return parent.run(requestMacroApiToken);
}
type TextContentType = `text/${string}`;
@@ -92,7 +94,8 @@ export async function fetchWithAuth<
input: RequestInfo,
init?: fetchWithAuthOptions<T, CustomErrorCode>
): Promise<Result<T, ResultError<BaseFetchErrorCode | CustomErrorCode>[]>> {
- const apiToken = await getMacroApiToken();
+ const parentSpan = init?.trace?.parentSpan ?? Telemetry.captureContext();
+ const apiToken = await parentSpan.run(getMacroApiToken);
if (!apiToken) {
return err([
{ code: 'UNAUTHORIZED', message: 'No access and/or refresh token found' },
@@ -101,6 +104,7 @@ export async function fetchWithAuth<
const safeFetchInit = {
...init,
+ trace: { ...init?.trace, parentSpan },
headers: {
...init?.headers,
Authorization: `Bearer ${apiToken}`,
diff --git a/apps/web/src/lib/service-clients/service-call/client.test.ts b/apps/web/src/lib/service-clients/service-call/client.test.ts
index 6546a40c3a..eb6fe99622 100644
--- a/apps/web/src/lib/service-clients/service-call/client.test.ts
+++ b/apps/web/src/lib/service-clients/service-call/client.test.ts
@@ -5,7 +5,8 @@ const requests = vi.hoisted(() => ({
authenticated: vi.fn(),
public: vi.fn(),
}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'document-storage-service': 'https://gateway.example/dss' },
}));
vi.mock('@core/util/fetchWithToken', () => ({
diff --git a/apps/web/src/lib/service-clients/service-connection/websocket-url.ts b/apps/web/src/lib/service-clients/service-connection/websocket-url.ts
index 6c12247938..b5fccb7231 100644
--- a/apps/web/src/lib/service-clients/service-connection/websocket-url.ts
+++ b/apps/web/src/lib/service-clients/service-connection/websocket-url.ts
@@ -1,6 +1,6 @@
import { ENABLE_BEARER_TOKEN_AUTH } from '@core/constant/featureFlags';
import { SERVER_HOSTS } from '@core/constant/servers';
-import { fetchToken } from '@core/util/fetchWithToken';
+import { ensureFreshSession } from '@core/util/fetchWithToken';
import { getMacroApiToken } from '@service-auth/fetch';
/** Resolve gateway credentials without initializing a connection. */
@@ -12,6 +12,6 @@ export async function resolveWsUrl() {
return `${wsHost}?macro-api-token=${apiToken}`;
}
- await fetchToken();
+ await ensureFreshSession();
return wsHost;
}
diff --git a/apps/web/src/lib/service-clients/service-email/client.test.ts b/apps/web/src/lib/service-clients/service-email/client.test.ts
index d2af33512b..fe5332151c 100644
--- a/apps/web/src/lib/service-clients/service-email/client.test.ts
+++ b/apps/web/src/lib/service-clients/service-email/client.test.ts
@@ -2,7 +2,8 @@ import { ok } from 'neverthrow';
import { expect, it, vi } from 'vitest';
const fetchWithToken = vi.hoisted(() => vi.fn());
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: {
'email-service': 'https://gateway.example/email',
'calendar-service': 'https://gateway.example/calendar',
diff --git a/apps/web/src/lib/service-clients/service-notification/client.test.ts b/apps/web/src/lib/service-clients/service-notification/client.test.ts
index 8e2c803581..d79f83969c 100644
--- a/apps/web/src/lib/service-clients/service-notification/client.test.ts
+++ b/apps/web/src/lib/service-clients/service-notification/client.test.ts
@@ -3,7 +3,8 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
import { notificationServiceClient } from './client';
const { fetchMock } = vi.hoisted(() => ({ fetchMock: vi.fn() }));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'notification-service': 'http://localhost/notifications' },
}));
vi.mock('@core/util/fetchWithToken', () => ({ fetchWithToken: fetchMock }));
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-notification-receipt.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-notification-receipt.test.ts
index 08c83936d4..99a02c012f 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-notification-receipt.test.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-notification-receipt.test.ts
@@ -250,46 +250,61 @@ it('does not let a notification callback failure stop persistence or the next ev
}
});
-it('marks failed persistence in the receipt trace without failing or replaying delivery', async () => {
- const receipt = new RecordedSpan('receipt');
- vi.spyOn(Telemetry, 'span').mockReturnValueOnce(receipt);
- const failure = new Error('private cache failure details');
- const onCacheError = vi.fn();
- const delivered = Promise.withResolvers<void>();
- const onPatch = vi.fn();
- const stream = subscribe(
- [
- normalizedCacheExchange(
- {
- ...createNoopCacheHost(),
- async writeQuery() {
- throw failure;
+it.each([
+ { message: 'private cache failure details', code: 'unknown' },
+ {
+ message: 'graphql cache ipc timeout: graphql_cache_write',
+ code: 'timeout',
+ },
+])(
+ 'marks $code persistence failures without failing or replaying delivery',
+ async ({ message, code }) => {
+ const receipt = new RecordedSpan('receipt');
+ vi.spyOn(Telemetry, 'span').mockReturnValueOnce(receipt);
+ const failure = new Error(message);
+ const onCacheError = vi.fn();
+ const delivered = Promise.withResolvers<void>();
+ const onPatch = vi.fn();
+ const stream = subscribe(
+ [
+ normalizedCacheExchange(
+ {
+ ...createNoopCacheHost(),
+ async writeQuery() {
+ throw failure;
+ },
},
- },
- { onCacheError }
- ),
- notificationReceiptExchange(onPatch),
- ],
- () => delivered.resolve()
- );
- try {
- await stream.attached;
- stream.emit(NEW_NOTIFICATION);
- await delivered.promise;
- expect(onPatch).toHaveBeenCalledOnce();
- expect(onCacheError).toHaveBeenCalledWith(failure, expect.any(Object));
- expect(receipt.ends).toBe(1);
- expect(receipt.errors).toEqual([]);
- expect(receipt.children.map((span) => span.ends)).toEqual([1, 1]);
- expect(receipt.children[1].errors).toEqual([
- 'Subscription cache effect failed',
- ]);
- expect(receipt.children[1].attributes['cache.effects_applied']).toBe(false);
- expect(JSON.stringify(receipt)).not.toContain(failure.message);
- } finally {
- stream.dispose();
+ { onCacheError }
+ ),
+ notificationReceiptExchange(onPatch),
+ ],
+ () => delivered.resolve()
+ );
+ try {
+ await stream.attached;
+ stream.emit(NEW_NOTIFICATION);
+ await delivered.promise;
+ expect(onPatch).toHaveBeenCalledOnce();
+ expect(onCacheError).toHaveBeenCalledWith(failure, expect.any(Object));
+ expect(receipt.ends).toBe(1);
+ expect(receipt.errors).toEqual([]);
+ expect(receipt.children.map((span) => span.ends)).toEqual([1, 1]);
+ expect(receipt.children[1].errors).toEqual([
+ 'Subscription cache effect failed',
+ ]);
+ expect(receipt.children[1].attributes['cache.effects_applied']).toBe(
+ false
+ );
+ expect(receipt.children[1].attributes['cache.failure']).toBe(code);
+ expect(receipt.children[1].children[0].attributes['cache.failure']).toBe(
+ code
+ );
+ expect(JSON.stringify(receipt)).not.toContain(failure.message);
+ } finally {
+ stream.dispose();
+ }
}
-});
+);
it('delivers without a cache and stops receipt when the subscription is disposed', async () => {
const onPatch = vi.fn();
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts
index 15c6ef824a..422ea21939 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup-websocket.test.ts
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
const telemetryError = vi.hoisted(() => vi.fn());
vi.mock('@macro-inc/observability', () => ({
+ NOOP_SPAN: {},
Telemetry: { error: telemetryError },
}));
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
index 05a683d013..30bb40575a 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.test.ts
@@ -413,7 +413,8 @@ vi.mock('@core/constant/featureFlags', () => ({
enableGraphqlSoup: { key: 'enable-graphql-soup' },
isFeatureEnabled: () => mocks.graphqlEnabled,
}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'document-storage-service': 'http://dss.test' },
}));
vi.mock('@core/util/cookies', () => ({
@@ -464,8 +465,10 @@ vi.mock('@macro-inc/observability', () => ({
Telemetry: {
error: mocks.telemetryError,
warn: mocks.telemetryWarn,
+ captureContext: () => ({ run: <T>(work: () => T) => work() }),
span: (_name: string, work: (span: unknown) => Promise<unknown>) =>
work({
+ run: <T>(work: () => T) => work(),
event: vi.fn(),
setAttr: vi.fn(),
injectTraceHeaders: (headers: Record<string, string>) => {
diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
index f61214551a..6d9bb2d868 100644
--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts
@@ -1,3 +1,7 @@
+import {
+ captureTraceParentExchange,
+ traceParentExchange,
+} from '@app/lib/urql-solid/trace-parent-exchange';
import { toast } from '@core/component/Toast/Toast';
import {
ENABLE_BEARER_TOKEN_AUTH,
@@ -138,6 +142,7 @@ async function authorizedDssGraphqlFetch(
input: RequestInfo | URL,
init?: RequestInit
): Promise<Response> {
+ const parent = Telemetry.captureContext();
if (ENABLE_BEARER_TOKEN_AUTH) {
const apiToken = await getMacroApiToken();
return await platformFetch(input, {
@@ -154,7 +159,7 @@ async function authorizedDssGraphqlFetch(
let response = await fetchWithCredentials();
if (response.status !== 401) return response;
- const tokenResult = await fetchToken();
+ const tokenResult = await parent.run(fetchToken);
if (tokenResult.isErr()) return response;
response = await fetchWithCredentials();
@@ -346,7 +351,9 @@ export async function dssGraphqlFetch(
}),
};
span.event('request_dispatch');
- const response = await authorizedDssGraphqlFetch(input, transportInit);
+ const response = await span.run(() =>
+ authorizedDssGraphqlFetch(input, transportInit)
+ );
span.setAttr('graphql.response_headers_ms', performance.now() - started);
span.setAttr('http.response.status_code', response.status);
span.event('response_headers');
@@ -375,7 +382,7 @@ export async function dssGraphqlFetch(
// metadata field and suppress v2 local authority for this session. Backfill
// still refuses to checkpoint missing required Document supplements.
soupProjectionServerSupported = false;
- return await authorizedDssGraphqlFetch(input, legacyInit);
+ return await span.run(() => authorizedDssGraphqlFetch(input, legacyInit));
} catch (error) {
// Transport errors may contain query URLs; record a category only.
span.setAttr('graphql.transport_failed', true);
@@ -386,7 +393,12 @@ export async function dssGraphqlFetch(
const graphqlSoupClient = createClient({
url: `${dssHost}/items/soup/graphql`,
- exchanges: [networkRevalidationExchange(), fetchExchange],
+ exchanges: [
+ captureTraceParentExchange,
+ networkRevalidationExchange(),
+ traceParentExchange,
+ fetchExchange,
+ ],
fetch: dssGraphqlFetch,
// urql's default ("within-url-limit") sends small documents as GET, but
// GET on the DSS GraphQL path serves the GraphiQL IDE — only POST
@@ -503,9 +515,11 @@ function getUncachedRealtimeClient(): Client {
url: `${dssHost}/items/soup/graphql`,
preferGetMethod: false,
exchanges: [
+ captureTraceParentExchange,
networkRevalidationExchange(),
notificationReceiptExchange(publishNotificationPatch),
graphqlSoupSubscriptionExchange(websocketClient),
+ traceParentExchange,
fetchExchange,
],
fetch: dssGraphqlFetch,
@@ -816,6 +830,7 @@ export function getGraphqlSoupClient(): Client {
// See graphqlSoupClient: GET serves GraphiQL on this path.
preferGetMethod: false,
exchanges: [
+ captureTraceParentExchange,
optimisticResolversExchange(soupOptimisticResolvers),
networkRevalidationExchange(() => host?.disabled === true),
normalizedCacheExchange(host, {
@@ -848,6 +863,7 @@ export function getGraphqlSoupClient(): Client {
}),
notificationReceiptExchange(publishNotificationPatch),
graphqlSoupSubscriptionExchange(graphqlWsClient),
+ traceParentExchange,
fetchExchange,
],
fetch: (input, init) => dssGraphqlFetch(input, init, host),
diff --git a/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts b/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
index c57e2ba293..31292a77e9 100644
--- a/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
+++ b/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
@@ -4,6 +4,7 @@ import {
WebsocketConnectionState,
} from '@macro-inc/collaboration/websocket';
import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket/solid/state-signal';
+import { NOOP_SPAN } from '@macro-inc/observability';
import { createRoot } from 'solid-js';
import { beforeEach, describe, expect, it, vi } from 'vitest';
@@ -13,10 +14,8 @@ const mocks = vi.hoisted(() => ({
vi.mock('@macro-inc/collaboration/sync-service/socket', () => ({
createSyncSocket: mocks.socket,
}));
-vi.mock('@block-md/observability', () => ({
- resumeDocumentSpan: () => undefined,
-}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SYNC_SERVICE_HOSTS: { ws: 'wss://sync.test' },
}));
vi.mock('@core/constant/featureFlags', () => ({
@@ -104,3 +103,28 @@ describe('deferred document authorization', () => {
expect(getToken).toHaveBeenCalledOnce();
});
});
+
+it('uses the supplied load context for initial and renewed document sockets', async () => {
+ const parent = {
+ ...NOOP_SPAN,
+ traceparent: () =>
+ '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01',
+ };
+ createSyncServiceSocket(
+ 'document',
+ undefined,
+ {
+ isCurrent: () => true,
+ canWrite: () => true,
+ getToken: async () => 'fresh',
+ onInvalidated: () => () => {},
+ },
+ parent
+ );
+ expect(await resolveUrl()).toContain(
+ '&traceparent=00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01'
+ );
+ expect(await resolveUrl()).toContain(
+ '&traceparent=00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01'
+ );
+});
diff --git a/apps/web/src/lib/service-clients/service-sync/source/helpers.ts b/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
index e5d77b4916..1906bbb9ca 100644
--- a/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
+++ b/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
@@ -1,4 +1,3 @@
-import { resumeDocumentSpan } from '@block-md/observability';
import { isFeatureEnabled, syncViaGateway } from '@core/constant/featureFlags';
import { SYNC_SERVICE_HOSTS } from '@core/constant/servers';
import type {
@@ -19,6 +18,7 @@ import {
} from '@macro-inc/collaboration/sync-service/source';
import type { UrlResolver } from '@macro-inc/collaboration/websocket';
import { createWebsocketStateSignal } from '@macro-inc/collaboration/websocket/solid/state-signal';
+import type { Span } from '@macro-inc/observability';
import { storageServiceClient } from '@service-storage/client';
import type { ResultAsync } from 'neverthrow';
import { resolveSyncRouterWsUrl } from '../websocket-url';
@@ -86,7 +86,8 @@ export function createTokenRefreshingSocket(
export function createSyncServiceSocket(
documentId: string,
initialToken: string | undefined,
- authorization?: DocumentSyncAuthorization
+ authorization?: DocumentSyncAuthorization,
+ parentSpan?: Span
): SyncWebsocket {
return createTokenRefreshingSocket(
documentId,
@@ -103,7 +104,7 @@ export function createSyncServiceSocket(
}
return response.value.token;
}),
- () => resumeDocumentSpan(documentId)?.traceparent()
+ () => parentSpan?.traceparent()
);
}
@@ -125,7 +126,8 @@ async function refreshPermissionToken(documentId: string): Promise<string> {
export const createSyncServiceSource = (
documentId: string,
token: string | undefined,
- authorization?: DocumentSyncAuthorization
+ authorization?: DocumentSyncAuthorization,
+ parentSpan?: Span
): {
source: LiveSyncSource;
doInitialSync: () => ResultAsync<InitialSync, SyncError>;
@@ -138,7 +140,7 @@ export const createSyncServiceSource = (
authorization ? undefined : token,
authorization?.getToken ?? (() => refreshPermissionToken(documentId))
)
- : createSyncServiceSocket(documentId, token, authorization);
+ : createSyncServiceSocket(documentId, token, authorization, parentSpan);
const state = createWebsocketStateSignal(ws);
const source = new SyncServiceSource(ws, documentId, {
status: () => mapToSyncStatus(state()),
diff --git a/apps/web/src/lib/service-clients/service-sync/websocket-url.test.ts b/apps/web/src/lib/service-clients/service-sync/websocket-url.test.ts
index 9631897291..2f473599bb 100644
--- a/apps/web/src/lib/service-clients/service-sync/websocket-url.test.ts
+++ b/apps/web/src/lib/service-clients/service-sync/websocket-url.test.ts
@@ -11,10 +11,13 @@ vi.mock('@core/constant/featureFlags', () => ({
return auth.bearer;
},
}));
-vi.mock('@core/constant/servers', () => ({
+vi.mock('@core/constant/servers', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@core/constant/servers')>()),
SERVER_HOSTS: { 'document-storage-service': 'https://gateway.test/dss' },
}));
-vi.mock('@core/util/fetchWithToken', () => ({ fetchToken: auth.cookie }));
+vi.mock('@core/util/fetchWithToken', () => ({
+ ensureFreshSession: auth.cookie,
+}));
vi.mock('@service-auth/fetch', () => ({ getMacroApiToken: auth.token }));
import { resolveSyncRouterWsUrl } from './websocket-url';
@@ -26,7 +29,7 @@ beforeEach(() => {
});
describe('dedicated DSS sync socket credentials', () => {
- it('preserves the DSS gateway prefix and refreshes cookies on each connection', async () => {
+ it('preserves the DSS gateway prefix and ensures fresh cookies on each connection', async () => {
expect(await resolveSyncRouterWsUrl()).toBe(
'wss://gateway.test/dss/sync/ws'
);
diff --git a/apps/web/src/lib/service-clients/service-sync/websocket-url.ts b/apps/web/src/lib/service-clients/service-sync/websocket-url.ts
index 41b95e8199..6db6853f13 100644
--- a/apps/web/src/lib/service-clients/service-sync/websocket-url.ts
+++ b/apps/web/src/lib/service-clients/service-sync/websocket-url.ts
@@ -1,6 +1,6 @@
import { ENABLE_BEARER_TOKEN_AUTH } from '@core/constant/featureFlags';
import { SERVER_HOSTS } from '@core/constant/servers';
-import { fetchToken } from '@core/util/fetchWithToken';
+import { ensureFreshSession } from '@core/util/fetchWithToken';
import { Telemetry } from '@macro-inc/observability';
import { getMacroApiToken } from '@service-auth/fetch';
@@ -16,7 +16,7 @@ export async function resolveSyncRouterWsUrl(): Promise<string> {
if (!token) throw new Error('No Macro API token');
url.searchParams.set('macro-api-token', token);
} else {
- const refreshed = await fetchToken();
+ const refreshed = await ensureFreshSession();
if (refreshed.isErr()) throw new Error('Unable to refresh sync session');
}
const traceparent = span.traceparent();
diff --git a/apps/web/src/lib/split-router/README.md b/apps/web/src/lib/split-router/README.md
index 0139e8288f..ec31c575f3 100644
--- a/apps/web/src/lib/split-router/README.md
+++ b/apps/web/src/lib/split-router/README.md
@@ -1,4 +1,6 @@
-# SplitRouter leave guards
+# SplitRouter
+
+## Leave guards
`useBeforeLeave` runs when a navigation leaves the registering route, closes its
pane, or changes an explicitly watched search namespace. Returning `false` keeps
@@ -21,3 +23,15 @@ or preventing later callbacks from running.
Preload and middleware errors that the router recovers from still allow commit
callbacks when navigation commits. Host-leave permission checks cannot confirm
that the host actually navigates, so their `onCommit` registration is a no-op.
+
+## Outlets
+
+An outlet outside a pane renders the first available pane. While no pane exists,
+it renders its supplied fallback without calling pane-scoped hooks. It starts
+rendering the pane when one becomes available. An outlet already inside a pane
+continues that pane's route branch, even when no explicit `pane` prop is given.
+
+Route preloads resolve the destination leaf's `toReference` once and pass it to
+ancestor data preload hooks. Canonical reference params preserve targets in both
+scoped router search and external links. Hover preloads use the router lifetime
+signal; disposing an account's router cancels deferred query admission.
diff --git a/apps/web/src/lib/split-router/router/create-router.ts b/apps/web/src/lib/split-router/router/create-router.ts
index fa24f7b373..10976df80d 100644
--- a/apps/web/src/lib/split-router/router/create-router.ts
+++ b/apps/web/src/lib/split-router/router/create-router.ts
@@ -7,7 +7,6 @@ import type {
PreloadIntent,
SplitLocation,
} from '../routes/types';
-import { UNCANCELLABLE } from '../utils';
import { createClaims } from './claims';
import { createLayout } from './layout';
import { createLeaveGuards } from './leave-guards';
@@ -40,7 +39,9 @@ export function createSplitRouter(options: SplitRouterOptions) {
const url = createUrl({ routes, history, panes });
+ const preloadLifetime = new AbortController();
const phaseOptions = {
+ preloadSignal: preloadLifetime.signal,
routes,
middleware: options.middleware ?? [],
guards,
@@ -111,7 +112,8 @@ export function createSplitRouter(options: SplitRouterOptions) {
location: SplitLocation,
intent: PreloadIntent = 'hover'
): Promise<unknown> | undefined => {
- const context = { location, intent, signal: UNCANCELLABLE };
+ if (disposed) return;
+ const context = { location, intent, signal: preloadLifetime.signal };
return untrack(() => preloadLocation(routes, context));
};
@@ -120,6 +122,7 @@ export function createSplitRouter(options: SplitRouterOptions) {
if (disposed) return;
disposed = true;
+ preloadLifetime.abort();
disconnect();
runner.dispose();
claims.dispose();
diff --git a/apps/web/src/lib/split-router/router/phases.ts b/apps/web/src/lib/split-router/router/phases.ts
index 415b84476d..ce18939287 100644
--- a/apps/web/src/lib/split-router/router/phases.ts
+++ b/apps/web/src/lib/split-router/router/phases.ts
@@ -115,6 +115,8 @@ export function createPhaseScopes(
/** What a pane shows now, which its guards are asked to leave. */
current(pane: PaneId): Entry | undefined;
preloadBudgetMs: number;
+ /** Speculative cache admission belongs to the router, not its navigation phase. */
+ preloadSignal: AbortSignal;
},
waiting: (state: Running) => void,
registerCommit: RegisterCommitCallback
@@ -200,12 +202,16 @@ export function createPhaseScopes(
};
const preloadEntries = (
- { navigation, signal }: RunContext,
+ { navigation }: RunContext,
entries: readonly Entry[]
): MaybePromise<void> => {
const intent = intentOf(navigation);
const work = entries.flatMap((entry) => {
- const context = { location: entry.location, intent, signal };
+ const context = {
+ location: entry.location,
+ intent,
+ signal: options.preloadSignal,
+ };
return preloadLocation(routes, context) ?? [];
});
diff --git a/apps/web/src/lib/split-router/router/preload.ts b/apps/web/src/lib/split-router/router/preload.ts
index 5cad527a26..7acda804f9 100644
--- a/apps/web/src/lib/split-router/router/preload.ts
+++ b/apps/web/src/lib/split-router/router/preload.ts
@@ -5,13 +5,19 @@ import {
type SplitRoutesManifest,
} from '../routes/manifest';
import { routeParams } from '../routes/queries';
-import type { PreloadIntent, SplitLocation } from '../routes/types';
+import { replacePaneSearchParams } from '../routes/search';
+import type {
+ PreloadIntent,
+ SplitLocation,
+ SplitReference,
+} from '../routes/types';
import { isPromise } from '../utils';
type PreloadContext = {
location: SplitLocation;
intent: PreloadIntent;
signal: AbortSignal;
+ reference?: SplitReference;
};
async function settleQuietly(work: Promise<unknown>): Promise<void> {
@@ -26,15 +32,14 @@ function hasPreload(component: unknown): component is { preload: unknown } {
return typeof component === 'function' && 'preload' in component;
}
-function warmComponent(component: unknown): void {
+export async function preloadComponent(component: unknown): Promise<void> {
if (!hasPreload(component)) return;
const preload = component.preload;
if (typeof preload !== 'function') return;
const chunk: unknown = preload.call(component);
- if (chunk instanceof Promise)
- fireAndForget(settleQuietly(chunk), 'split-router');
+ if (chunk instanceof Promise) await chunk;
}
function preloadNode(
@@ -44,9 +49,14 @@ function preloadNode(
): Promise<unknown> | undefined {
const { definition } = node;
const { location, intent, signal } = context;
- warmComponent(definition.component);
+ fireAndForget(
+ settleQuietly(preloadComponent(definition.component)),
+ 'split-router'
+ );
const data = definition.preload?.({
+ location,
+ reference: context.reference,
params: routeParams(location.route, depth + 1),
search: location.search,
intent,
@@ -56,6 +66,26 @@ function preloadNode(
return isPromise(data) ? data : undefined;
}
+/** Canonical route-owned entity reference, including scoped target search. */
+export function referenceForLocation(
+ routes: SplitRoutesManifest,
+ location: SplitLocation
+): SplitReference | undefined {
+ const leaf = resolveBranch(routes, location.route).at(-1);
+ const query = new URLSearchParams();
+ replacePaneSearchParams(query, [location.search]);
+ let reference: SplitReference | undefined;
+ try {
+ reference = leaf?.definition.toReference?.(
+ routeParams(location.route),
+ query
+ );
+ } catch {
+ // A malformed speculative destination must never fail navigation.
+ }
+ return reference;
+}
+
/**
* Starts loading every `lazy()` chunk along the branch without waiting for
* them, and returns only the route data preloads that need waiting for.
@@ -68,9 +98,11 @@ export function preloadLocation(
const work: Promise<unknown>[] = [];
const branch = resolveBranch(routes, context.location.route);
+ const reference = referenceForLocation(routes, context.location);
+
branch.forEach((node, depth) => {
try {
- const data = preloadNode(node, depth, context);
+ const data = preloadNode(node, depth, { ...context, reference });
if (data) work.push(data);
} catch (error) {
console.error(
diff --git a/apps/web/src/lib/split-router/router/runner.ts b/apps/web/src/lib/split-router/router/runner.ts
index a0fb461381..06e4cb36bb 100644
--- a/apps/web/src/lib/split-router/router/runner.ts
+++ b/apps/web/src/lib/split-router/router/runner.ts
@@ -1,3 +1,4 @@
+import { beginInteraction } from '@app/observability/flow';
import { fireAndForget } from '@core/util/fireAndForget';
import {
createMachine,
@@ -220,6 +221,14 @@ export function createRunner(options: {
entries: readonly Entry[]
): NavigationResult => {
committing += 1;
+ // Views the commit mounts join this trace until they have loaded.
+ const interaction = beginInteraction('navigation', {
+ kind: 'navigation',
+ attributes: {
+ 'navigation.cause': navigation.cause,
+ 'navigation.pane_count': navigation.targets.length,
+ },
+ });
try {
const result = navigation.apply(entries);
@@ -239,6 +248,7 @@ export function createRunner(options: {
console.error('Split router could not commit a navigation', error);
return CANCELLED_RESULT;
} finally {
+ interaction.end();
committing -= 1;
release();
}
diff --git a/apps/web/src/lib/split-router/routes/queries.ts b/apps/web/src/lib/split-router/routes/queries.ts
index 6babb9e795..2ed1144f7d 100644
--- a/apps/web/src/lib/split-router/routes/queries.ts
+++ b/apps/web/src/lib/split-router/routes/queries.ts
@@ -213,6 +213,8 @@ export type OutletMatch = {
/** The route's own loading view, shown while `component` suspends. */
loading?: unknown;
key: string;
+ /** The route definition's id, a static name safe for telemetry. */
+ route: string;
/** Depth the next nested outlet starts from. */
depth: number;
};
@@ -229,9 +231,15 @@ export function outletAt(
const branch = resolveBranch(routes, entry.location.route);
for (let depth = start; depth < branch.length; depth += 1) {
- const { component, loading } = branch[depth]!.definition;
+ const { component, loading, id } = branch[depth]!.definition;
if (typeof component !== 'function') continue;
- return { component, loading, key: keys[depth]!, depth: depth + 1 };
+ return {
+ component,
+ loading,
+ key: keys[depth]!,
+ route: id,
+ depth: depth + 1,
+ };
}
}
diff --git a/apps/web/src/lib/split-router/routes/types.ts b/apps/web/src/lib/split-router/routes/types.ts
index f24cd7765c..c09c64c1e8 100644
--- a/apps/web/src/lib/split-router/routes/types.ts
+++ b/apps/web/src/lib/split-router/routes/types.ts
@@ -98,9 +98,14 @@ export type SplitRouteRemountContext = {
};
export type SplitRoutePreloadContext<TParams = SplitRouteParams> = {
+ /** Entity declared by the destination leaf, when it has one. */
+ reference?: SplitReference;
+ /** Full destination for an ancestor that owns shared resource preloading. */
+ location: SplitLocation;
params: TParams;
search: SplitSearchState | undefined;
intent: PreloadIntent;
+ /** Cache admission survives navigation commit; aborts on router disposal. */
signal: AbortSignal;
};
diff --git a/apps/web/src/lib/split-router/solid/outlet.tsx b/apps/web/src/lib/split-router/solid/outlet.tsx
index b36b682981..518f267269 100644
--- a/apps/web/src/lib/split-router/solid/outlet.tsx
+++ b/apps/web/src/lib/split-router/solid/outlet.tsx
@@ -1,17 +1,20 @@
+import { TraceFlow } from '@app/observability/flow';
import { perfMark } from '@app/observability/perf-marks';
+import { trackRouteView } from '@app/observability/runtime-resources';
import {
type Component,
createEffect,
createMemo,
type JSX,
on,
+ onCleanup,
onMount,
Show,
Suspense,
useContext,
} from 'solid-js';
import { Dynamic } from 'solid-js/web';
-import { type OutletMatch, outletAt } from '../routes/queries';
+import { type OutletMatch, outletAt, routeParams } from '../routes/queries';
import type { PaneId } from '../routes/types';
import {
PaneContext,
@@ -23,10 +26,14 @@ import { PaneScope } from './pane-scope';
type OutletFallback = JSX.Element | (() => JSX.Element);
+function renderFallback(fallback: OutletFallback | undefined): JSX.Element {
+ return typeof fallback === 'function' ? fallback() : fallback;
+}
+
export type OutletProps = {
/** Shorthand for wrapping this outlet in `<SplitRouter.Scope pane={…}>`. */
pane?: PaneId;
- /** Shown when nothing below this point in the branch has a component. */
+ /** Shown when no root pane exists or the branch has no further component. */
fallback?: OutletFallback;
};
@@ -34,12 +41,7 @@ function RouteOutlet(props: { fallback?: OutletFallback }) {
const router = useSplitRouter();
const parent = usePaneContext();
- const fallback = () => {
- const { fallback } = props;
- if (typeof fallback === 'function') return fallback();
-
- return fallback;
- };
+ const fallback = () => renderFallback(props.fallback);
const match = createMemo<OutletMatch | undefined>(
() => outletAt(router.routes, parent.entry(), parent.depth()),
@@ -68,14 +70,15 @@ function RouteOutlet(props: { fallback?: OutletFallback }) {
{(resolved) => (
<PaneContext.Provider value={context}>
{/* Only routes with their own loading view get a boundary, so the
- rest suspend to their enclosing boundary as before. */}
+ rest suspend to their enclosing boundary as before. The flow
+ sits inside it: Solid defers its mount until the view resolves. */}
<Show
when={resolved.loading as Component | undefined}
- fallback={<Dynamic component={resolved.component as Component} />}
+ fallback={<RouteView match={resolved} />}
>
{(loading) => (
<Suspense fallback={<Dynamic component={loading()} />}>
- <Dynamic component={resolved.component as Component} />
+ <RouteView match={resolved} />
</Suspense>
)}
</Show>
@@ -86,6 +89,33 @@ function RouteOutlet(props: { fallback?: OutletFallback }) {
);
}
+/**
+ * A route's view, timed from creation until it and its loads have painted.
+ * Params at or above this depth update the view in place; the flow starts
+ * again for each, so loads after an in-place navigation are timed too.
+ */
+function RouteView(props: { match: OutletMatch }) {
+ onCleanup(trackRouteView());
+ const pane = usePaneContext();
+ const params = () =>
+ JSON.stringify(
+ routeParams(pane.entry()?.location.route, props.match.depth)
+ );
+
+ return (
+ <TraceFlow
+ name={`view.${props.match.route}`}
+ attributes={{
+ 'route.id': props.match.route,
+ 'route.depth': props.match.depth,
+ }}
+ key={params}
+ >
+ <Dynamic component={props.match.component as Component} />
+ </TraceFlow>
+ );
+}
+
/** Marks when a matched route's component tree has been created and attached. */
function RouteMounted(props: { route: string }) {
onMount(() => perfMark('route.mounted', { route: props.route }));
@@ -110,7 +140,16 @@ export function Outlet(props: OutletProps) {
};
return (
- <Show when={pane()} fallback={<RouteOutlet fallback={props.fallback} />}>
+ <Show
+ when={pane()}
+ fallback={
+ enclosing ? (
+ <RouteOutlet fallback={props.fallback} />
+ ) : (
+ renderFallback(props.fallback)
+ )
+ }
+ >
{(pane) => (
<PaneScope pane={pane()}>
<RouteOutlet fallback={props.fallback} />
diff --git a/apps/web/src/lib/split-router/tests/preload.test.ts b/apps/web/src/lib/split-router/tests/preload.test.ts
new file mode 100644
index 0000000000..e21d665991
--- /dev/null
+++ b/apps/web/src/lib/split-router/tests/preload.test.ts
@@ -0,0 +1,54 @@
+import { expect, it, vi } from 'vitest';
+import { preloadLocation } from '../router/preload';
+import { createRoutesManifest } from '../routes/manifest';
+import type { SplitLocation } from '../routes/types';
+
+it('provides the leaf entity to shared ancestors while code and data start independently', async () => {
+ const data = vi.fn();
+ const code = vi.fn(() => new Promise<void>(() => {}));
+ const routes = createRoutesManifest({
+ definitions: [
+ {
+ id: 'app',
+ path: '',
+ preload: data,
+ children: [
+ {
+ id: 'mail',
+ path: 'mail',
+ children: [
+ {
+ id: 'thread',
+ path: ':id',
+ component: Object.assign(() => null, { preload: code }),
+ toReference: ({ id }) => ({ type: 'email', id: String(id) }),
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ defaultRoute: () => ({ matches: [{ id: 'app', params: {} }] }),
+ });
+ const location: SplitLocation = {
+ route: {
+ matches: [
+ { id: 'app', params: {} },
+ { id: 'mail', params: {} },
+ { id: 'thread', params: { id: 'thread-id' } },
+ ],
+ },
+ };
+ await preloadLocation(routes, {
+ location,
+ intent: 'hover',
+ signal: new AbortController().signal,
+ });
+ expect(code).toHaveBeenCalledOnce();
+ expect(data).toHaveBeenCalledWith(
+ expect.objectContaining({
+ reference: { type: 'email', id: 'thread-id' },
+ location,
+ })
+ );
+});
diff --git a/apps/web/src/lib/split-router/tests/router.test.ts b/apps/web/src/lib/split-router/tests/router.test.ts
index e259675c43..e176261ab3 100644
--- a/apps/web/src/lib/split-router/tests/router.test.ts
+++ b/apps/web/src/lib/split-router/tests/router.test.ts
@@ -1507,3 +1507,62 @@ describe('split router while other work is in flight', () => {
expect(router.arrival(pane(0))).toBe('forward');
});
});
+
+it('cancels speculative route admission when its account router is disposed', async () => {
+ let signal: AbortSignal | undefined;
+ const view = setup('/home', {
+ routes: {
+ ...appRoutes,
+ definitions: [
+ {
+ ...appRoute,
+ preload: (context) => {
+ if (context.intent === 'hover') signal = context.signal;
+ },
+ },
+ ],
+ },
+ });
+ const preloaded = view.router.preload(homeLocation, 'hover');
+ expect(signal?.aborted).toBe(false);
+ view.dispose();
+ expect(signal?.aborted).toBe(true);
+ await preloaded;
+});
+
+it('keeps speculative admission alive after navigation commits, until account disposal', async () => {
+ const imported = Promise.withResolvers<void>();
+ const requested = vi.fn();
+ let admission: Promise<void> | undefined;
+ let signal: AbortSignal | undefined;
+ async function readAfterImport(lifetime: AbortSignal) {
+ await imported.promise;
+ if (!lifetime.aborted) requested();
+ }
+ const view = setup('/home', {
+ routes: {
+ ...appRoutes,
+ definitions: [
+ {
+ ...appRoute,
+ preload: (context) => {
+ signal = context.signal;
+ admission = readAfterImport(context.signal);
+ },
+ },
+ ],
+ },
+ });
+ try {
+ expect(view.router.ready()).toBe(true);
+ expect(signal?.aborted).toBe(false);
+ imported.resolve();
+ await admission;
+ expect(requested).toHaveBeenCalledOnce();
+ } finally {
+ imported.resolve();
+ await admission;
+ view.dispose();
+ }
+ expect(signal?.aborted).toBe(true);
+});
diff --git a/apps/web/src/lib/split-router/tests/solid.test.tsx b/apps/web/src/lib/split-router/tests/solid.test.tsx
index 406fa23cc6..7704592ef0 100644
--- a/apps/web/src/lib/split-router/tests/solid.test.tsx
+++ b/apps/web/src/lib/split-router/tests/solid.test.tsx
@@ -1,6 +1,7 @@
import { cleanup, fireEvent, render, screen } from '@solidjs/testing-library';
import {
createEffect,
+ createSignal,
For,
type JSX,
lazy,
@@ -301,6 +302,20 @@ it('opts a mounted view into leave guards for its search namespace', () => {
expect(screen.getByRole('button', { name: 'sort:date' })).toBeTruthy();
});
describe('split router Solid bindings', () => {
+ it('renders the root fallback while no pane is available', () => {
+ const [panes, setPanes] = createSignal<readonly PaneId[]>([]);
+ const { router } = renderRouter('/home', (router) => (
+ <SplitRouterProvider router={{ ...router, panes }}>
+ <Outlet fallback={() => <p>waiting for a pane</p>} />
+ </SplitRouterProvider>
+ ));
+ expect(screen.getByText('waiting for a pane')).toBeTruthy();
+ setPanes(router.panes());
+ expect(screen.getByText('home')).toBeTruthy();
+ setPanes([]);
+ expect(screen.getByText('waiting for a pane')).toBeTruthy();
+ });
+
it('keeps a view mounted while its remount key holds and updates params in place', async () => {
const { router } = renderPanes('/drive/md/d1');
const pane = router.panes()[0]!;
diff --git a/apps/web/src/lib/urql-solid/create-base-query.ts b/apps/web/src/lib/urql-solid/create-base-query.ts
index 6fe49bd873..b0c6a2c599 100644
--- a/apps/web/src/lib/urql-solid/create-base-query.ts
+++ b/apps/web/src/lib/urql-solid/create-base-query.ts
@@ -1,3 +1,5 @@
+import { useFlowTrace } from '@app/observability/flow';
+import { Telemetry } from '@macro-inc/observability';
import {
type Accessor,
batch,
@@ -14,6 +16,7 @@ import {
containsReactiveStore,
supportsStoreReconciliation,
} from './reactive-selection';
+import { TRACE_PARENT_CONTEXT_KEY } from './trace-parent-exchange';
/** Bridges a framework-neutral urql observer into one reactive Solid store. */
export function createBaseQuery<
@@ -25,7 +28,17 @@ export function createBaseQuery<
name: string
): Result {
const providerClient = useOptionalUrqlClient();
- const options = createMemo(getOptions);
+ // Requests sent while the enclosing view loads join its trace; see
+ // traceParentExchange.
+ const flow = useFlowTrace();
+ const options = createMemo(() => {
+ const next = getOptions();
+ if (!flow) return next;
+ return {
+ ...next,
+ context: { ...next.context, [TRACE_PARENT_CONTEXT_KEY]: flow },
+ };
+ });
const client = createMemo(() => {
const override = options().client;
@@ -88,7 +101,12 @@ export function createBaseQuery<
}
}
previous = next;
- setState(reconcile(reconciled));
+ const span = Telemetry.span('urql.reconcile', { sampling: 'perf' });
+ try {
+ setState(reconcile(reconciled));
+ } finally {
+ span.end();
+ }
})
);
};
diff --git a/apps/web/src/lib/urql-solid/observer.ts b/apps/web/src/lib/urql-solid/observer.ts
index 3911b677c0..fc8697c4e1 100644
--- a/apps/web/src/lib/urql-solid/observer.ts
+++ b/apps/web/src/lib/urql-solid/observer.ts
@@ -1,8 +1,9 @@
-import type { Client } from '@urql/core';
+import type { Client, OperationContext } from '@urql/core';
/** Query options accepted by the shared Solid observer adapter. */
export type ObserverClientOptions = {
client?: Client;
+ context?: Partial<OperationContext>;
};
/** Why an active urql execution reached its terminal lifecycle handler. */
diff --git a/apps/web/src/lib/urql-solid/trace-parent-exchange.test.ts b/apps/web/src/lib/urql-solid/trace-parent-exchange.test.ts
new file mode 100644
index 0000000000..b3f24a5599
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/trace-parent-exchange.test.ts
@@ -0,0 +1,90 @@
+import {
+ createClient,
+ fetchExchange,
+ gql,
+ type OperationResult,
+} from '@urql/core';
+import { describe, expect, it, vi } from 'vitest';
+import {
+ captureTraceParentExchange,
+ TRACE_PARENT_CONTEXT_KEY,
+ traceParentExchange,
+} from './trace-parent-exchange';
+
+const { active } = vi.hoisted(() => ({ active: [] as string[] }));
+
+vi.mock('@macro-inc/observability', () => ({
+ Telemetry: {
+ captureContext: () => {
+ const captured = active.at(-1);
+ return {
+ run: <T>(work: () => T): T =>
+ captured ? within(captured, work) : work(),
+ };
+ },
+ },
+}));
+
+function within<T>(name: string, work: () => T): T {
+ active.push(name);
+ try {
+ return work();
+ } finally {
+ active.pop();
+ }
+}
+
+const query = gql`
+ query Viewer($first: Int) {
+ viewer(first: $first) {
+ id
+ }
+ }
+`;
+
+function clientRecording(sentIn: (string | undefined)[]) {
+ return createClient({
+ url: 'https://example.test/graphql',
+ exchanges: [captureTraceParentExchange, traceParentExchange, fetchExchange],
+ fetch: async () => {
+ sentIn.push(active.at(-1));
+ return new Response(JSON.stringify({ data: { viewer: null } }), {
+ headers: { 'Content-Type': 'application/json' },
+ });
+ },
+ });
+}
+
+describe('trace parent exchanges', () => {
+ it('sends a request inside the trace its query asked for', async () => {
+ const sentIn: (string | undefined)[] = [];
+ const client = clientRecording(sentIn);
+ const parent = { run: <T>(work: () => T) => within('view.home', work) };
+
+ await client
+ .query(query, { first: 1 }, { [TRACE_PARENT_CONTEXT_KEY]: parent })
+ .toPromise();
+ await client
+ .query(query, { first: 2 }, { requestPolicy: 'network-only' })
+ .toPromise();
+
+ expect(sentIn).toEqual(['view.home', undefined]);
+ });
+
+ it('sends a query in the span it was started in, only for its first request', async () => {
+ const sentIn: (string | undefined)[] = [];
+ const client = clientRecording(sentIn);
+ const results: OperationResult[] = [];
+ const subscription = within('crm.contacts', () =>
+ client
+ .query(query, { first: 3 }, { requestPolicy: 'network-only' })
+ .subscribe((result) => results.push(result))
+ );
+ await vi.waitFor(() => expect(results).toHaveLength(1));
+ client.reexecuteOperation(results[0].operation);
+ await vi.waitFor(() => expect(sentIn).toHaveLength(2));
+ subscription.unsubscribe();
+
+ expect(sentIn).toEqual(['crm.contacts', undefined]);
+ });
+});
diff --git a/apps/web/src/lib/urql-solid/trace-parent-exchange.ts b/apps/web/src/lib/urql-solid/trace-parent-exchange.ts
new file mode 100644
index 0000000000..ba93bb873d
--- /dev/null
+++ b/apps/web/src/lib/urql-solid/trace-parent-exchange.ts
@@ -0,0 +1,63 @@
+import { Telemetry, type TraceContext } from '@macro-inc/observability';
+import { type Exchange, makeOperation, type Operation } from '@urql/core';
+import { map, pipe } from 'wonka';
+
+/** Operation context key for the trace a query's request should join. */
+export const TRACE_PARENT_CONTEXT_KEY = 'macroTraceParent';
+
+/**
+ * The caller's context for the operation's first request only: a re-sent
+ * operation (cache revalidation, refetch) must not join a trace that ended.
+ */
+function firstRequestIn(parent: TraceContext): TraceContext {
+ let used = false;
+ return {
+ run(work) {
+ if (used) return work();
+ used = true;
+ return parent.run(work);
+ },
+ };
+}
+
+// Mutations are sent by the mutation queue inside its own attempt span.
+function captured(operation: Operation): Operation {
+ if (operation.kind !== 'query' || operation.context[TRACE_PARENT_CONTEXT_KEY])
+ return operation;
+ return makeOperation(operation.kind, operation, {
+ ...operation.context,
+ [TRACE_PARENT_CONTEXT_KEY]: firstRequestIn(Telemetry.captureContext()),
+ });
+}
+
+function traced(operation: Operation): Operation {
+ const parent: TraceContext | undefined =
+ operation.context[TRACE_PARENT_CONTEXT_KEY];
+ if (!parent || operation.kind !== 'query') return operation;
+ const send = operation.context.fetch ?? fetch;
+ return makeOperation(operation.kind, operation, {
+ ...operation.context,
+ // fetchExchange calls this synchronously when it sends, so the transport's
+ // client span starts in the parent's trace and injects its traceparent.
+ fetch: (input, init) => parent.run(() => send(input, init)),
+ });
+}
+
+/**
+ * First in the chain: remembers the span context an operation was started in
+ * (client.query inside a span or a TanStack query function), unless a query
+ * binding already named its flow.
+ */
+export const captureTraceParentExchange: Exchange =
+ ({ forward }) =>
+ (operations$) =>
+ forward(pipe(operations$, map(captured)));
+
+/**
+ * Directly before `fetchExchange`: sends each request in the trace its
+ * operation carries. Cache hits never reach it.
+ */
+export const traceParentExchange: Exchange =
+ ({ forward }) =>
+ (operations$) =>
+ forward(pipe(operations$, map(traced)));
diff --git a/apps/web/src/observability/boot.test.ts b/apps/web/src/observability/boot.test.ts
new file mode 100644
index 0000000000..ca516d69b3
--- /dev/null
+++ b/apps/web/src/observability/boot.test.ts
@@ -0,0 +1,131 @@
+import { NOOP_SPAN, Telemetry } from '@macro-inc/observability';
+import { afterEach, expect, it, vi } from 'vitest';
+
+vi.mock('./flow', () => ({ beginInteraction: vi.fn() }));
+
+// The Performance API is browser-owned; control its entries and clock, while
+// observing the public telemetry calls used to reconstruct those entries.
+afterEach(() => {
+ vi.useRealTimers();
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+});
+
+it('starts at navigation time, lets the first view close its window, and aggregates resource timings without a second observer or resource spans', async () => {
+ vi.useFakeTimers();
+ const root = {
+ ...NOOP_SPAN,
+ run: <T>(fn: () => T) => fn(),
+ setAttr: vi.fn(),
+ event: vi.fn(),
+ end: vi.fn(),
+ };
+ const phase = { ...NOOP_SPAN, setAttr: vi.fn(), end: vi.fn() };
+ vi.spyOn(Telemetry, 'span').mockReturnValue(phase);
+ vi.stubGlobal('performance', {
+ timeOrigin: 1700000000000,
+ now: () => 200,
+ getEntriesByType: (type: string) => {
+ if (type === 'navigation')
+ return [
+ {
+ type: 'navigate',
+ domainLookupStart: 1,
+ domainLookupEnd: 2,
+ connectStart: 2,
+ connectEnd: 5,
+ secureConnectionStart: 3,
+ requestStart: 5,
+ responseStart: 10,
+ responseEnd: 20,
+ domInteractive: 30,
+ },
+ ];
+ if (type === 'mark')
+ return [
+ {
+ name: 'macro.auth.refresh-start',
+ startTime: 10,
+ detail: { generation: 0 },
+ },
+ {
+ name: 'macro.auth.refresh-start',
+ startTime: 12,
+ detail: { generation: 1 },
+ },
+ {
+ name: 'macro.auth.refresh-end',
+ startTime: 20,
+ detail: { generation: 0 },
+ },
+ {
+ name: 'macro.auth.refresh-end',
+ startTime: 24,
+ detail: { generation: 1 },
+ },
+ { name: 'macro.boot.render-start', startTime: 100 },
+ ];
+ if (type === 'resource')
+ return [
+ {
+ name: 'https://example.com/private/path.wasm?token=secret',
+ startTime: 30,
+ responseEnd: 80,
+ encodedBodySize: 100,
+ decodedBodySize: 200,
+ transferSize: 110,
+ },
+ ];
+ return [];
+ },
+ });
+ vi.stubGlobal(
+ 'PerformanceObserver',
+ class {
+ static supportedEntryTypes: string[] = [];
+ }
+ );
+ const { beginInteraction } = await import('./flow');
+ const { startBootTrace } = await import('./boot');
+ startBootTrace();
+ startBootTrace();
+ expect(beginInteraction).toHaveBeenCalledOnce();
+ const [name, options] = vi.mocked(beginInteraction).mock.calls[0]!;
+ expect(name).toBe('app.boot');
+ expect(options).toMatchObject({ startTime: 0, closeOnJoin: true });
+ options?.onFinish?.(root, 'success', 200);
+ expect(root.setAttr).toHaveBeenCalledWith('boot.outcome', 'success');
+ expect(Telemetry.span).toHaveBeenCalledWith('boot.auth.refresh', {
+ startTime: 1700000000010,
+ });
+ expect(phase.end).toHaveBeenCalledWith(1700000000020);
+ expect(Telemetry.span).toHaveBeenCalledWith('boot.auth.refresh', {
+ startTime: 1700000000012,
+ });
+ expect(phase.end).toHaveBeenCalledWith(1700000000024);
+ expect(root.event).toHaveBeenCalledWith(
+ 'macro.boot.render-start',
+ undefined,
+ 1700000000100
+ );
+ expect(root.setAttr).toHaveBeenCalledWith('boot.resource.wasm.count', 1);
+ expect(root.setAttr).toHaveBeenCalledWith(
+ 'boot.resource.wasm.encoded_bytes',
+ 100
+ );
+ expect(root.setAttr).toHaveBeenCalledWith(
+ 'boot.resource.wasm.transfer_bytes',
+ 110
+ );
+ expect(root.setAttr).toHaveBeenCalledWith(
+ 'boot.resource.wasm.duration_ms',
+ 50
+ );
+ expect(Telemetry.span).toHaveBeenCalledTimes(8);
+ expect(
+ vi.mocked(Telemetry.span).mock.calls.map(([name]) => name)
+ ).not.toContain('boot.resource.wasm');
+ expect(JSON.stringify(phase.setAttr.mock.calls)).not.toContain('secret');
+ expect(JSON.stringify(root.setAttr.mock.calls)).not.toContain('private');
+});
diff --git a/apps/web/src/observability/boot.ts b/apps/web/src/observability/boot.ts
new file mode 100644
index 0000000000..40eaba6336
--- /dev/null
+++ b/apps/web/src/observability/boot.ts
@@ -0,0 +1,159 @@
+import { type Span, Telemetry } from '@macro-inc/observability';
+import { beginInteraction } from './flow';
+import type { UiOperationOutcome } from './ui-operation';
+
+let started = false;
+
+/**
+ * Trace boot as an interaction that starts at navigation start; the first
+ * view joins it, and it finishes at that view's paint opportunity. Call after
+ * the provider and UI operation telemetry are registered, before rendering.
+ */
+export function startBootTrace(): void {
+ if (started || typeof performance === 'undefined') return;
+ started = true;
+ beginInteraction('app.boot', {
+ kind: 'boot',
+ startTime: 0,
+ closeOnJoin: true,
+ onFinish: reconstructBoot,
+ });
+}
+
+function interval(
+ boot: Span,
+ name: string,
+ start: number,
+ end: number,
+ attributes?: Record<string, string | number>
+): void {
+ if (start < 0 || end <= start) return;
+ const span = boot.run(() =>
+ Telemetry.span(name, { startTime: performance.timeOrigin + start })
+ );
+ for (const [key, value] of Object.entries(attributes ?? {}))
+ span.setAttr(key, value);
+ span.end(performance.timeOrigin + end);
+}
+
+/** Reconstruct browser work once the first view reaches its paint opportunity. */
+function reconstructBoot(
+ boot: Span,
+ outcome: UiOperationOutcome,
+ end: number
+): void {
+ const navigation = performance.getEntriesByType('navigation')[0] as
+ | PerformanceNavigationTiming
+ | undefined;
+ if (navigation) {
+ boot.setAttr('boot.navigation_type', navigation.type);
+ interval(
+ boot,
+ 'boot.dns',
+ navigation.domainLookupStart,
+ navigation.domainLookupEnd
+ );
+ interval(
+ boot,
+ 'boot.connect',
+ navigation.connectStart,
+ navigation.connectEnd
+ );
+ if (navigation.secureConnectionStart > 0)
+ interval(
+ boot,
+ 'boot.tls',
+ navigation.secureConnectionStart,
+ navigation.connectEnd
+ );
+ interval(
+ boot,
+ 'boot.request',
+ navigation.requestStart,
+ navigation.responseStart
+ );
+ interval(
+ boot,
+ 'boot.response',
+ navigation.responseStart,
+ navigation.responseEnd
+ );
+ interval(
+ boot,
+ 'boot.dom',
+ navigation.responseEnd,
+ navigation.domInteractive
+ );
+ }
+ const refreshStarts = new Map<number, number>();
+ for (const mark of performance.getEntriesByType('mark')) {
+ if (mark.name.startsWith('macro.') && mark.startTime <= end) {
+ boot.event(mark.name, undefined, performance.timeOrigin + mark.startTime);
+ const detail = 'detail' in mark ? mark.detail : undefined;
+ if (
+ !detail ||
+ typeof detail !== 'object' ||
+ !('generation' in detail) ||
+ typeof detail.generation !== 'number'
+ )
+ continue;
+ if (mark.name === 'macro.auth.refresh-start') {
+ refreshStarts.set(detail.generation, mark.startTime);
+ } else if (mark.name === 'macro.auth.refresh-end') {
+ const start = refreshStarts.get(detail.generation);
+ // Provider registration may follow refresh; account resets can overlap
+ // old and new attempts, so pair only marks from the same generation.
+ if (start !== undefined)
+ interval(boot, 'boot.auth.refresh', start, mark.startTime);
+ refreshStarts.delete(detail.generation);
+ }
+ }
+ }
+ const resources = {
+ script: {
+ count: 0,
+ encoded_bytes: 0,
+ decoded_bytes: 0,
+ transfer_bytes: 0,
+ duration_ms: 0,
+ },
+ wasm: {
+ count: 0,
+ encoded_bytes: 0,
+ decoded_bytes: 0,
+ transfer_bytes: 0,
+ duration_ms: 0,
+ },
+ font: {
+ count: 0,
+ encoded_bytes: 0,
+ decoded_bytes: 0,
+ transfer_bytes: 0,
+ duration_ms: 0,
+ },
+ };
+ for (const entry of performance.getEntriesByType('resource')) {
+ const resource = entry as PerformanceResourceTiming;
+ if (resource.responseEnd > end) continue;
+ const path = new URL(resource.name, location.href).pathname;
+ const kind = path.endsWith('.wasm')
+ ? 'wasm'
+ : /\.(woff2?|ttf|otf)$/.test(path)
+ ? 'font'
+ : path.endsWith('.js')
+ ? 'script'
+ : undefined;
+ if (!kind) continue;
+ const totals = resources[kind];
+ totals.count++;
+ totals.encoded_bytes += resource.encodedBodySize;
+ totals.decoded_bytes += resource.decodedBodySize;
+ totals.transfer_bytes += resource.transferSize;
+ totals.duration_ms += resource.responseEnd - resource.startTime;
+ }
+ for (const [kind, totals] of Object.entries(resources)) {
+ for (const [metric, value] of Object.entries(totals))
+ boot.setAttr(`boot.resource.${kind}.${metric}`, value);
+ }
+ boot.setAttr('boot.outcome', outcome);
+}
diff --git a/apps/web/src/observability/browser.test.ts b/apps/web/src/observability/browser.test.ts
index b87eeb5969..caefdb9d53 100644
--- a/apps/web/src/observability/browser.test.ts
+++ b/apps/web/src/observability/browser.test.ts
@@ -4,6 +4,7 @@ import { initializeBrowserObservability } from './browser';
import { readDesktopDiagnostics } from './desktop';
import { clearDocumentLifecycle } from './document-lifecycle';
import { frontendInstanceId } from './frontend-instance';
+import { startRuntimeResourceSampling } from './runtime-resources';
import { initializeUiOperationTelemetry } from './ui-operation';
const startupSpan = vi.hoisted(() => ({
@@ -29,10 +30,17 @@ vi.mock('@macro-inc/observability', () => ({
}));
vi.mock('@macro-inc/observability/web', () => ({
createWebTracingProvider: vi.fn(),
+ StackContextManager: class {},
}));
-vi.mock('@macro-inc/observability/zone', () => ({
- ZoneContextManager: class {},
+vi.mock('./typing-burst', () => ({
+ startTypingBurstTelemetry: vi.fn(() => vi.fn()),
}));
+
+vi.mock('./runtime-resources', () => ({
+ startRuntimeResourceSampling: vi.fn(() => vi.fn()),
+}));
+vi.mock('./boot', () => ({ startBootTrace: vi.fn() }));
+vi.mock('./os-type', () => ({ osType: () => 'linux' }));
vi.mock('./ui-operation', () => ({
initializeUiOperationTelemetry: vi.fn(() => vi.fn()),
}));
@@ -76,10 +84,15 @@ it('explicit native recording overrides the normal enablement gate and exporter
await initializeBrowserObservability();
const config = vi.mocked(Telemetry.init).mock.calls[0][0];
expect(await config.enabled()).toBe(true);
- expect(config.recording).toBe(true);
+ expect((await config.startup)?.recording).toBe(true);
+ expect(startRuntimeResourceSampling).toHaveBeenCalledOnce();
+ const read = vi.mocked(startRuntimeResourceSampling).mock.calls[0][0];
+ expect(await read?.()).toEqual({});
expect(initializeUiOperationTelemetry).toHaveBeenCalledOnce();
- expect(config.tracesUrl).toBe('http://localhost:4318/v1/traces');
- expect(config.logsUrl).toBe('http://localhost:4318/v1/logs');
+ expect((await config.startup)?.tracesUrl).toBe(
+ 'http://localhost:4318/v1/traces'
+ );
+ expect((await config.startup)?.logsUrl).toBe('http://localhost:4318/v1/logs');
expect(config.resourceAttributes).toMatchObject({
'app.runtime': 'tauri',
frontend_instance_id: frontendInstanceId,
@@ -148,11 +161,12 @@ it('an older binary without diagnostics still obeys the normal telemetry gate',
await initializeBrowserObservability();
const config = vi.mocked(Telemetry.init).mock.calls[0][0];
expect(await config.enabled()).toBe(false);
- expect(config.recording).toBe(false);
- expect(initializeUiOperationTelemetry).not.toHaveBeenCalled();
+ expect((await config.startup)?.recording).toBe(false);
+ expect(initializeUiOperationTelemetry).toHaveBeenCalledOnce();
expect(config.resourceAttributes).toMatchObject({
'app.runtime': 'tauri',
'app.platform': 'desktop',
+ 'os.type': 'linux',
});
expect(startupSpan.setAttr).toHaveBeenCalledWith(
'previous_document_checkpoint_available',
@@ -195,3 +209,38 @@ it('revokes the previous document identity if logout happens while telemetry ini
expect.anything()
);
});
+
+it('registers the native provider before waiting for a single enablement decision', async () => {
+ vi.mocked(readDesktopDiagnostics).mockResolvedValue(undefined);
+ const decide = Promise.withResolvers<void>();
+ const reached = Promise.withResolvers<void>();
+ const onProviderReady = vi.fn();
+ vi.mocked(Telemetry.init).mockImplementation(async (config) => {
+ // Every consumer must get the same decision, including the exporter.
+ expect(config.enabled()).toBe(config.enabled());
+ reached.resolve();
+ await decide.promise;
+ });
+ const initializing = initializeBrowserObservability(onProviderReady);
+ await reached.promise;
+ expect(onProviderReady).toHaveBeenCalledOnce();
+ expect(initializeUiOperationTelemetry).toHaveBeenCalledOnce();
+ decide.resolve();
+ await initializing;
+});
+
+it('registers the provider and releases native render while diagnostics remain pending', async () => {
+ let finish: (snapshot: undefined) => void = () => {};
+ vi.mocked(readDesktopDiagnostics).mockReturnValue(
+ new Promise((resolve) => {
+ finish = resolve;
+ })
+ );
+ const ready = vi.fn();
+ const initialization = initializeBrowserObservability(ready);
+ expect(Telemetry.init).toHaveBeenCalledOnce();
+ expect(ready).toHaveBeenCalledOnce();
+ expect(initializeUiOperationTelemetry).toHaveBeenCalledOnce();
+ finish(undefined);
+ await initialization;
+});
diff --git a/apps/web/src/observability/browser.ts b/apps/web/src/observability/browser.ts
index d41f946980..2ee9b090b8 100644
--- a/apps/web/src/observability/browser.ts
+++ b/apps/web/src/observability/browser.ts
@@ -1,13 +1,18 @@
+import { DEVELOPMENT_PROXY_PREFIX } from '@core/constant/developmentProxy';
import { fireAndForget } from '@core/util/fireAndForget';
import { isIgnorableError } from '@core/util/ignorableErrors';
import { getPlatform, isTauri } from '@core/util/platform';
+import { webviewFetch } from '@core/util/platformFetch';
import { recordBrowserTursoCacheNavigation } from '@graphql-cache/rollout-observability';
-import { Telemetry } from '@macro-inc/observability';
-import { createWebTracingProvider } from '@macro-inc/observability/web';
-// This static import loads the zone.js Promise patch before application modules run.
-import { ZoneContextManager } from '@macro-inc/observability/zone';
+import { Telemetry, type TelemetryInitConfig } from '@macro-inc/observability';
+import {
+ createWebTracingProvider,
+ StackContextManager,
+} from '@macro-inc/observability/web';
+import { startBootTrace } from './boot';
import {
createDesktopMemoryRecording,
+ type DesktopSnapshot,
desktopResourceAttributes,
readDesktopDiagnostics,
} from './desktop';
@@ -16,6 +21,10 @@ import { frontendInstanceId } from './frontend-instance';
import { configureNativeCallTracing } from './native-call-tracing';
import { startNativeDiagnostics } from './native-diagnostics';
import { recordNativeWebviewStart } from './native-lifecycle';
+import { osType } from './os-type';
+import { startRuntimeResourceSampling } from './runtime-resources';
+import { samplingKey, samplingRates } from './sampling';
+import { startTypingBurstTelemetry } from './typing-burst';
import { initializeUiOperationTelemetry } from './ui-operation';
async function browserTelemetryEnabled(hasExporter: boolean): Promise<boolean> {
@@ -56,79 +65,138 @@ async function browserTelemetryEnabled(hasExporter: boolean): Promise<boolean> {
});
}
+/**
+ * A local stack's analytics proxy forwards to the collector; the standalone
+ * dev server against hosted dev reaches it through its own proxy.
+ */
+function localDevelopmentTracesUrl(): string {
+ const standalone =
+ import.meta.env.VITE_DEV_PROXY === true ||
+ import.meta.env.VITE_DEV_PROXY === 'true';
+ return standalone
+ ? `${DEVELOPMENT_PROXY_PREFIX}/otlp/v1/traces`
+ : 'http://localhost:8098/i/otlp/v1/traces';
+}
+
/** Initialize browser telemetry and its application-level lifecycle hooks. */
-export async function initializeBrowserObservability(): Promise<void> {
+export async function initializeBrowserObservability(
+ onProviderReady?: () => void
+): Promise<void> {
const lifecycle = isTauri() ? startDocumentLifecycle() : undefined;
import.meta.hot?.dispose(() => lifecycle?.dispose());
let browserEnabled = false;
- const desktop = await readDesktopDiagnostics();
- const disposeNativeDiagnostics = startNativeDiagnostics(desktop);
- import.meta.hot?.dispose(disposeNativeDiagnostics);
- const recording = desktop?.identity.recordingId
- ? createDesktopMemoryRecording(desktop)
- : undefined;
+ const native = isTauri();
+ const desktopReady = native
+ ? Promise.resolve().then(() => readDesktopDiagnostics())
+ : Promise.resolve(undefined);
+ let desktop: DesktopSnapshot | undefined;
+ let recording: ReturnType<typeof createDesktopMemoryRecording> | undefined;
+ let disposed = false;
+ import.meta.hot?.dispose(() => {
+ disposed = true;
+ });
const configuredTracesUrl =
- desktop?.identity.tracesUrl ??
import.meta.env.VITE_OTEL_EXPORTER_URL ??
- (import.meta.hot ? 'http://localhost:8098/i/otlp/v1/traces' : undefined);
+ (import.meta.hot ? localDevelopmentTracesUrl() : undefined);
// Local stacks use a same-origin path; exporters expect an absolute URL.
- const tracesUrl = configuredTracesUrl
+ const fallbackTracesUrl = configuredTracesUrl
? new URL(configuredTracesUrl, window.location.origin).href
: undefined;
- const telemetryConfig = {
+ const startup = desktopReady.then((snapshot) => {
+ desktop = snapshot;
+ recording = snapshot?.identity.recordingId
+ ? createDesktopMemoryRecording(snapshot)
+ : undefined;
+ if (!disposed) {
+ const dispose = startNativeDiagnostics(snapshot);
+ import.meta.hot?.dispose(dispose);
+ }
+ const destination = snapshot?.identity.tracesUrl ?? fallbackTracesUrl;
+ const tracesUrl = destination
+ ? new URL(destination, window.location.origin).href
+ : undefined;
+ return {
+ recording: Boolean(recording),
+ tracesUrl,
+ logsUrl: tracesUrl?.replace(/\/v1\/traces\/?$/, '/v1/logs'),
+ };
+ });
+ const environment =
+ import.meta.env.VITE_OTEL_ENV ??
+ (import.meta.env.MODE === 'production' ? 'prod' : 'dev');
+ let enablement: Promise<boolean> | undefined;
+ async function resolveEnablement(): Promise<boolean> {
+ const settings = await startup;
+ browserEnabled = settings.recording
+ ? true
+ : await browserTelemetryEnabled(Boolean(settings.tracesUrl));
+ return browserEnabled;
+ }
+ const telemetryConfig: TelemetryInitConfig = {
serviceName: 'web-app',
- environment:
- import.meta.env.VITE_OTEL_ENV ??
- (import.meta.env.MODE === 'production' ? 'prod' : 'dev'),
- tracesUrl,
- logsUrl: tracesUrl?.replace(/\/v1\/traces\/?$/, '/v1/logs'),
- contextManager: new ZoneContextManager(),
+ environment,
+ sampling: samplingRates(environment),
+ samplingKey,
+ tracesUrl: fallbackTracesUrl,
+ logsUrl: fallbackTracesUrl?.replace(/\/v1\/traces\/?$/, '/v1/logs'),
+ exportFetch: (input, init) =>
+ webviewFetch(input, { ...init, credentials: 'omit' }),
+ startup: native ? startup : undefined,
+ contextManager: new StackContextManager(),
resourceAttributes: {
'service.version': import.meta.env.__APP_VERSION__,
frontend_instance_id: frontendInstanceId,
'app.runtime': isTauri() ? 'tauri' : 'browser',
'app.platform': getPlatform(),
- ...(desktop && desktopResourceAttributes(desktop)),
+ 'os.type': osType(),
+ ...(native && desktopResourceAttributes(desktopReady)),
},
- recording: Boolean(recording),
spanAttributes: () => ({
...recording?.attributes(),
frontend_instance_id: frontendInstanceId,
native_instance_id: desktop?.identity.instanceId,
}),
- enabled: async () => {
- browserEnabled = recording
- ? true
- : await browserTelemetryEnabled(Boolean(tracesUrl));
- return browserEnabled;
- },
+ enabled: () => (enablement ??= resolveEnablement()),
};
- await Telemetry.init({
+ const initialization = Telemetry.init({
...telemetryConfig,
- tracingProvider: (resource, getUserId) =>
- createWebTracingProvider(telemetryConfig, resource, getUserId),
+ tracingProvider: (resource, getUserId, sampling) =>
+ createWebTracingProvider(telemetryConfig, resource, getUserId, sampling),
});
+ // Capture early UI operations locally while the exporter awaits enablement.
+ const disposeUiTelemetry = initializeUiOperationTelemetry();
+ import.meta.hot?.dispose(disposeUiTelemetry);
+ startBootTrace();
+ onProviderReady?.();
+ await initialization;
+ const { tracesUrl } = await startup;
+ if (disposed) return;
await configureNativeCallTracing({
enabled: browserEnabled,
tracesUrl,
environment: telemetryConfig.environment,
}).catch(() => Telemetry.warn('Native call tracing configuration failed'));
if (isTauri()) recordNativeWebviewStart(desktop, lifecycle?.attributes);
- if (recording && desktop) {
- recording.accept(desktop);
+ const memoryRecording = recording;
+ if (memoryRecording && desktop) {
+ memoryRecording.accept(desktop);
Telemetry.info('Desktop memory recording enabled', {
'macro.recording.id': desktop.identity.recordingId ?? undefined,
'service.instance.id': desktop.identity.instanceId,
});
- fireAndForget(recording.start(), 'desktop-memory-recording');
- import.meta.hot?.dispose(() => recording.dispose());
+ fireAndForget(memoryRecording.start(), 'desktop-memory-recording');
+ import.meta.hot?.dispose(() => memoryRecording.dispose());
}
- recordBrowserTursoCacheNavigation();
if (browserEnabled) {
- const disposeUiTelemetry = initializeUiOperationTelemetry();
- import.meta.hot?.dispose(disposeUiTelemetry);
+ const disposeTyping = startTypingBurstTelemetry();
+ import.meta.hot?.dispose(disposeTyping);
+ const disposeResources = startRuntimeResourceSampling(
+ recording?.attributes
+ );
+ import.meta.hot?.dispose(disposeResources);
}
+ recordBrowserTursoCacheNavigation();
window.addEventListener('pagehide', () =>
fireAndForget(Telemetry.flush(), 'telemetry-flush')
diff --git a/apps/web/src/observability/desktop.test.ts b/apps/web/src/observability/desktop.test.ts
index 6692c567ab..92408ac161 100644
--- a/apps/web/src/observability/desktop.test.ts
+++ b/apps/web/src/observability/desktop.test.ts
@@ -76,7 +76,6 @@ describe('desktop recording', () => {
'app.platform': 'desktop',
'service.instance.id': 'launch-1',
'macro.recording.id': 'recording-1',
- 'os.type': 'darwin',
});
recorded.identity.recordingId = null;
expect(desktopResourceAttributes(recorded)).toMatchObject({
@@ -85,6 +84,16 @@ describe('desktop recording', () => {
});
});
+ it('keeps known runtime attributes when asynchronous diagnostics are unavailable', async () => {
+ const attributes = desktopResourceAttributes(Promise.resolve(undefined));
+ expect(attributes['app.runtime']).toBe('tauri');
+ expect(attributes['app.platform']).toBe('desktop');
+ expect(await attributes['service.instance.id']).toBeUndefined();
+ const recorded = desktopResourceAttributes(Promise.resolve(snapshot([])));
+ expect(await recorded['service.instance.id']).toBe('launch-1');
+ expect(await recorded['macro.recording.id']).toBe('recording-1');
+ });
+
it('exports each new sample once, preserves sample times, and expires stale readings', () => {
vi.useFakeTimers();
vi.setSystemTime(2000);
diff --git a/apps/web/src/observability/desktop.ts b/apps/web/src/observability/desktop.ts
index 7cbd2293c7..c864b6333f 100644
--- a/apps/web/src/observability/desktop.ts
+++ b/apps/web/src/observability/desktop.ts
@@ -1,6 +1,11 @@
import { fireAndForget } from '@core/util/fireAndForget';
import { getPlatform, isTauri } from '@core/util/platform';
-import { type Attributes, Telemetry } from '@macro-inc/observability';
+import {
+ type Attribute,
+ type Attributes,
+ type ResourceAttributes,
+ Telemetry,
+} from '@macro-inc/observability';
import { invoke } from '@tauri-apps/api/core';
import type { BundleReloadDiagnostics } from './generated/bundle-reloads';
import type { EventSnapshot } from './generated/native-diagnostics';
@@ -91,20 +96,40 @@ export function memoryAttributes(sample: MemorySample): Attributes {
return attributes;
}
+const desktopResourceReaders: Record<
+ string,
+ (snapshot: DesktopSnapshot) => Attribute | undefined
+> = {
+ 'service.instance.id': (snapshot) => snapshot.identity.instanceId,
+ native_instance_id: (snapshot) => snapshot.identity.instanceId,
+ 'macro.recording.id': (snapshot) =>
+ snapshot.identity.recordingId ?? undefined,
+ 'macro.recording.enabled': (snapshot) =>
+ snapshot.identity.recordingId !== null,
+ 'macro.native.version': (snapshot) => snapshot.identity.nativeVersion,
+ 'macro.native.pid': (snapshot) => snapshot.identity.hostPid,
+};
+
export function desktopResourceAttributes(
snapshot: DesktopSnapshot
-): Attributes {
+): Attributes;
+export function desktopResourceAttributes(
+ snapshot: Promise<DesktopSnapshot | undefined>
+): ResourceAttributes;
+export function desktopResourceAttributes(
+ snapshot: DesktopSnapshot | Promise<DesktopSnapshot | undefined>
+): ResourceAttributes {
return {
'app.runtime': 'tauri',
'app.platform': getPlatform(),
- 'service.instance.id': snapshot.identity.instanceId,
- native_instance_id: snapshot.identity.instanceId,
- 'macro.recording.id': snapshot.identity.recordingId ?? undefined,
- 'macro.recording.enabled': snapshot.identity.recordingId !== null,
- 'macro.native.version': snapshot.identity.nativeVersion,
- 'os.type':
- snapshot.identity.os === 'macos' ? 'darwin' : snapshot.identity.os,
- 'macro.native.pid': snapshot.identity.hostPid,
+ ...Object.fromEntries(
+ Object.entries(desktopResourceReaders).map(([key, read]) => [
+ key,
+ snapshot instanceof Promise
+ ? snapshot.then((value) => (value ? read(value) : undefined))
+ : read(snapshot),
+ ])
+ ),
};
}
diff --git a/apps/web/src/observability/flow.test.tsx b/apps/web/src/observability/flow.test.tsx
new file mode 100644
index 0000000000..63039f3ccf
--- /dev/null
+++ b/apps/web/src/observability/flow.test.tsx
@@ -0,0 +1,479 @@
+import { render } from '@solidjs/testing-library';
+import { createSignal, Show } from 'solid-js';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { beginInteraction, TraceFlow, useFlow, usePending } from './flow';
+
+type Recorded = {
+ name: string;
+ parent: string | undefined;
+ attrs: Record<string, unknown>;
+ events: string[];
+ ended: boolean;
+};
+
+const { spans, operations, contexts } = vi.hoisted(() => ({
+ spans: [] as Recorded[],
+ operations: [] as { name: string; outcome: string | undefined }[],
+ /** The span each `run` call made active, innermost last. */
+ contexts: [] as string[],
+}));
+
+vi.mock('./ui-operation', () => {
+ function makeSpan(name: string, parent: string | undefined) {
+ const record: Recorded = {
+ name,
+ parent,
+ attrs: {},
+ events: [],
+ ended: false,
+ };
+ spans.push(record);
+ const span = {
+ span: (child: string) => makeSpan(child, name),
+ run: <T,>(work: () => T) => {
+ contexts.push(name);
+ try {
+ return work();
+ } finally {
+ contexts.pop();
+ }
+ },
+ setAttr: (key: string, value: unknown) => {
+ record.attrs[key] = value;
+ },
+ event: (event: string) => record.events.push(event),
+ error: () => {},
+ end: () => {
+ record.ended = true;
+ },
+ };
+ return span;
+ }
+ return {
+ setActiveRoute: () => {},
+ currentRoute: () => undefined,
+ startUiOperation: (
+ name: string,
+ options: { kind?: string; attributes?: Record<string, unknown> } = {}
+ ) => {
+ const operation = { name, outcome: undefined as string | undefined };
+ operations.push(operation);
+ const span = makeSpan(name, undefined);
+ span.setAttr('flow.kind', options.kind);
+ for (const [key, value] of Object.entries(options.attributes ?? {}))
+ span.setAttr(key, value);
+ return {
+ span,
+ get ended() {
+ return operation.outcome !== undefined;
+ },
+ afterPaint: () => {
+ operation.outcome ??= 'painted';
+ },
+ cancel: () => {
+ operation.outcome ??= 'cancelled';
+ },
+ finish: (outcome = 'success') => {
+ operation.outcome ??= outcome;
+ },
+ };
+ },
+ };
+});
+
+const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
+
+describe('TraceFlow', () => {
+ beforeEach(() => {
+ spans.length = 0;
+ operations.length = 0;
+ contexts.length = 0;
+ });
+
+ it('stays open until every pending phase under it has loaded', async () => {
+ const [items, setItems] = createSignal(true);
+ const [preview, setPreview] = createSignal(true);
+ function Items() {
+ usePending('home.items', items);
+ return null;
+ }
+ function Preview() {
+ usePending('home.preview', preview);
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="home.load">
+ <Items />
+ <Preview />
+ </TraceFlow>
+ ));
+ await flush();
+ expect(operations).toEqual([{ name: 'home.load', outcome: undefined }]);
+
+ setItems(false);
+ await flush();
+ expect(spans.find((span) => span.name === 'home.items')).toMatchObject({
+ parent: 'home.load',
+ ended: true,
+ attrs: { 'flow.outcome': 'success' },
+ });
+ expect(operations[0].outcome).toBeUndefined();
+
+ setPreview(false);
+ await flush();
+ expect(operations[0].outcome).toBe('painted');
+ });
+
+ it('records a phase that was already loaded as an event, not a span', async () => {
+ function Cached() {
+ usePending('home.items', () => false);
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="home.load">
+ <Cached />
+ </TraceFlow>
+ ));
+ await flush();
+ expect(spans.map((span) => span.name)).toEqual(['home.load']);
+ expect(spans[0].events).toEqual(['home.items.ready']);
+ expect(spans[0].attrs).toMatchObject({
+ 'home.items.waited': false,
+ 'flow.ready_phase_count': 1,
+ 'flow.phase_count': 0,
+ });
+ expect(operations[0].outcome).toBe('painted');
+ });
+
+ it('records a flow that unmounts while loading as cancelled', async () => {
+ const [shown, setShown] = createSignal(true);
+ function Loading() {
+ usePending('doc.content', () => true);
+ return null;
+ }
+ render(() => (
+ <Show when={shown()}>
+ <TraceFlow name="doc.view">
+ <Loading />
+ </TraceFlow>
+ </Show>
+ ));
+ await flush();
+ setShown(false);
+ expect(operations[0].outcome).toBe('cancelled');
+ expect(spans.find((span) => span.name === 'doc.content')).toMatchObject({
+ ended: true,
+ attrs: { 'flow.outcome': 'cancelled' },
+ });
+ });
+
+ it('joins the interaction that opened it, so the trace runs from input to the view', async () => {
+ const [loading, setLoading] = createSignal(true);
+ function Content() {
+ usePending('doc.content', loading);
+ return null;
+ }
+ const interaction = beginInteraction('nav.open');
+ render(() => (
+ <TraceFlow name="doc.view">
+ <Content />
+ </TraceFlow>
+ ));
+ interaction.end();
+ await flush();
+ expect(operations).toEqual([{ name: 'nav.open', outcome: undefined }]);
+ expect(spans.find((span) => span.name === 'doc.view')?.parent).toBe(
+ 'nav.open'
+ );
+
+ setLoading(false);
+ await flush();
+ expect(operations[0].outcome).toBe('painted');
+ });
+
+ it('ends an interaction that opened no view one paint after it ends', async () => {
+ beginInteraction('panel.toggle').end();
+ expect(operations).toEqual([{ name: 'panel.toggle', outcome: 'painted' }]);
+ });
+
+ it('starts a new trace instead of joining a flow that timed out', async () => {
+ const [later, setLater] = createSignal(false);
+ function Stuck() {
+ usePending('home.items', () => true);
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="home.load">
+ <Stuck />
+ <Show when={later()}>
+ <TraceFlow name="settings.view">{null}</TraceFlow>
+ </Show>
+ </TraceFlow>
+ ));
+ await flush();
+ operations[0].outcome = 'timeout';
+ setLater(true);
+ expect(operations.map((operation) => operation.name)).toEqual([
+ 'home.load',
+ 'settings.view',
+ ]);
+ });
+
+ it('starts again when its key changes in place, joining the navigation that changed it', async () => {
+ const [id, setId] = createSignal('a');
+ const [loading, setLoading] = createSignal(false);
+ function Content() {
+ usePending('doc.content', loading);
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="view.doc" key={id}>
+ <Content />
+ </TraceFlow>
+ ));
+ await flush();
+ expect(operations).toEqual([{ name: 'view.doc', outcome: 'painted' }]);
+
+ const navigation = beginInteraction('navigation');
+ setId('b');
+ setLoading(true);
+ navigation.end();
+ await flush();
+ expect(
+ spans.filter((span) => span.name === 'view.doc').at(-1)?.parent
+ ).toBe('navigation');
+ expect(spans.find((span) => span.name === 'doc.content')).toMatchObject({
+ parent: 'view.doc',
+ ended: false,
+ });
+ expect(operations[1]).toEqual({ name: 'navigation', outcome: undefined });
+
+ setLoading(false);
+ await flush();
+ expect(operations[1].outcome).toBe('painted');
+ });
+
+ it('moves a still-pending phase to each restart of a keyed flow', async () => {
+ const [query, setQuery] = createSignal('a');
+ const [searching, setSearching] = createSignal(true);
+ function Results() {
+ usePending('search.results', searching);
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="search.flow" key={query}>
+ <Results />
+ </TraceFlow>
+ ));
+ await flush();
+ setQuery('ab');
+ await flush();
+ setQuery('abc');
+ await flush();
+ const phases = spans.filter((span) => span.name === 'search.results');
+ expect(phases.map((span) => span.attrs['flow.outcome'])).toEqual([
+ 'cancelled',
+ 'cancelled',
+ undefined,
+ ]);
+ expect(operations.map((operation) => operation.outcome)).toEqual([
+ 'cancelled',
+ 'cancelled',
+ undefined,
+ ]);
+
+ setSearching(false);
+ await flush();
+ expect(operations.at(-1)?.outcome).toBe('painted');
+ });
+
+ it('makes an interaction begun inside another a phase of it', () => {
+ const outer = beginInteraction('app.boot');
+ const inner = beginInteraction('navigation');
+ inner.end();
+ expect(operations.map((operation) => operation.name)).toEqual(['app.boot']);
+ expect(spans.find((span) => span.name === 'navigation')?.parent).toBe(
+ 'app.boot'
+ );
+ outer.end();
+ expect(operations[0].outcome).toBe('painted');
+ });
+
+ it('lets only the first view join an interaction that closes on join', async () => {
+ const boot = beginInteraction('app.boot', { closeOnJoin: true });
+ render(() => <TraceFlow name="view.home">{null}</TraceFlow>);
+ render(() => <TraceFlow name="view.settings">{null}</TraceFlow>);
+ await flush();
+ expect(spans.find((span) => span.name === 'view.home')?.parent).toBe(
+ 'app.boot'
+ );
+ expect(operations.map((operation) => operation.name)).toEqual([
+ 'app.boot',
+ 'view.settings',
+ ]);
+ expect(operations[0].outcome).toBe('painted');
+ boot.end();
+ });
+
+ it('starts its own trace once the flow it is nested in has settled', async () => {
+ const [later, setLater] = createSignal(false);
+ render(() => (
+ <TraceFlow name="app.shell">
+ <Show when={later()}>
+ <TraceFlow name="settings.view">{null}</TraceFlow>
+ </Show>
+ </TraceFlow>
+ ));
+ await flush();
+ setLater(true);
+ await flush();
+ expect(operations.map((operation) => operation.name)).toEqual([
+ 'app.shell',
+ 'settings.view',
+ ]);
+ });
+
+ it('tags roots with their kind and every phase with its root and route', async () => {
+ const [loading, setLoading] = createSignal(true);
+ function Content() {
+ usePending('doc.content', loading);
+ return null;
+ }
+ const navigation = beginInteraction('navigation', { kind: 'navigation' });
+ render(() => (
+ <TraceFlow name="view.app" attributes={{ 'route.id': 'app' }}>
+ <TraceFlow name="view.doc" attributes={{ 'route.id': 'doc' }}>
+ <Content />
+ </TraceFlow>
+ </TraceFlow>
+ ));
+ navigation.end();
+ await flush();
+ setLoading(false);
+ await flush();
+ const span = (name: string) => spans.find((each) => each.name === name);
+ expect(span('navigation')?.attrs).toMatchObject({
+ 'flow.kind': 'navigation',
+ 'route.id': 'doc',
+ 'flow.phase_count': 3,
+ 'flow.ready_phase_count': 0,
+ });
+ expect(span('view.app')?.attrs).toMatchObject({
+ 'flow.root': 'navigation',
+ 'route.id': 'app',
+ });
+ expect(span('view.doc')?.attrs).toMatchObject({
+ 'flow.root': 'navigation',
+ 'route.id': 'doc',
+ });
+ expect(span('view.doc')?.attrs['doc.content.waited']).toBe(true);
+ expect(span('doc.content')?.attrs).toMatchObject({
+ 'flow.root': 'navigation',
+ 'route.id': 'doc',
+ 'flow.outcome': 'success',
+ });
+ });
+
+ it('records a flow with no interaction to join as a view root', async () => {
+ render(() => <TraceFlow name="view.home">{null}</TraceFlow>);
+ await flush();
+ expect(spans[0].attrs['flow.kind']).toBe('view');
+ beginInteraction('panel.toggle').end();
+ expect(spans[1].attrs['flow.kind']).toBe('interaction');
+ });
+
+ it('starts requests in the flow while it loads and outside it once settled', async () => {
+ const [loading, setLoading] = createSignal(true);
+ let flow: ReturnType<typeof useFlow> | undefined;
+ function Content() {
+ flow = useFlow();
+ usePending('doc.content', loading);
+ return null;
+ }
+ render(() => (
+ <TraceFlow name="view.doc">
+ <Content />
+ </TraceFlow>
+ ));
+ await flush();
+ let parent: string | undefined;
+ flow?.run(() => {
+ parent = contexts.at(-1);
+ });
+ expect(parent).toBe('view.doc');
+
+ setLoading(false);
+ await flush();
+ flow?.run(() => {
+ parent = contexts.at(-1);
+ });
+ expect(parent).toBeUndefined();
+ });
+
+ it('keeps boot open for the view a navigation commits before it mounts', async () => {
+ const boot = beginInteraction('app.boot', {
+ kind: 'boot',
+ closeOnJoin: true,
+ });
+ beginInteraction('navigation', { kind: 'navigation' }).end();
+ render(() => (
+ <TraceFlow name="view.home" attributes={{ 'route.id': 'home' }}>
+ {null}
+ </TraceFlow>
+ ));
+ render(() => <TraceFlow name="view.later">{null}</TraceFlow>);
+ await flush();
+ expect(spans.find((span) => span.name === 'view.home')?.parent).toBe(
+ 'app.boot'
+ );
+ expect(operations.map((operation) => operation.name)).toEqual([
+ 'app.boot',
+ 'view.later',
+ ]);
+ expect(operations[0].outcome).toBe('painted');
+ expect(spans[0].attrs['route.id']).toBe('home');
+ boot.end();
+ });
+
+ it('closes boot when its navigation opens the first view', async () => {
+ beginInteraction('app.boot', { kind: 'boot', closeOnJoin: true });
+ const navigation = beginInteraction('navigation', { kind: 'navigation' });
+ render(() => <TraceFlow name="view.home">{null}</TraceFlow>);
+ navigation.end();
+ render(() => <TraceFlow name="view.later">{null}</TraceFlow>);
+ await flush();
+ expect(spans.find((span) => span.name === 'view.home')?.parent).toBe(
+ 'navigation'
+ );
+ expect(operations.map((operation) => operation.name)).toEqual([
+ 'app.boot',
+ 'view.later',
+ ]);
+ expect(operations[0].outcome).toBe('painted');
+ });
+
+ it('lets the next view join boot when the first one unmounts before loading', async () => {
+ const [redirected, setRedirected] = createSignal(false);
+ beginInteraction('app.boot', { kind: 'boot', closeOnJoin: true });
+ render(() => (
+ <Show
+ when={redirected()}
+ fallback={<TraceFlow name="view.base">{null}</TraceFlow>}
+ >
+ <TraceFlow name="view.home">{null}</TraceFlow>
+ </Show>
+ ));
+ setRedirected(true);
+ await flush();
+ await flush();
+ expect(
+ spans
+ .filter((span) => span.parent === 'app.boot')
+ .map((span) => [span.name, span.attrs['flow.outcome']])
+ ).toEqual([
+ ['view.base', 'cancelled'],
+ ['view.home', 'success'],
+ ]);
+ expect(operations).toEqual([{ name: 'app.boot', outcome: 'painted' }]);
+ });
+});
diff --git a/apps/web/src/observability/flow.tsx b/apps/web/src/observability/flow.tsx
new file mode 100644
index 0000000000..a5db7817d7
--- /dev/null
+++ b/apps/web/src/observability/flow.tsx
@@ -0,0 +1,462 @@
+import {
+ NOOP_SPAN,
+ type Span,
+ type TraceContext,
+} from '@macro-inc/observability';
+import {
+ type Accessor,
+ createContext,
+ createEffect,
+ createSignal,
+ type JSX,
+ on,
+ onCleanup,
+ onMount,
+ untrack,
+ useContext,
+} from 'solid-js';
+import type { SamplingClass } from './sampling';
+import {
+ currentRoute,
+ type FlowKind,
+ setActiveRoute,
+ startUiOperation,
+ type UiOperationOptions,
+} from './ui-operation';
+
+type Attributes = Record<string, string | number | boolean>;
+type Outcome = 'success' | 'cancelled';
+
+/**
+ * What every node of one perf trace shares: the root's name, stamped on each
+ * phase so Datadog can aggregate phases per root without trace queries, and
+ * how many phases it opened versus found already loaded.
+ */
+interface FlowRoot {
+ readonly span: Span;
+ readonly name: string;
+ phaseCount: number;
+ readyPhases: number;
+}
+
+const ROUTE_ID = 'route.id';
+
+/**
+ * One span in a loading flow. It stays open while anything under it holds it
+ * and settles the first time the holds reach zero.
+ */
+interface FlowNode {
+ readonly span: Span;
+ readonly root: FlowRoot;
+ /** The route of the nearest view at or above this node. */
+ readonly route: string | undefined;
+ readonly settled: boolean;
+ /** Keep the node open until the returned release runs. Idempotent. */
+ hold(): () => void;
+ /** Settle now as cancelled, for a view that unmounted while loading. */
+ abandon(): void;
+}
+
+function createNode(
+ span: Span,
+ root: FlowRoot,
+ route: string | undefined,
+ finish: (outcome: Outcome) => void,
+ expired: () => boolean = () => false
+): FlowNode {
+ let count = 0;
+ let settled = false;
+ return {
+ span,
+ root,
+ route,
+ get settled() {
+ return settled || expired();
+ },
+ hold() {
+ if (settled) return () => {};
+ count++;
+ let released = false;
+ return () => {
+ if (released) return;
+ released = true;
+ count--;
+ if (count === 0 && !settled) {
+ settled = true;
+ finish('success');
+ }
+ };
+ },
+ abandon() {
+ if (settled) return;
+ settled = true;
+ finish('cancelled');
+ },
+ };
+}
+
+/** A root node finishes its UI operation one paint after it settles. */
+function rootNode(
+ name: string,
+ kind: FlowKind,
+ options: UiOperationOptions = {}
+): FlowNode {
+ const operation = startUiOperation(name, { ...options, kind });
+ const own = options.attributes?.[ROUTE_ID];
+ if (typeof own === 'string') setActiveRoute(own);
+ // Mirrors startUiOperation: a navigation's route comes from its views.
+ const route =
+ typeof own === 'string'
+ ? own
+ : kind === 'boot' || kind === 'navigation'
+ ? undefined
+ : currentRoute();
+ const root: FlowRoot = {
+ span: operation.span,
+ name,
+ phaseCount: 0,
+ readyPhases: 0,
+ };
+ return createNode(
+ operation.span,
+ root,
+ route,
+ (outcome) => {
+ operation.span.setAttr('flow.phase_count', root.phaseCount);
+ operation.span.setAttr('flow.ready_phase_count', root.readyPhases);
+ if (outcome === 'success') operation.afterPaint();
+ else operation.cancel();
+ },
+ // A timed-out or hidden operation takes no more phases.
+ () => operation.ended
+ );
+}
+
+function childNode(
+ parent: FlowNode,
+ name: string,
+ attributes?: Attributes,
+ onSettle?: (outcome: Outcome) => void
+): FlowNode {
+ const release = parent.hold();
+ const span = parent.span.span(name);
+ const root = parent.root;
+ const own = attributes?.[ROUTE_ID];
+ if (typeof own === 'string') {
+ setActiveRoute(own);
+ // The root is about the most specific view it opened: the last to join,
+ // which for nested routes is the innermost.
+ root.span.setAttr(ROUTE_ID, own);
+ }
+ const route = typeof own === 'string' ? own : parent.route;
+ span.setAttr('flow.root', root.name);
+ if (route !== undefined) span.setAttr(ROUTE_ID, route);
+ for (const [key, value] of Object.entries(attributes ?? {}))
+ span.setAttr(key, value);
+ root.phaseCount++;
+ return createNode(span, root, route, (outcome) => {
+ span.setAttr('flow.outcome', outcome);
+ span.end();
+ onSettle?.(outcome);
+ // Solid disposes children before parents: when the parent is unmounting
+ // too, it must abandon before this release can settle it as a success.
+ if (outcome === 'cancelled') queueMicrotask(release);
+ else release();
+ });
+}
+
+/** The nearest flow; a keyed flow replaces its node when the key changes. */
+interface FlowScope {
+ /** The current node, read without tracking. */
+ readonly node: FlowNode;
+ /** The current node, tracked, for phases that move to a restarted flow. */
+ current: Accessor<FlowNode>;
+}
+
+const FlowContext = createContext<FlowScope>();
+
+interface OpenInteraction {
+ readonly node: FlowNode;
+ readonly closeOnJoin: boolean;
+ /** The interaction that was open when this one began. */
+ readonly enclosing: OpenInteraction | undefined;
+ readonly closed: boolean;
+ close(): void;
+ /** Open the window again, while the interaction itself is still open. */
+ reopen(): void;
+}
+
+let openInteraction: OpenInteraction | undefined;
+
+function activeInteraction(): OpenInteraction | undefined {
+ let open = openInteraction;
+ while (open && (open.closed || open.node.settled)) open = open.enclosing;
+ return open;
+}
+
+export interface Interaction {
+ readonly span: Span;
+ /** Close the window in which new views join this interaction. */
+ end(): void;
+}
+
+export type InteractionOptions = Omit<UiOperationOptions, 'kind'> & {
+ /** `boot` or `navigation` for the app's own roots; defaults to `interaction`. */
+ kind?: Extract<FlowKind, 'boot' | 'navigation' | 'interaction'>;
+ /** Close the window as soon as one flow joins, such as the first view. */
+ closeOnJoin?: boolean;
+};
+
+/**
+ * Start a user interaction, such as a click or a navigation. Every
+ * `<TraceFlow>` created before `end()` that has no open parent joins it, so
+ * one trace runs from the input event until the views it opened have loaded
+ * and painted. Without such a view it ends one paint after `end()`. An
+ * interaction begun while another is open is a phase of that one.
+ */
+export function beginInteraction(
+ name: string,
+ options: InteractionOptions = {}
+): Interaction {
+ const enclosing = activeInteraction();
+ // A nested interaction is not the view a closeOnJoin interaction waits for:
+ // the router's first navigation must leave app.boot open for its view.
+ const node = enclosing
+ ? childNode(enclosing.node, name, options.attributes)
+ : rootNode(name, options.kind ?? 'interaction', options);
+ let release = node.hold();
+ let closed = false;
+ const interaction: OpenInteraction = {
+ node,
+ closeOnJoin: options.closeOnJoin ?? false,
+ enclosing,
+ get closed() {
+ return closed;
+ },
+ close() {
+ if (closed) return;
+ closed = true;
+ if (openInteraction === interaction) openInteraction = enclosing;
+ release();
+ },
+ reopen() {
+ if (!closed || node.settled) return;
+ closed = false;
+ release = node.hold();
+ if (!activeInteraction()) openInteraction = interaction;
+ },
+ };
+ openInteraction = interaction;
+ return { span: node.span, end: interaction.close };
+}
+
+function joinInteraction(
+ interaction: OpenInteraction,
+ name: string,
+ attributes: Attributes | undefined
+): FlowNode {
+ const waiting: OpenInteraction[] = [];
+ for (
+ let open: OpenInteraction | undefined = interaction;
+ open;
+ open = open.enclosing
+ )
+ if (open.closeOnJoin && !open.closed) waiting.push(open);
+ const node = childNode(interaction.node, name, attributes, (outcome) => {
+ // A view that unmounted before loading (a redirect) is not the view they
+ // waited for: the next view joins instead.
+ if (outcome === 'cancelled') for (const open of waiting) open.reopen();
+ });
+ // The first view closes every interaction waiting for one, at any depth.
+ for (const open of waiting) open.close();
+ return node;
+}
+
+/** Joins the nearest open flow, else an open interaction, else starts one. */
+function openNode(
+ parent: FlowScope | undefined,
+ name: string,
+ attributes: Attributes | undefined,
+ sampling: SamplingClass | undefined
+): FlowNode {
+ if (parent && !parent.node.settled)
+ return childNode(parent.node, name, attributes);
+ const interaction = activeInteraction();
+ if (interaction) return joinInteraction(interaction, name, attributes);
+ return rootNode(name, 'view', { attributes, sampling });
+}
+
+/**
+ * Times a view from mount until everything under it has loaded and painted.
+ *
+ * The flow stays open while any nested `<TraceFlow>`, `usePending`, or
+ * `useFlow().task` holds it. Nested flows
+ * become child phases. A flow with no open parent joins the interaction that
+ * opened it (see {@link beginInteraction}) or starts its own trace, of class
+ * `sampling` (`perf` by default).
+ * When `key` changes, such as a view showing a different entity in place, the
+ * flow starts again. Unmounting before it settles records it as cancelled.
+ *
+ * Names and attributes are static categories, ids, and counts; never user
+ * content.
+ */
+export function TraceFlow(props: {
+ name: string;
+ attributes?: Attributes;
+ key?: Accessor<unknown>;
+ /** The sampling class of the trace it starts as a root. Defaults to `perf`. */
+ sampling?: SamplingClass;
+ children: JSX.Element;
+}): JSX.Element {
+ const parent = useContext(FlowContext);
+ const start = () =>
+ openNode(
+ parent,
+ untrack(() => props.name),
+ untrack(() => props.attributes),
+ untrack(() => props.sampling)
+ );
+ const [current, setCurrent] = createSignal(start());
+ const scope: FlowScope = {
+ get node() {
+ return untrack(current);
+ },
+ current,
+ };
+ const releaseMount = scope.node.hold();
+ // Effects of this subtree run in the same flush; let them hold first.
+ onMount(() => queueMicrotask(releaseMount));
+ const key = props.key;
+ if (key)
+ createEffect(
+ on(
+ key,
+ () => {
+ scope.node.abandon();
+ const next = start();
+ setCurrent(next);
+ // Loads the new key starts in this flush hold the node first.
+ queueMicrotask(next.hold());
+ },
+ { defer: true }
+ )
+ );
+ onCleanup(() => scope.node.abandon());
+ return (
+ <FlowContext.Provider value={scope}>{props.children}</FlowContext.Provider>
+ );
+}
+
+/**
+ * Times a loading phase of the enclosing flow: a child span runs while
+ * `pending()` is true and holds the flow open, each time it starts loading
+ * while the flow is open, and moves to a keyed flow that restarts mid-load. If it is already loaded when the flow reaches it (a
+ * cache hit) the flow records a `<name>.ready` event instead.
+ */
+export function usePending(
+ name: string,
+ pending: Accessor<boolean>,
+ attributes?: Attributes
+): void {
+ const scope = useContext(FlowContext);
+ if (!scope) return;
+ let phase: FlowNode | undefined;
+ let release: (() => void) | undefined;
+ let attached = scope.node;
+ const begin = () => {
+ if (phase || scope.node.settled) return;
+ scope.node.span.setAttr(`${name}.waited`, true);
+ phase = childNode(scope.node, name, attributes);
+ release = phase.hold();
+ };
+ const finish = () => {
+ release?.();
+ phase = undefined;
+ release = undefined;
+ };
+ if (untrack(pending)) begin();
+ else if (!scope.node.settled) {
+ // Already loaded when the flow reached it: usually a cache or a load an
+ // earlier view started. `waited` is queryable where the event is not.
+ scope.node.span.event(`${name}.ready`, attributes);
+ scope.node.span.setAttr(`${name}.waited`, false);
+ scope.node.root.readyPhases++;
+ }
+ createEffect(
+ on(
+ [pending, scope.current],
+ ([isPending, node]) => {
+ // A keyed flow restarted while loading: the phase moves to it.
+ if (node !== attached) {
+ attached = node;
+ phase?.abandon();
+ phase = undefined;
+ release = undefined;
+ }
+ if (isPending) begin();
+ else finish();
+ },
+ { defer: true }
+ )
+ );
+ onCleanup(() => phase?.abandon());
+}
+
+export interface Flow {
+ /**
+ * The enclosing flow's span, or a no-op span outside one. Use it for work
+ * that belongs to the load; a settled flow's span has already ended.
+ */
+ readonly span: Span;
+ /** Run async work as a child phase that holds the flow open until done. */
+ task<T>(name: string, operation: (span: Span) => Promise<T>): Promise<T>;
+ /**
+ * Run work in the flow's trace while it is loading, so requests it starts
+ * become the flow's descendants. Once the flow settles, work runs in the
+ * caller's context: a background refresh never joins a finished view.
+ */
+ run<T>(work: () => T): T;
+}
+
+const NO_FLOW: Flow = {
+ span: NOOP_SPAN,
+ task: (_name, operation) => operation(NOOP_SPAN),
+ run: (work) => work(),
+};
+
+/** The enclosing flow, for imperative phases and attributes. */
+export function useFlow(): Flow {
+ const scope = useContext(FlowContext);
+ if (!scope) return NO_FLOW;
+ return {
+ get span() {
+ return scope.node.span;
+ },
+ run: (work) => (scope.node.settled ? work() : scope.node.span.run(work)),
+ task: async (name, operation) => {
+ if (scope.node.settled) return operation(NOOP_SPAN);
+ const phase = childNode(scope.node, name);
+ const release = phase.hold();
+ try {
+ return await phase.span.run(() => operation(phase.span));
+ } catch (error) {
+ phase.span.error(error);
+ throw error;
+ } finally {
+ release();
+ }
+ },
+ };
+}
+
+/**
+ * The nearest flow as a parent for requests a component starts (see
+ * {@link Flow.run}), or undefined outside any flow. Transports that send
+ * later, such as urql's exchange chain, carry it to the send.
+ */
+export function useFlowTrace(): TraceContext | undefined {
+ const scope = useContext(FlowContext);
+ if (!scope) return;
+ const flow = useFlow();
+ return { run: flow.run };
+}
diff --git a/apps/web/src/observability/native-diagnostics.test.ts b/apps/web/src/observability/native-diagnostics.test.ts
index cfa6a457da..2b270002ae 100644
--- a/apps/web/src/observability/native-diagnostics.test.ts
+++ b/apps/web/src/observability/native-diagnostics.test.ts
@@ -182,3 +182,17 @@ it('does not recover an old account after native clearing fails', async () => {
dispose = replacement.startNativeDiagnostics(snapshot);
expect(replacement.recoverableNativeFrontend()).toBeUndefined();
});
+
+it('records idle diagnostic heartbeats twice a minute and visibility immediately', async () => {
+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
+ const diagnostics = await import('./native-diagnostics');
+ dispose = diagnostics.startNativeDiagnostics(snapshot);
+ await vi.advanceTimersByTimeAsync(0);
+ vi.mocked(invoke).mockClear();
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(invoke).toHaveBeenCalledTimes(2);
+ document.dispatchEvent(new Event('visibilitychange'));
+ await vi.advanceTimersByTimeAsync(0);
+ expect(invoke).toHaveBeenCalledTimes(4);
+ vi.restoreAllMocks();
+});
diff --git a/apps/web/src/observability/native-diagnostics.ts b/apps/web/src/observability/native-diagnostics.ts
index 94f49eeaf9..d58f8731c4 100644
--- a/apps/web/src/observability/native-diagnostics.ts
+++ b/apps/web/src/observability/native-diagnostics.ts
@@ -139,10 +139,12 @@ export function startNativeDiagnostics(
window.addEventListener('online', connectivity);
window.addEventListener('offline', connectivity);
heartbeat();
+ // This is a diagnostic breadcrumb, not a liveness lease. Visibility and
+ // connectivity transitions are still recorded immediately.
const timer = setInterval(() => {
// Background timer throttling is expected, not evidence of a hung frontend.
if (document.visibilityState === 'visible') heartbeat();
- }, 5000);
+ }, 30_000);
return () => {
clearInterval(timer);
document.removeEventListener('visibilitychange', visibility);
diff --git a/apps/web/src/observability/os-type.test.ts b/apps/web/src/observability/os-type.test.ts
new file mode 100644
index 0000000000..fd32df9b44
--- /dev/null
+++ b/apps/web/src/observability/os-type.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { osType } from './os-type';
+
+const { native } = vi.hoisted(() => ({
+ native: { tauri: false, os: 'linux' },
+}));
+
+vi.mock('@core/util/platform', () => ({ isTauri: () => native.tauri }));
+vi.mock('@tauri-apps/plugin-os', () => ({ type: () => native.os }));
+
+function browser(userAgent: string, platform?: string) {
+ vi.stubGlobal('navigator', {
+ userAgent,
+ ...(platform !== undefined && { userAgentData: { platform } }),
+ });
+}
+
+describe('osType', () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ native.tauri = false;
+ });
+
+ it('reports the native OS family in the desktop and mobile apps', () => {
+ native.tauri = true;
+ native.os = 'macos';
+ expect(osType()).toBe('darwin');
+ native.os = 'windows';
+ expect(osType()).toBe('windows');
+ native.os = 'ios';
+ expect(osType()).toBe('ios');
+ });
+
+ it('prefers client hints in browsers that send them', () => {
+ browser('Mozilla/5.0 (X11; Linux x86_64)', 'macOS');
+ expect(osType()).toBe('darwin');
+ browser('Mozilla/5.0 (X11; CrOS x86_64)', 'Chrome OS');
+ expect(osType()).toBe('chromeos');
+ });
+
+ it('falls back to the user agent family', () => {
+ browser(
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Version/26.6 Safari/605.1.15'
+ );
+ expect(osType()).toBe('darwin');
+ browser('Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/156.0.0.0');
+ expect(osType()).toBe('windows');
+ browser('Mozilla/5.0 (X11; Linux x86_64) Chrome/156.0.0.0');
+ expect(osType()).toBe('linux');
+ browser('Mozilla/5.0 (Linux; Android 15; Pixel 9) Chrome/156.0.0.0');
+ expect(osType()).toBe('android');
+ browser('Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)');
+ expect(osType()).toBe('ios');
+ browser('', '');
+ expect(osType()).toBe('unknown');
+ });
+});
diff --git a/apps/web/src/observability/os-type.ts b/apps/web/src/observability/os-type.ts
new file mode 100644
index 0000000000..5af5e36af2
--- /dev/null
+++ b/apps/web/src/observability/os-type.ts
@@ -0,0 +1,52 @@
+import { isTauri } from '@core/util/platform';
+import { type as nativeOsType } from '@tauri-apps/plugin-os';
+
+/** OpenTelemetry `os.type` values, plus the mobile and ChromeOS families. */
+export type OsType =
+ | 'darwin'
+ | 'windows'
+ | 'linux'
+ | 'ios'
+ | 'android'
+ | 'chromeos'
+ | 'unknown';
+
+type NavigatorWithUserAgentData = Navigator & {
+ userAgentData?: { platform?: string };
+};
+
+/**
+ * The operating system family only, for splitting performance by OS. Never
+ * record versions, architectures or the user agent string.
+ */
+export function osType(): OsType {
+ if (isTauri()) return fromPlatformName(nativeOsType());
+ if (typeof navigator === 'undefined') return 'unknown';
+ const browser = navigator as NavigatorWithUserAgentData;
+ const fromHints = fromPlatformName(browser.userAgentData?.platform ?? '');
+ if (fromHints !== 'unknown') return fromHints;
+ return fromUserAgent(navigator.userAgent);
+}
+
+function fromPlatformName(platform: string): OsType {
+ const name = platform.toLowerCase();
+ if (name === 'macos' || name === 'mac os x' || name === 'darwin')
+ return 'darwin';
+ if (name === 'windows') return 'windows';
+ if (name === 'linux') return 'linux';
+ if (name === 'ios') return 'ios';
+ if (name === 'android') return 'android';
+ if (name === 'chrome os' || name === 'chromeos') return 'chromeos';
+ return 'unknown';
+}
+
+function fromUserAgent(userAgent: string): OsType {
+ // Order matters: Android user agents also name Linux.
+ if (/iPhone|iPad|iPod/.test(userAgent)) return 'ios';
+ if (/Android/.test(userAgent)) return 'android';
+ if (/CrOS/.test(userAgent)) return 'chromeos';
+ if (/Windows/.test(userAgent)) return 'windows';
+ if (/Macintosh|Mac OS X/.test(userAgent)) return 'darwin';
+ if (/Linux|X11/.test(userAgent)) return 'linux';
+ return 'unknown';
+}
diff --git a/apps/web/src/observability/runtime-resources.test.ts b/apps/web/src/observability/runtime-resources.test.ts
new file mode 100644
index 0000000000..cc9307a614
--- /dev/null
+++ b/apps/web/src/observability/runtime-resources.test.ts
@@ -0,0 +1,208 @@
+import { Telemetry } from '@macro-inc/observability';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import {
+ browserMemoryAttributes,
+ startRuntimeResourceSampling,
+ trackRouteView,
+} from './runtime-resources';
+import { blockingWorkBetween } from './ui-operation';
+
+vi.mock('@macro-inc/observability', () => ({
+ Telemetry: {
+ config: { sampled: vi.fn(() => true) },
+ recordSample: vi.fn(),
+ error: vi.fn(),
+ },
+}));
+vi.mock('./ui-operation', () => ({
+ blockingWorkBetween: vi.fn(() => ({
+ longTaskCount: 2,
+ longTaskMs: 120,
+ longAnimationFrameCount: 1,
+ longAnimationFrameMs: 100,
+ longAnimationFrameBlockingMs: 40,
+ })),
+}));
+let dispose: (() => void) | undefined;
+let releases: (() => void)[] = [];
+function visible(value: boolean) {
+ vi.spyOn(document, 'hidden', 'get').mockReturnValue(!value);
+ document.dispatchEvent(new Event('visibilitychange'));
+}
+beforeEach(() => {
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'performance'] });
+ vi.mocked(Telemetry.recordSample).mockClear();
+ vi.mocked(blockingWorkBetween).mockClear();
+ vi.mocked(Telemetry.config.sampled).mockReturnValue(true);
+ vi.stubGlobal('PerformanceObserver', {
+ supportedEntryTypes: ['longtask', 'long-animation-frame'],
+ });
+ vi.spyOn(document, 'hidden', 'get').mockReturnValue(false);
+ vi.stubGlobal('crossOriginIsolated', false);
+});
+afterEach(() => {
+ dispose?.();
+ dispose = undefined;
+ for (const release of releases) release();
+ releases = [];
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ vi.useRealTimers();
+});
+
+it('installs no work at all in unsampled sessions', async () => {
+ vi.mocked(Telemetry.config.sampled).mockReturnValue(false);
+ const listener = vi.spyOn(document, 'addEventListener');
+ const read = vi.fn();
+ dispose = startRuntimeResourceSampling(read);
+ releases.push(trackRouteView());
+ expect(listener).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ await vi.advanceTimersByTimeAsync(120_000);
+ expect(read).not.toHaveBeenCalled();
+ expect(blockingWorkBetween).not.toHaveBeenCalled();
+ expect(Telemetry.recordSample).not.toHaveBeenCalled();
+});
+it('reports visible windows, live route owners, session age and existing native fields', async () => {
+ releases.push(trackRouteView(), trackRouteView());
+ const read = vi.fn(() => ({
+ 'macro.memory.web_content.footprint_bytes': 1024,
+ }));
+ dispose = startRuntimeResourceSampling(read);
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(blockingWorkBetween).toHaveBeenLastCalledWith(0, 60_000);
+ expect(Telemetry.recordSample).toHaveBeenLastCalledWith(
+ 'app.runtime.sample',
+ expect.objectContaining({
+ 'runtime.window_ms': 60_000,
+ 'runtime.session_age_ms': 60_000,
+ 'runtime.route_views.count': 2,
+ 'runtime.long_task.ms': 120,
+ 'runtime.long_animation_frame.blocking_ms': 40,
+ 'macro.memory.web_content.footprint_bytes': 1024,
+ }),
+ performance.timeOrigin + 60_000,
+ 'perf'
+ );
+ releases[0]();
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(Telemetry.recordSample).toHaveBeenLastCalledWith(
+ 'app.runtime.sample',
+ expect.objectContaining({
+ 'runtime.route_views.count': 1,
+ 'runtime.session_age_ms': 120_000,
+ }),
+ expect.any(Number),
+ 'perf'
+ );
+ expect(read).toHaveBeenCalledTimes(2);
+});
+it('does no work hidden and starts a fresh visible window on return', async () => {
+ dispose = startRuntimeResourceSampling();
+ await vi.advanceTimersByTimeAsync(30_000);
+ visible(false);
+ expect(vi.getTimerCount()).toBe(0);
+ await vi.advanceTimersByTimeAsync(120_000);
+ expect(blockingWorkBetween).not.toHaveBeenCalled();
+ visible(true);
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(blockingWorkBetween).toHaveBeenLastCalledWith(150_000, 210_000);
+});
+it('does not publish a stale asynchronous memory read after hide and resume', async () => {
+ let finish!: (value: Record<string, number>) => void;
+ const read = vi.fn(
+ () =>
+ new Promise<Record<string, number>>((resolve) => {
+ finish = resolve;
+ })
+ );
+ dispose = startRuntimeResourceSampling(read);
+ await vi.advanceTimersByTimeAsync(60_000);
+ visible(false);
+ visible(true);
+ finish({ 'macro.memory.web_content.footprint_bytes': 1 });
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(Telemetry.recordSample).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(1);
+});
+it('stops timers and ignores pending reads after disposal', async () => {
+ let finish!: (value: Record<string, number>) => void;
+ dispose = startRuntimeResourceSampling(
+ () =>
+ new Promise((resolve) => {
+ finish = resolve;
+ })
+ );
+ await vi.advanceTimersByTimeAsync(60_000);
+ dispose();
+ finish({});
+ await Promise.resolve();
+ await Promise.resolve();
+ visible(true);
+ expect(vi.getTimerCount()).toBe(0);
+ expect(Telemetry.recordSample).not.toHaveBeenCalled();
+});
+it('omits unavailable observer totals instead of reporting false zero CPU', async () => {
+ vi.stubGlobal('PerformanceObserver', undefined);
+ dispose = startRuntimeResourceSampling();
+ await vi.advanceTimersByTimeAsync(60_000);
+ const attrs = vi.mocked(Telemetry.recordSample).mock.calls[0][1];
+ expect(attrs['runtime.long_task.supported']).toBe(false);
+ expect(attrs).not.toHaveProperty('runtime.long_task.ms');
+});
+it('reads aggregate memory only when isolated, with an explicit source', async () => {
+ vi.stubGlobal('crossOriginIsolated', true);
+ Object.defineProperty(performance, 'measureUserAgentSpecificMemory', {
+ configurable: true,
+ value: vi.fn(async () => ({ bytes: 2048 })),
+ });
+ expect(await browserMemoryAttributes()).toEqual({
+ 'macro.memory.browser.source': 'user_agent_specific',
+ 'macro.memory.browser.bytes': 2048,
+ });
+});
+it('falls back to Chromium heap when aggregate memory rejects', async () => {
+ vi.stubGlobal('crossOriginIsolated', true);
+ Object.defineProperty(performance, 'measureUserAgentSpecificMemory', {
+ configurable: true,
+ value: vi.fn(async () => {
+ throw new Error('denied');
+ }),
+ });
+ Object.defineProperty(performance, 'memory', {
+ configurable: true,
+ value: { usedJSHeapSize: 10, totalJSHeapSize: 20, jsHeapSizeLimit: 30 },
+ });
+ expect(await browserMemoryAttributes()).toEqual({
+ 'macro.memory.browser.source': 'js_heap',
+ 'macro.memory.js_heap.used_bytes': 10,
+ 'macro.memory.js_heap.total_bytes': 20,
+ 'macro.memory.js_heap.limit_bytes': 30,
+ });
+});
+
+it('pauses a cached page and resumes a fresh visible window', async () => {
+ dispose = startRuntimeResourceSampling();
+ await vi.advanceTimersByTimeAsync(10_000);
+ window.dispatchEvent(
+ new PageTransitionEvent('pagehide', { persisted: true })
+ );
+ expect(vi.getTimerCount()).toBe(0);
+ await vi.advanceTimersByTimeAsync(60_000);
+ window.dispatchEvent(
+ new PageTransitionEvent('pageshow', { persisted: true })
+ );
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(blockingWorkBetween).toHaveBeenLastCalledWith(70_000, 130_000);
+});
+it('does not overlap a hung measurement after a visibility restart', async () => {
+ const read = vi.fn(() => new Promise<Record<string, number>>(() => {}));
+ dispose = startRuntimeResourceSampling(read);
+ await vi.advanceTimersByTimeAsync(60_000);
+ visible(false);
+ visible(true);
+ await vi.advanceTimersByTimeAsync(120_000);
+ expect(read).toHaveBeenCalledTimes(1);
+ expect(vi.getTimerCount()).toBe(1);
+});
diff --git a/apps/web/src/observability/runtime-resources.ts b/apps/web/src/observability/runtime-resources.ts
new file mode 100644
index 0000000000..0a1f334ee4
--- /dev/null
+++ b/apps/web/src/observability/runtime-resources.ts
@@ -0,0 +1,152 @@
+import { fireAndForget } from '@core/util/fireAndForget';
+import { type Attributes, Telemetry } from '@macro-inc/observability';
+import { blockingWorkBetween } from './ui-operation';
+
+// This counts live route component owners, including retained hidden panes,
+// rather than navigation history entries or serialized restoration snapshots.
+const routeViews = new Set<object>();
+export function trackRouteView(): () => void {
+ if (!Telemetry.config.sampled('perf')) return () => {};
+ const view = {};
+ routeViews.add(view);
+ return () => routeViews.delete(view);
+}
+
+type MemoryPerformance = Performance & {
+ measureUserAgentSpecificMemory?: () => Promise<{ bytes: number }>;
+ memory?: {
+ usedJSHeapSize: number;
+ totalJSHeapSize: number;
+ jsHeapSizeLimit: number;
+ };
+};
+
+/** Coverage is explicit: browser aggregate memory and JS heap are different. */
+export async function browserMemoryAttributes(): Promise<Attributes> {
+ const browser: MemoryPerformance = performance;
+ if (
+ globalThis.crossOriginIsolated &&
+ browser.measureUserAgentSpecificMemory
+ ) {
+ try {
+ const memory = await browser.measureUserAgentSpecificMemory();
+ return {
+ 'macro.memory.browser.source': 'user_agent_specific',
+ 'macro.memory.browser.bytes': memory.bytes,
+ };
+ } catch {
+ // The browser can reject the measurement despite exposing the API.
+ }
+ }
+ if (browser.memory)
+ return {
+ 'macro.memory.browser.source': 'js_heap',
+ 'macro.memory.js_heap.used_bytes': browser.memory.usedJSHeapSize,
+ 'macro.memory.js_heap.total_bytes': browser.memory.totalJSHeapSize,
+ 'macro.memory.js_heap.limit_bytes': browser.memory.jsHeapSizeLimit,
+ };
+ return { 'macro.memory.browser.source': 'unavailable' };
+}
+
+/** One visible-tab window per minute; no timer or listeners when unsampled. */
+export function startRuntimeResourceSampling(
+ readNativeMemory?: () => Attributes | Promise<Attributes>
+): () => void {
+ if (!Telemetry.config.sampled('perf')) return () => {};
+ let disposed = false;
+ let pending = false;
+ let generation = 0;
+ let start = performance.now();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+
+ function schedule() {
+ timer = setTimeout(
+ () => fireAndForget(sample(), 'runtime-resources'),
+ 60_000
+ );
+ }
+ async function sample() {
+ if (pending) {
+ schedule();
+ return;
+ }
+ pending = true;
+ const windowGeneration = generation;
+ const end = performance.now();
+ const attributes: Attributes = {
+ 'runtime.window_ms': end - start,
+ 'runtime.session_age_ms': end,
+ 'runtime.route_views.count': routeViews.size,
+ 'runtime.blocking_work.coverage': 'bounded_recent_entries',
+ };
+ const work = blockingWorkBetween(start, end);
+ const supported =
+ typeof PerformanceObserver === 'undefined'
+ ? []
+ : PerformanceObserver.supportedEntryTypes;
+ attributes['runtime.long_task.supported'] = supported.includes('longtask');
+ attributes['runtime.long_animation_frame.supported'] = supported.includes(
+ 'long-animation-frame'
+ );
+ if (supported.includes('longtask')) {
+ attributes['runtime.long_task.count'] = work.longTaskCount;
+ attributes['runtime.long_task.ms'] = work.longTaskMs;
+ }
+ if (supported.includes('long-animation-frame')) {
+ attributes['runtime.long_animation_frame.count'] =
+ work.longAnimationFrameCount;
+ attributes['runtime.long_animation_frame.ms'] = work.longAnimationFrameMs;
+ attributes['runtime.long_animation_frame.blocking_ms'] =
+ work.longAnimationFrameBlockingMs;
+ }
+ const timestamp = performance.timeOrigin + end;
+ start = end;
+ try {
+ const [memory, native] = await Promise.all([
+ browserMemoryAttributes(),
+ readNativeMemory?.(),
+ ]);
+ if (disposed || generation !== windowGeneration || document.hidden)
+ return;
+ Telemetry.recordSample(
+ 'app.runtime.sample',
+ { ...attributes, ...memory, ...native },
+ timestamp,
+ 'perf'
+ );
+ } finally {
+ pending = false;
+ if (!disposed && generation === windowGeneration && !document.hidden)
+ schedule();
+ }
+ }
+ function visibilityChanged() {
+ generation++;
+ clearTimeout(timer);
+ if (!document.hidden) {
+ start = performance.now();
+ schedule();
+ }
+ }
+ function dispose() {
+ disposed = true;
+ generation++;
+ clearTimeout(timer);
+ document.removeEventListener('visibilitychange', visibilityChanged);
+ window.removeEventListener('pagehide', pageHidden);
+ window.removeEventListener('pageshow', pageShown);
+ }
+ function pageHidden(event: PageTransitionEvent) {
+ if (!event.persisted) return dispose();
+ generation++;
+ clearTimeout(timer);
+ }
+ function pageShown(event: PageTransitionEvent) {
+ if (event.persisted) visibilityChanged();
+ }
+ document.addEventListener('visibilitychange', visibilityChanged);
+ window.addEventListener('pagehide', pageHidden);
+ window.addEventListener('pageshow', pageShown);
+ if (!document.hidden) schedule();
+ return dispose;
+}
diff --git a/apps/web/src/observability/sampling.ts b/apps/web/src/observability/sampling.ts
new file mode 100644
index 0000000000..d9eda75244
--- /dev/null
+++ b/apps/web/src/observability/sampling.ts
@@ -0,0 +1,39 @@
+import { Telemetry } from '@macro-inc/observability';
+import { frontendInstanceId } from './frontend-instance';
+
+/**
+ * The web app's sampling classes. `perf` is boot, navigation, view and
+ * interaction timing; `always` is kept for every user, for spans that must
+ * leave a dropped `perf` trace under their own class.
+ */
+export type SamplingClass = 'always' | 'perf';
+
+declare module '@macro-inc/observability' {
+ interface TelemetryRegister {
+ samplingClass: SamplingClass;
+ }
+}
+
+/** Share of production users whose perf traces are exported. */
+const PROD_PERF_RATE = 0.05;
+
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Share of users, 0 to 1, whose traces of each class are exported. */
+export function samplingRates(
+ environment: string
+): Record<SamplingClass, number> {
+ return {
+ always: 1,
+ perf: environment === 'prod' ? PROD_PERF_RATE : 1,
+ };
+}
+
+/**
+ * The user, or this document when no one is signed in yet, salted with the
+ * week so the sampled cohort rotates.
+ */
+export function samplingKey(): string {
+ const identity = Telemetry.config.userId ?? frontendInstanceId;
+ return `${identity}:${Math.floor(Date.now() / WEEK_MS)}`;
+}
diff --git a/apps/web/src/observability/typing-burst.test.ts b/apps/web/src/observability/typing-burst.test.ts
new file mode 100644
index 0000000000..6d65ed49ec
--- /dev/null
+++ b/apps/web/src/observability/typing-burst.test.ts
@@ -0,0 +1,338 @@
+import { NOOP_SPAN, Telemetry } from '@macro-inc/observability';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { startTypingBurstTelemetry } from './typing-burst';
+import { initializeUiOperationTelemetry } from './ui-operation';
+
+vi.mock('@macro-inc/observability', () => {
+ const span = {
+ setAttr: vi.fn(),
+ end: vi.fn(),
+ event: vi.fn(),
+ run: (work: () => unknown) => work(),
+ };
+ return {
+ NOOP_SPAN: span,
+ Telemetry: {
+ config: { sampled: vi.fn(() => true) },
+ span: vi.fn(() => ({ ...span, setAttr: vi.fn(), end: vi.fn() })),
+ },
+ };
+});
+let dispose: (() => void) | undefined;
+let disposeOperations: (() => void) | undefined;
+let input: HTMLTextAreaElement;
+let records: PerformanceEntry[];
+let observerCount: number;
+beforeEach(() => {
+ vi.clearAllMocks();
+ vi.useFakeTimers({
+ toFake: [
+ 'setTimeout',
+ 'clearTimeout',
+ 'requestAnimationFrame',
+ 'cancelAnimationFrame',
+ 'performance',
+ ],
+ });
+ records = [];
+ observerCount = 0;
+ vi.stubGlobal(
+ 'PerformanceObserver',
+ class {
+ static supportedEntryTypes = [
+ 'event',
+ 'longtask',
+ 'long-animation-frame',
+ ];
+ constructor() {
+ observerCount++;
+ }
+ observe() {}
+ takeRecords() {
+ const pending = records;
+ records = [];
+ return pending;
+ }
+ disconnect() {}
+ }
+ );
+ vi.mocked(Telemetry.config.sampled).mockReturnValue(true);
+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
+ input = document.createElement('textarea');
+ input.dataset.inputSurface = 'command-search';
+ document.body.append(input);
+ input.focus();
+ vi.runOnlyPendingTimers();
+ disposeOperations = initializeUiOperationTelemetry();
+});
+afterEach(() => {
+ dispose?.();
+ disposeOperations?.();
+ dispose = undefined;
+ document.body.replaceChildren();
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ vi.useRealTimers();
+});
+function edit(target = input) {
+ const key = new KeyboardEvent('keydown', { key: 'a', bubbles: true });
+ Object.defineProperty(key, 'timeStamp', { value: performance.now() });
+ target.dispatchEvent(key);
+ const event = new InputEvent('beforeinput', {
+ inputType: 'insertText',
+ data: 'private text',
+ bubbles: true,
+ });
+ Object.defineProperty(event, 'timeStamp', { value: performance.now() });
+ target.dispatchEvent(event);
+ return performance.now();
+}
+
+it('installs no listeners or timers in unsampled sessions', () => {
+ vi.mocked(Telemetry.config.sampled).mockReturnValue(false);
+ const listen = vi.spyOn(document, 'addEventListener');
+ dispose = startTypingBurstTelemetry();
+ expect(listen).not.toHaveBeenCalled();
+ expect(vi.getTimerCount()).toBe(0);
+ edit();
+ expect(Telemetry.span).not.toHaveBeenCalled();
+});
+function timing(
+ start: number,
+ id: number,
+ duration = 32,
+ name = 'keydown',
+ delay = 2,
+ processing = 3
+) {
+ const entry = {
+ entryType: 'event',
+ name,
+ startTime: start,
+ duration,
+ processingStart: start + delay,
+ processingEnd: start + delay + processing,
+ interactionId: id,
+ toJSON: () => ({}),
+ };
+ records.push(entry);
+}
+function spanAttributes() {
+ const span = vi.mocked(Telemetry.span).mock.results.at(-1)!.value;
+ return Object.fromEntries(vi.mocked(span.setAttr).mock.calls);
+}
+
+it('reads one content-free cursor window per burst without frame sampling', () => {
+ const frame = vi.spyOn(window, 'requestAnimationFrame');
+ dispose = startTypingBurstTelemetry();
+ for (let i = 0; i < 200; i++) {
+ vi.advanceTimersByTime(20);
+ timing(edit(), i + 1, 16 + i, 'keydown', i % 5, i % 7);
+ }
+ expect(Telemetry.span).toHaveBeenCalledTimes(1);
+ const span = vi.mocked(Telemetry.span).mock.results[0].value;
+ expect(span.end).not.toHaveBeenCalled();
+ vi.advanceTimersByTime(750);
+ expect(span.end).toHaveBeenCalledOnce();
+ expect(spanAttributes()).toMatchObject({
+ 'typing.input_count': 200,
+ 'typing.surface': 'command-search',
+ 'typing.event_timing_supported': true,
+ 'typing.event_timing_threshold_ms': 16,
+ 'typing.event_timing_dropped_timings': 0,
+ 'typing.event_timing_entry_count': 200,
+ 'typing.event_timing_interaction_count': 200,
+ 'typing.event_timing_coverage': 'thresholded_window',
+ 'typing.event_duration_p50_ms': 115,
+ 'typing.event_duration_p95_ms': 205,
+ 'typing.event_input_delay_p95_ms': 4,
+ 'typing.event_processing_p95_ms': 6,
+ });
+ expect(JSON.stringify(vi.mocked(span.setAttr).mock.calls)).not.toContain(
+ 'private text'
+ );
+ expect(frame).not.toHaveBeenCalled();
+ expect(observerCount).toBe(3);
+ expect(vi.getTimerCount()).toBe(0);
+ edit();
+ expect(Telemetry.span).toHaveBeenCalledTimes(2);
+});
+
+it('reports retained interactions and dropped timings when the shared buffer overflows', () => {
+ dispose = startTypingBurstTelemetry();
+ for (let i = 0; i < 1000; i++) {
+ vi.advanceTimersByTime(1);
+ timing(edit(), i + 1);
+ }
+ vi.advanceTimersByTime(750);
+ expect(spanAttributes()).toMatchObject({
+ 'typing.input_count': 1000,
+ 'typing.event_timing_interaction_count': 200,
+ 'typing.event_timing_dropped_timings': 800,
+ 'typing.event_timing_coverage': 'buffer_truncated',
+ });
+ expect(vi.getTimerCount()).toBe(0);
+});
+
+it('does not interpret dropped non-event timings as a missing input count', () => {
+ dispose = startTypingBurstTelemetry();
+ vi.advanceTimersByTime(100);
+ const start = edit();
+ for (let i = 0; i < 201; i++)
+ records.push({
+ entryType: 'longtask',
+ name: '',
+ startTime: start,
+ duration: 50,
+ toJSON: () => ({}),
+ });
+ timing(start, 1);
+ vi.advanceTimersByTime(750);
+ expect(spanAttributes()).toMatchObject({
+ 'typing.input_count': 1,
+ 'typing.event_timing_interaction_count': 1,
+ 'typing.event_timing_dropped_timings': 2,
+ 'typing.event_timing_coverage': 'buffer_truncated',
+ });
+});
+
+it('reads the cursor and cancels the quiet boundary at the shared continuous-burst timeout', () => {
+ dispose = startTypingBurstTelemetry();
+ for (let i = 0; i < 50; i++) {
+ timing(edit(), i + 1);
+ vi.advanceTimersByTime(600);
+ }
+ expect(Telemetry.span).toHaveBeenCalledTimes(1);
+ expect(spanAttributes()).toMatchObject({
+ 'ui.outcome': 'timeout',
+ 'typing.input_count': 50,
+ 'typing.event_timing_interaction_count': 50,
+ 'typing.event_timing_dropped_timings': 0,
+ });
+ expect(
+ vi.mocked(Telemetry.span).mock.results[0].value.end
+ ).toHaveBeenCalledOnce();
+ expect(vi.getTimerCount()).toBe(0);
+});
+
+it('deduplicates keyboard interactions, excludes pointer/other windows and counts unassigned edits', () => {
+ dispose = startTypingBurstTelemetry();
+ vi.advanceTimersByTime(100);
+ const first = edit();
+ timing(first, 1, 48, 'keydown', 4, 10);
+ timing(first + 0.1, 1, 64, 'keypress', 1, 20);
+ timing(first + 20, 1, 32, 'keyup', 2, 1);
+ timing(first + 1, 0, 32, 'beforeinput');
+ timing(first + 2, 0, 32, 'input');
+ timing(first - 10, 9, 999);
+ timing(first + 2000, 10, 999);
+ timing(first + 10, 3, 999, 'click');
+ vi.advanceTimersByTime(40);
+ timing(edit(), 2, 24, 'keydown', 8, 5);
+ vi.advanceTimersByTime(750);
+ expect(spanAttributes()).toMatchObject({
+ 'typing.input_count': 2,
+ 'typing.event_timing_entry_count': 6,
+ 'typing.event_timing_interaction_count': 2,
+ 'typing.event_timing_unattributed_entry_count': 2,
+ 'typing.event_timing_aggregation': 'max_per_interaction',
+ 'typing.event_duration_p50_ms': 24,
+ 'typing.event_duration_p95_ms': 64,
+ 'typing.event_input_delay_p50_ms': 4,
+ 'typing.event_input_delay_p95_ms': 8,
+ 'typing.event_processing_p50_ms': 5,
+ 'typing.event_processing_p95_ms': 20,
+ });
+});
+
+it('does not invent zero-latency samples when supported events are not delivered', () => {
+ dispose = startTypingBurstTelemetry();
+ edit();
+ vi.advanceTimersByTime(750);
+ const attrs = spanAttributes();
+ expect(attrs).toMatchObject({
+ 'typing.event_timing_supported': true,
+ 'typing.event_timing_interaction_count': 0,
+ 'typing.event_timing_coverage': 'thresholded_window',
+ 'typing.event_timing_delivery': 'available_at_finish',
+ });
+ expect(attrs).not.toHaveProperty('typing.event_duration_p95_ms');
+});
+
+it('reports unsupported browsers without percentiles', () => {
+ disposeOperations?.();
+ vi.stubGlobal(
+ 'PerformanceObserver',
+ class {
+ static supportedEntryTypes: string[] = [];
+ }
+ );
+ disposeOperations = initializeUiOperationTelemetry();
+ dispose = startTypingBurstTelemetry();
+ edit();
+ vi.advanceTimersByTime(750);
+ const attrs = spanAttributes();
+ expect(attrs).toMatchObject({
+ 'typing.event_timing_supported': false,
+ 'typing.event_timing_interaction_count': 0,
+ 'typing.event_timing_coverage': 'unsupported',
+ });
+ expect(attrs).not.toHaveProperty('typing.event_duration_p95_ms');
+});
+it('ends on hide and disposal and ignores unmarked or read-only fields', () => {
+ dispose = startTypingBurstTelemetry();
+ input.removeAttribute('data-input-surface');
+ edit();
+ input.dataset.inputSurface = 'command-search';
+ input.readOnly = true;
+ edit();
+ expect(Telemetry.span).not.toHaveBeenCalled();
+ input.readOnly = false;
+ edit();
+ const span = vi.mocked(Telemetry.span).mock.results[0].value;
+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('hidden');
+ document.dispatchEvent(new Event('visibilitychange'));
+ expect(span.setAttr).toHaveBeenCalledWith('ui.outcome', 'hidden');
+ expect(span.end).toHaveBeenCalledOnce();
+ expect(vi.getTimerCount()).toBe(0);
+ edit();
+ expect(Telemetry.span).toHaveBeenCalledTimes(1);
+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
+ edit();
+ const second = vi.mocked(Telemetry.span).mock.results[1].value;
+ dispose();
+ expect(second.end).toHaveBeenCalledOnce();
+ expect(vi.getTimerCount()).toBe(0);
+ expect(NOOP_SPAN.end).not.toHaveBeenCalled();
+});
+it('finishes the previous field before starting another owner', () => {
+ dispose = startTypingBurstTelemetry();
+ edit();
+ const other = document.createElement('textarea');
+ other.dataset.inputSurface = 'grid-cell';
+ document.body.append(other);
+ edit(other);
+ expect(Telemetry.span).toHaveBeenCalledTimes(2);
+ const first = vi.mocked(Telemetry.span).mock.results[0].value;
+ const second = vi.mocked(Telemetry.span).mock.results[1].value;
+ expect(first.end).toHaveBeenCalledOnce();
+ expect(second.end).not.toHaveBeenCalled();
+});
+
+it('drops an unmatched key when its field blurs before the next edit', () => {
+ dispose = startTypingBurstTelemetry();
+ vi.advanceTimersByTime(100);
+ const key = new KeyboardEvent('keydown', { key: 'Enter', bubbles: true });
+ Object.defineProperty(key, 'timeStamp', { value: performance.now() });
+ input.dispatchEvent(key);
+ input.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
+ vi.advanceTimersByTime(100);
+ const paste = new InputEvent('beforeinput', {
+ inputType: 'insertFromPaste',
+ bubbles: true,
+ });
+ Object.defineProperty(paste, 'timeStamp', { value: performance.now() });
+ input.dispatchEvent(paste);
+ const span = vi.mocked(Telemetry.span).mock.results[0].value;
+ expect(span.setAttr).toHaveBeenCalledWith('ui.input_type', 'beforeinput');
+});
diff --git a/apps/web/src/observability/typing-burst.ts b/apps/web/src/observability/typing-burst.ts
new file mode 100644
index 0000000000..329a2e668f
--- /dev/null
+++ b/apps/web/src/observability/typing-burst.ts
@@ -0,0 +1,220 @@
+import { debounce } from '@core/util/debounce';
+import { Telemetry } from '@macro-inc/observability';
+import {
+ eventTimingCursor,
+ readEventTimings,
+ startUiOperation,
+ type UiOperation,
+} from './ui-operation';
+
+const SURFACES = new Set([
+ 'markdown',
+ 'markdown-sync',
+ 'chat',
+ 'plain-text',
+ 'title',
+ 'calendar',
+ 'agent-composer',
+ 'channel-composer',
+ 'command-search',
+ 'grid-cell',
+]);
+const QUIET_MS = 750;
+
+type Burst = {
+ root: HTMLElement;
+ operation: UiOperation;
+ inputs: number;
+ cursor: number;
+ start: number;
+};
+
+/** One sampled owner for edit bursts; no content, per-key spans or idle loop. */
+export function startTypingBurstTelemetry(): () => void {
+ if (!Telemetry.config.sampled('perf')) return () => {};
+ let burst: Burst | undefined;
+ let key: { event: KeyboardEvent; cursor: number } | undefined;
+ const close = debounce(
+ (current: Burst) => current.operation.finish(),
+ QUIET_MS
+ );
+
+ function surface(target: EventTarget | null) {
+ if (!(target instanceof HTMLElement)) return;
+ const root = target.closest<HTMLElement>('[data-input-surface]');
+ const name = root?.dataset.inputSurface;
+ if (!root || !name || !SURFACES.has(name)) return;
+ if (
+ root instanceof HTMLInputElement ||
+ root instanceof HTMLTextAreaElement
+ ) {
+ if (root.disabled || root.readOnly) return;
+ } else if (!root.isContentEditable) return;
+ return { root, name };
+ }
+
+ function finish(current: Burst) {
+ close.clear();
+ if (burst === current) burst = undefined;
+ const result = readEventTimings(current.cursor);
+ const end = performance.now();
+ // Focus ends the burst on field changes. Restrict delayed shared entries
+ // to this window and keyboard/edit events; pointer activity is unrelated.
+ const entries = result.entries.filter(
+ (entry) =>
+ entry.start >= current.start &&
+ entry.start <= end &&
+ ['keydown', 'keypress', 'keyup', 'beforeinput', 'input'].includes(
+ entry.name
+ )
+ );
+ const interactions = new Map<
+ number,
+ { inputDelayMs: number; processingMs: number; durationMs: number }
+ >();
+ let unattributed = 0;
+ for (const entry of entries) {
+ if (!entry.interactionId) {
+ unattributed++;
+ continue;
+ }
+ const previous = interactions.get(entry.interactionId);
+ interactions.set(entry.interactionId, {
+ inputDelayMs: Math.max(previous?.inputDelayMs ?? 0, entry.inputDelayMs),
+ processingMs: Math.max(previous?.processingMs ?? 0, entry.processingMs),
+ durationMs: Math.max(previous?.durationMs ?? 0, entry.durationMs),
+ });
+ }
+ const span = current.operation.span;
+ span.setAttr('typing.input_count', current.inputs);
+ span.setAttr('typing.event_timing_supported', result.supported);
+ span.setAttr('typing.event_timing_threshold_ms', result.thresholdMs);
+ // The cursor counts every timing kind, so this is not a lost-input count.
+ span.setAttr('typing.event_timing_dropped_timings', result.dropped);
+ span.setAttr('typing.event_timing_entry_count', entries.length);
+ span.setAttr('typing.event_timing_interaction_count', interactions.size);
+ span.setAttr('typing.event_timing_unattributed_entry_count', unattributed);
+ span.setAttr('typing.event_timing_aggregation', 'max_per_interaction');
+ span.setAttr('typing.event_timing_delivery', 'available_at_finish');
+ span.setAttr(
+ 'typing.event_timing_coverage',
+ !result.supported
+ ? 'unsupported'
+ : result.dropped > 0
+ ? 'buffer_truncated'
+ : 'thresholded_window'
+ );
+ span.setAttr('typing.quiet_ms', QUIET_MS);
+ const values = [...interactions.values()];
+ for (const [name, field] of [
+ ['input_delay', 'inputDelayMs'],
+ ['processing', 'processingMs'],
+ ['duration', 'durationMs'],
+ ] as const) {
+ const sorted = values.map((entry) => entry[field]).sort((a, b) => a - b);
+ if (!sorted.length) continue;
+ span.setAttr(
+ `typing.event_${name}_p50_ms`,
+ sorted[Math.ceil(sorted.length * 0.5) - 1]
+ );
+ span.setAttr(
+ `typing.event_${name}_p95_ms`,
+ sorted[Math.ceil(sorted.length * 0.95) - 1]
+ );
+ }
+ key = undefined;
+ }
+
+ const keydown = (event: KeyboardEvent) => {
+ const edits =
+ event.key.length === 1 ||
+ ['Backspace', 'Delete', 'Enter'].includes(event.key);
+ key =
+ edits &&
+ !event.ctrlKey &&
+ !event.metaKey &&
+ !event.altKey &&
+ surface(event.target)
+ ? { event, cursor: burst?.cursor ?? eventTimingCursor() }
+ : undefined;
+ };
+ const input = (event: InputEvent) => {
+ if (document.visibilityState !== 'visible') return;
+ const target = surface(event.target);
+ if (
+ key &&
+ (event.timeStamp < key.event.timeStamp ||
+ event.timeStamp - key.event.timeStamp > 1000)
+ )
+ key = undefined;
+ if (!target) return;
+ if (burst && burst.root !== target.root) burst.operation.finish();
+ if (!burst) {
+ const first = key?.event.target === event.target ? key.event : event;
+ const cursor = key?.cursor ?? eventTimingCursor();
+ const relative =
+ first.timeStamp > performance.timeOrigin
+ ? first.timeStamp - performance.timeOrigin
+ : first.timeStamp;
+ const now = performance.now();
+ const start =
+ Number.isFinite(relative) && relative >= 0 && relative <= now
+ ? relative
+ : now;
+ // onFinish also runs on hide, disposal and the shared operation timeout.
+ let created: Burst | undefined;
+ const operation = startUiOperation('input.typing_burst', {
+ event: first,
+ attributes: { 'typing.surface': target.name },
+ onFinish: () => {
+ if (created) finish(created);
+ },
+ });
+ if (operation.ended) return;
+ created = {
+ root: target.root,
+ operation,
+ inputs: 0,
+ cursor,
+ start,
+ };
+ burst = created;
+ }
+ const current = burst;
+ key = undefined;
+ current.inputs++;
+ close(current);
+ };
+ const clearKey = () => {
+ key = undefined;
+ };
+ const focusout = (event: FocusEvent) => {
+ if (key?.event.target === event.target) clearKey();
+ if (
+ burst &&
+ event.target instanceof Node &&
+ burst.root.contains(event.target) &&
+ !(
+ event.relatedTarget instanceof Node &&
+ burst.root.contains(event.relatedTarget)
+ )
+ )
+ burst.operation.finish();
+ };
+ document.addEventListener('keydown', keydown, true);
+ document.addEventListener('keyup', clearKey, true);
+ document.addEventListener('visibilitychange', clearKey);
+ window.addEventListener('pagehide', clearKey);
+ document.addEventListener('beforeinput', input, true);
+ document.addEventListener('focusout', focusout, true);
+ return () => {
+ burst?.operation.cancel();
+ key = undefined;
+ document.removeEventListener('keydown', keydown, true);
+ document.removeEventListener('keyup', clearKey, true);
+ document.removeEventListener('visibilitychange', clearKey);
+ window.removeEventListener('pagehide', clearKey);
+ document.removeEventListener('beforeinput', input, true);
+ document.removeEventListener('focusout', focusout, true);
+ };
+}
diff --git a/apps/web/src/observability/ui-operation.test.ts b/apps/web/src/observability/ui-operation.test.ts
index d4515dc8ba..869430a64b 100644
--- a/apps/web/src/observability/ui-operation.test.ts
+++ b/apps/web/src/observability/ui-operation.test.ts
@@ -1,6 +1,9 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import {
+ eventTimingCursor,
initializeUiOperationTelemetry,
+ readEventTimings,
+ setActiveRoute,
startUiOperation,
} from './ui-operation';
@@ -13,6 +16,7 @@ const { spans } = vi.hoisted(() => ({
}[],
}));
vi.mock('@macro-inc/observability', () => ({
+ NOOP_SPAN: {},
Telemetry: {
span: (name: string) => {
const record = {
@@ -145,6 +149,32 @@ describe('UI operation timing', () => {
expect(spans[0].ends).toBe(1);
});
+ it('tags each root with its kind and, except navigations, the current route', () => {
+ setActiveRoute('channel');
+ startUiOperation('database.cell.commit').cancel();
+ startUiOperation('navigation', { kind: 'navigation' }).cancel();
+ startUiOperation('view.email', {
+ kind: 'view',
+ attributes: { 'route.id': 'email' },
+ }).cancel();
+ expect(spans.map((span) => span.attrs['flow.kind'])).toEqual([
+ 'interaction',
+ 'navigation',
+ 'view',
+ ]);
+ expect(spans.map((span) => span.attrs['route.id'])).toEqual([
+ 'channel',
+ undefined,
+ 'email',
+ ]);
+ expect(spans[0].attrs).toMatchObject({
+ 'ui.outcome': 'cancelled',
+ 'ui.long_task_count': 0,
+ 'ui.long_animation_frame_count': 0,
+ });
+ expect(spans[0].attrs['ui.elapsed_ms']).toEqual(expect.any(Number));
+ });
+
it('ends hidden operations and cancels frames without claiming a paint', () => {
const operation = startUiOperation('database.cell.editor.open');
operation.afterPaint();
@@ -178,6 +208,49 @@ describe('UI operation timing', () => {
expect(spans[1].attrs['ui.event_to_handler_ms']).toBeUndefined();
});
+ it('reads event timings after a cursor and reports what the bounded buffer dropped', () => {
+ const keydown = (start: number) =>
+ ({
+ entryType: 'event',
+ name: 'keydown',
+ startTime: start,
+ duration: 40,
+ processingStart: start + 5,
+ processingEnd: start + 25,
+ interactionId: start,
+ }) as unknown as PerformanceEntry;
+ records.push(keydown(1));
+ const cursor = eventTimingCursor();
+ records.push(keydown(10), {
+ entryType: 'longtask',
+ name: 'self',
+ startTime: 12,
+ duration: 80,
+ } as PerformanceEntry);
+ const read = readEventTimings(cursor);
+ expect(read).toMatchObject({
+ dropped: 0,
+ supported: true,
+ thresholdMs: 16,
+ });
+ expect(read.entries).toEqual([
+ {
+ name: 'keydown',
+ start: 10,
+ inputDelayMs: 5,
+ processingMs: 20,
+ durationMs: 40,
+ interactionId: 10,
+ },
+ ]);
+
+ for (let start = 100; start < 400; start++) records.push(keydown(start));
+ const late = readEventTimings(read.cursor);
+ expect(late.dropped).toBe(100);
+ expect(late.entries).toHaveLength(200);
+ expect(readEventTimings(late.cursor).entries).toEqual([]);
+ });
+
it('cleans up observers once and works without PerformanceObserver support', () => {
expect(initializeUiOperationTelemetry()).toBe(cleanup);
startUiOperation('database.cell.editor.open');
diff --git a/apps/web/src/observability/ui-operation.ts b/apps/web/src/observability/ui-operation.ts
index 0fade92cee..dc10d0b399 100644
--- a/apps/web/src/observability/ui-operation.ts
+++ b/apps/web/src/observability/ui-operation.ts
@@ -1,9 +1,55 @@
-import { Telemetry } from '@macro-inc/observability';
+import { NOOP_SPAN, type Span, Telemetry } from '@macro-inc/observability';
+import type { SamplingClass } from './sampling';
-type Outcome = 'success' | 'error' | 'cancelled' | 'timeout' | 'hidden';
+export type UiOperationOutcome =
+ | 'success'
+ | 'error'
+ | 'cancelled'
+ | 'timeout'
+ | 'hidden';
+type Outcome = UiOperationOutcome;
type Attributes = Record<string, string | number | boolean>;
+/**
+ * What a perf root measures, recorded as `flow.kind` so dashboards can rank
+ * each kind separately. `boot` and `navigation` take their `route.id` from the
+ * first view that joins them, not from the route they started on.
+ */
+export type FlowKind = 'boot' | 'navigation' | 'view' | 'interaction';
+
+let activeRoute: string | undefined;
+
+/** Record the route of the view that opened most recently, for later roots. */
+export function setActiveRoute(route: string): void {
+ activeRoute = route;
+}
+
+/** The route of the view that opened most recently. */
+export function currentRoute(): string | undefined {
+ return activeRoute;
+}
+
+export interface UiOperationOptions {
+ /** Defaults to `interaction`. */
+ kind?: FlowKind;
+ event?: Event;
+ attributes?: Attributes;
+ /**
+ * When it started, in `performance.now()` time, for an operation that began
+ * before code could observe it (0 is the page's navigation start).
+ */
+ startTime?: number;
+ /** Add final attributes or child spans before the span ends. */
+ onFinish?: (span: Span, outcome: Outcome, end: number) => void;
+ /** The sampling class of the trace it starts. Defaults to `perf`. */
+ sampling?: SamplingClass;
+}
+
export interface UiOperation {
+ /** The operation's root span, for child phases. */
+ readonly span: Span;
+ /** Whether it has finished, including by timeout or hiding the page. */
+ readonly ended: boolean;
/** Runs application work in this operation's trace context. */
run<T>(work: () => T): T;
/** Static phase names only; never include user content. */
@@ -15,6 +61,8 @@ export interface UiOperation {
}
type Timing = {
+ /** Position in everything collected so far; survives buffer trimming. */
+ sequence: number;
kind: string;
start: number;
duration: number;
@@ -22,12 +70,16 @@ type Timing = {
processingStart?: number;
processingEnd?: number;
blockingDuration?: number;
+ interactionId?: number;
};
const MAX_ENTRIES = 200;
const MAX_OPERATIONS = 32;
const TIMEOUT_MS = 30_000;
const timings: Timing[] = [];
+let collected = 0;
+// Event Timing only reports events at or above this duration.
+const EVENT_TIMING_THRESHOLD_MS = 16;
const active = new Set<UiOperation>();
let observers: PerformanceObserver[] = [];
let supported: string[] = [];
@@ -39,8 +91,10 @@ function collect(entries: PerformanceEntry[]) {
processingStart?: number;
processingEnd?: number;
blockingDuration?: number;
+ interactionId?: number;
};
timings.push({
+ sequence: collected++,
kind: entry.entryType,
start: entry.startTime,
duration: entry.duration,
@@ -49,12 +103,124 @@ function collect(entries: PerformanceEntry[]) {
processingStart: timing.processingStart,
processingEnd: timing.processingEnd,
blockingDuration: timing.blockingDuration,
+ interactionId: timing.interactionId,
});
}
if (timings.length > MAX_ENTRIES)
timings.splice(0, timings.length - MAX_ENTRIES);
}
+export interface BlockingWork {
+ longTaskCount: number;
+ /** Long-task time inside the window. */
+ longTaskMs: number;
+ longAnimationFrameCount: number;
+ /** Long-animation-frame time inside the window. */
+ longAnimationFrameMs: number;
+ /** Blocking time the browser attributed to those frames. */
+ longAnimationFrameBlockingMs: number;
+}
+
+function measureBlockingWork(
+ start: number,
+ end: number,
+ entries: readonly Timing[]
+): BlockingWork {
+ const inWindow = (entry: Timing) =>
+ Math.max(
+ 0,
+ Math.min(end, entry.start + entry.duration) - Math.max(start, entry.start)
+ );
+ const work: BlockingWork = {
+ longTaskCount: 0,
+ longTaskMs: 0,
+ longAnimationFrameCount: 0,
+ longAnimationFrameMs: 0,
+ longAnimationFrameBlockingMs: 0,
+ };
+ for (const entry of entries) {
+ if (entry.start >= end || entry.start + entry.duration <= start) continue;
+ if (entry.kind === 'longtask') {
+ work.longTaskCount++;
+ work.longTaskMs += inWindow(entry);
+ } else if (entry.kind === 'long-animation-frame') {
+ work.longAnimationFrameCount++;
+ work.longAnimationFrameMs += inWindow(entry);
+ work.longAnimationFrameBlockingMs += entry.blockingDuration ?? 0;
+ }
+ }
+ return work;
+}
+
+/**
+ * Long tasks and long animation frames between `start` and `end`
+ * (`performance.now()` time) from the app's shared observer, for samplers
+ * that must not install their own. The observer keeps a bounded recent
+ * buffer, so windows older than the last few hundred entries undercount.
+ */
+export function blockingWorkBetween(start: number, end: number): BlockingWork {
+ for (const observer of observers) collect(observer.takeRecords());
+ return measureBlockingWork(start, end, timings);
+}
+
+export interface EventTimingEntry {
+ /** Browser event type, such as `keydown`; never targets or content. */
+ name: string;
+ start: number;
+ inputDelayMs: number;
+ processingMs: number;
+ durationMs: number;
+ interactionId: number | undefined;
+}
+
+export interface EventTimingRead {
+ entries: EventTimingEntry[];
+ /** Pass to the next read to continue after these entries. */
+ cursor: number;
+ /** Buffered timings (of any kind) discarded before this read reached them. */
+ dropped: number;
+ supported: boolean;
+ /** Events shorter than this are never reported by the browser. */
+ thresholdMs: number;
+}
+
+/** A cursor at the end of the shared buffer, to read only later events. */
+export function eventTimingCursor(): number {
+ for (const observer of observers) collect(observer.takeRecords());
+ return collected;
+}
+
+/**
+ * Event Timing entries collected since `cursor` by the app's shared observer,
+ * for owners that summarize interactions (counts, percentiles) without their
+ * own observer or per-event spans. Read often enough to keep `dropped` at 0.
+ */
+export function readEventTimings(cursor: number): EventTimingRead {
+ for (const observer of observers) collect(observer.takeRecords());
+ const oldest = timings[0]?.sequence ?? collected;
+ const entries: EventTimingEntry[] = [];
+ for (const timing of timings) {
+ if (timing.sequence < cursor || timing.kind !== 'event') continue;
+ entries.push({
+ name: timing.name,
+ start: timing.start,
+ inputDelayMs: (timing.processingStart ?? timing.start) - timing.start,
+ processingMs:
+ (timing.processingEnd ?? timing.start) -
+ (timing.processingStart ?? timing.start),
+ durationMs: timing.duration,
+ interactionId: timing.interactionId,
+ });
+ }
+ return {
+ entries,
+ cursor: collected,
+ dropped: Math.max(0, oldest - cursor),
+ supported: supported.includes('event'),
+ thresholdMs: EVENT_TIMING_THRESHOLD_MS,
+ };
+}
+
/** One bounded observer per supported entry type for the whole application. */
export function initializeUiOperationTelemetry(): () => void {
if (disposeObservers) return disposeObservers;
@@ -69,7 +235,9 @@ export function initializeUiOperationTelemetry(): () => void {
observer.observe({
type,
buffered: true,
- ...(type === 'event' ? { durationThreshold: 16 } : {}),
+ ...(type === 'event'
+ ? { durationThreshold: EVENT_TIMING_THRESHOLD_MS }
+ : {}),
});
observers.push(observer);
supported.push(type);
@@ -116,6 +284,8 @@ function inputTime(event: Event | undefined, now: number): number | undefined {
}
const noop: UiOperation = {
+ span: NOOP_SPAN,
+ ended: true,
run: (work) => work(),
mark: () => {},
finish: () => {},
@@ -131,7 +301,7 @@ const noop: UiOperation = {
*/
export function startUiOperation(
name: string,
- options: { event?: Event; attributes?: Attributes } = {}
+ options: UiOperationOptions = {}
): UiOperation {
if (
typeof window === 'undefined' ||
@@ -139,11 +309,22 @@ export function startUiOperation(
active.size >= MAX_OPERATIONS
)
return noop;
- const started = performance.now();
+ const started = options.startTime ?? performance.now();
const input = inputTime(options.event, started);
const eventType = options.event?.type;
- const span = Telemetry.span(name);
+ const span = Telemetry.span(name, {
+ sampling: options.sampling ?? 'perf',
+ startTime:
+ options.startTime === undefined
+ ? undefined
+ : performance.timeOrigin + options.startTime,
+ });
+ const kind = options.kind ?? 'interaction';
span.setAttr('ui.operation', name);
+ span.setAttr('flow.kind', kind);
+ // A navigation's route is the view it opens, which joins it later.
+ if (kind !== 'boot' && kind !== 'navigation' && activeRoute !== undefined)
+ span.setAttr('route.id', activeRoute);
span.setAttr('ui.visibility', document.visibilityState);
span.setAttr('ui.performance_entry_types', supported.join(','));
for (const [key, value] of Object.entries(options.attributes ?? {}))
@@ -170,33 +351,18 @@ export function startUiOperation(
(entry) =>
entry.start < end && entry.start + entry.duration > (input ?? started)
);
- for (const kind of ['longtask', 'long-animation-frame']) {
- const entries = overlap.filter((entry) => entry.kind === kind);
- const prefix =
- kind === 'longtask' ? 'ui.long_task' : 'ui.long_animation_frame';
- span.setAttr(`${prefix}_count`, entries.length);
- span.setAttr(
- `${prefix}_overlap_ms`,
- entries.reduce(
- (total, entry) =>
- total +
- Math.max(
- 0,
- Math.min(end, entry.start + entry.duration) -
- Math.max(input ?? started, entry.start)
- ),
- 0
- )
- );
- if (kind === 'long-animation-frame')
- span.setAttr(
- 'ui.long_animation_frame_blocking_ms',
- entries.reduce(
- (total, entry) => total + (entry.blockingDuration ?? 0),
- 0
- )
- );
- }
+ const work = measureBlockingWork(input ?? started, end, overlap);
+ span.setAttr('ui.long_task_count', work.longTaskCount);
+ span.setAttr('ui.long_task_overlap_ms', work.longTaskMs);
+ span.setAttr('ui.long_animation_frame_count', work.longAnimationFrameCount);
+ span.setAttr(
+ 'ui.long_animation_frame_overlap_ms',
+ work.longAnimationFrameMs
+ );
+ span.setAttr(
+ 'ui.long_animation_frame_blocking_ms',
+ work.longAnimationFrameBlockingMs
+ );
const event =
input === undefined
? undefined
@@ -232,10 +398,15 @@ export function startUiOperation(
if (input !== undefined)
span.setAttr('ui.input_to_paint_opportunity_ms', end - input);
}
+ options.onFinish?.(span, outcome, end);
active.delete(operation);
span.end();
}
const operation: UiOperation = {
+ span,
+ get ended() {
+ return ended;
+ },
run: (work) => span.run(work),
mark: (phase) => {
if (!ended)
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
index 05f5e6c973..43b7cc3496 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs
@@ -17,7 +17,7 @@ use crate::engine::{
RollbackOptimisticWriteResultWire, WriteRegistration, WriteRequest, WriteResultWire,
};
use crate::{
- CacheState, InitializedCache, emit_cache_changed, emit_cache_changed_with_search_changes,
+ CacheState, InitializedCache, emit_cache_changed, emit_cache_changed_with_hints,
emit_mutation_settled, emit_ops_affected,
};
use cache_core::calendar::{CalendarCommit, CalendarRangeRequest};
@@ -135,6 +135,12 @@ pub async fn graphql_cache_current_storage_generation(
}
/// Attempts a cache read; registers `op_id` as active when given.
+#[tracing::instrument(
+ name = "graphql_cache.ipc.receive",
+ skip_all,
+ fields(graphql_cache.ipc.command = "read", upstream.trace_id = traceparent.as_deref().and_then(|parent| parent.split('-').nth(1))),
+ err
+)]
#[tauri::command]
pub async fn graphql_cache_read(
state: State<'_, CacheState>,
@@ -143,6 +149,7 @@ pub async fn graphql_cache_read(
operation_name: Option<String>,
variables: Option<Variables>,
entity_resolvers: Option<Vec<EntityResolver>>,
+ traceparent: Option<String>,
) -> Result<ReadResultWire, String> {
engine_handle(&state)?
.read(
@@ -156,6 +163,16 @@ pub async fn graphql_cache_read(
}
/// Incrementally project an ordinary query through cache-core.
+#[tracing::instrument(
+ name = "graphql_cache.ipc.receive",
+ skip_all,
+ fields(graphql_cache.ipc.command = "watch", upstream.trace_id = traceparent.as_deref().and_then(|parent| parent.split('-').nth(1))),
+ err
+)]
+#[expect(
+ clippy::too_many_arguments,
+ reason = "Tauri command fields preserve the existing flat IPC wire contract"
+)]
#[tauri::command]
pub async fn graphql_cache_watch(
state: State<'_, CacheState>,
@@ -165,6 +182,7 @@ pub async fn graphql_cache_watch(
variables: Option<Variables>,
entity_resolvers: Option<Vec<EntityResolver>>,
since: Option<String>,
+ traceparent: Option<String>,
) -> Result<cache_core::engine::watch_query::QueryUpdate, String> {
engine_handle(&state)?
.watch(
@@ -202,13 +220,42 @@ pub async fn graphql_cache_search(
/// Evaluates Soup filters over native projections, including cached Mail pages.
#[tauri::command]
+#[tracing::instrument(
+ name = "graphql_cache.native.entity_filter",
+ skip_all,
+ fields(graphql_cache.ipc.command = "entity_filter", upstream.trace_id = traceparent.as_deref().and_then(|parent| parent.split('-').nth(1))),
+ err
+)]
pub async fn graphql_cache_entity_filter(
state: State<'_, CacheState>,
request: EntityFilterRequest,
+ traceparent: Option<String>,
) -> Result<EntityFilterResult, String> {
engine_handle(&state)?.entity_filter(request).await
}
+/// Reads a registered live view without resending its selection and predicate.
+#[tauri::command]
+#[tracing::instrument(
+ name = "graphql_cache.native.entity_filter_resume",
+ skip_all,
+ fields(graphql_cache.ipc.command = "entity_filter_resume", upstream.trace_id = traceparent.as_deref().and_then(|parent| parent.split('-').nth(1)), graphql_cache.live_query.retained = tracing::field::Empty),
+ err
+)]
+pub async fn graphql_cache_entity_filter_resume(
+ state: State<'_, CacheState>,
+ id: String,
+ registration_id: cache_core::engine::live_query::LiveQueryRegistration,
+ since: Option<String>,
+ traceparent: Option<String>,
+) -> Result<Option<crate::engine::LiveQueryResult>, String> {
+ let update = engine_handle(&state)?
+ .resume_entity_filter(id, registration_id, since)
+ .await?;
+ tracing::Span::current().record("graphql_cache.live_query.retained", update.is_some());
+ Ok(update)
+}
+
/// Answers a calendar viewport from the native range index.
#[tauri::command]
pub async fn graphql_cache_calendar_range(
@@ -227,18 +274,14 @@ pub async fn graphql_cache_calendar_commit<R: Runtime>(
commit: CalendarCommit,
) -> Result<WriteResultWire, String> {
let result = engine_handle(&state)?.calendar_commit(commit).await?;
- emit_ops_affected(
- &app,
- &result.affected_ops,
- &result.changed,
- result.field_changes.as_ref(),
- );
+ emit_ops_affected(&app, &result.affected_ops, result.field_changes.as_ref());
if result.revision_advanced {
- emit_cache_changed_with_search_changes(
+ emit_cache_changed_with_hints(
&app,
&result.revision,
result.reset,
result.search_changed_buckets.as_ref(),
+ result.unchanged_views.as_ref(),
);
}
Ok(result)
@@ -257,6 +300,12 @@ pub struct WriteRegistrationWire {
/// Normalizes and stores a network response; broadcasts affected operations
/// to every webview.
+#[tracing::instrument(
+ name = "graphql_cache.ipc.receive",
+ skip_all,
+ fields(graphql_cache.ipc.command = "write", upstream.trace_id = traceparent.as_deref().and_then(|parent| parent.split('-').nth(1))),
+ err
+)]
#[tauri::command]
pub async fn graphql_cache_write<R: Runtime>(
app: AppHandle<R>,
@@ -268,6 +317,7 @@ pub async fn graphql_cache_write<R: Runtime>(
variables: Option<Variables>,
data: serde_json::Value,
identity: Option<String>,
+ traceparent: Option<String>,
) -> Result<WriteResultWire, String> {
let result = engine_handle(&state)?
.write(WriteRequest {
@@ -283,18 +333,14 @@ pub async fn graphql_cache_write<R: Runtime>(
identity,
})
.await?;
- emit_ops_affected(
- &app,
- &result.affected_ops,
- &result.changed,
- result.field_changes.as_ref(),
- );
+ emit_ops_affected(&app, &result.affected_ops, result.field_changes.as_ref());
if result.revision_advanced {
- emit_cache_changed_with_search_changes(
+ emit_cache_changed_with_hints(
&app,
&result.revision,
result.reset,
result.search_changed_buckets.as_ref(),
+ result.unchanged_views.as_ref(),
);
}
Ok(result)
@@ -306,6 +352,9 @@ pub async fn graphql_cache_write<R: Runtime>(
pub enum HydrationResultWire {
/// At least one non-cache-only field was projected.
Data {
+ /// Windows proven unchanged by the engine.
+ #[serde(rename = "unchangedViews")]
+ unchanged_views: Vec<String>,
/// Quick Access buckets whose searchable or materialized fields changed.
#[serde(rename = "searchChangedBuckets")]
search_changed_buckets: std::collections::BTreeSet<String>,
@@ -319,6 +368,9 @@ pub enum HydrationResultWire {
},
/// Every response field was cache-only.
Void {
+ /// Windows proven unchanged by the engine.
+ #[serde(rename = "unchangedViews")]
+ unchanged_views: Vec<String>,
/// Quick Access buckets whose searchable or materialized fields changed.
#[serde(rename = "searchChangedBuckets")]
search_changed_buckets: std::collections::BTreeSet<String>,
@@ -333,6 +385,16 @@ pub enum HydrationResultWire {
/// Normalizes and stores a background hydration response and returns only
/// fields not marked `@cacheOnly`. Ordinary hydration remains silent to
/// foreground subscribers; identity-changing resets are still broadcast.
+#[tracing::instrument(
+ name = "graphql_cache.ipc.receive",
+ skip_all,
+ fields(graphql_cache.ipc.command = "hydrate", upstream.trace_id = traceparent.as_deref().and_then(|parent| parent.split('-').nth(1))),
+ err
+)]
+#[expect(
+ clippy::too_many_arguments,
+ reason = "Tauri command fields preserve the existing flat IPC wire contract"
+)]
#[tauri::command]
pub async fn graphql_cache_hydrate<R: Runtime>(
app: AppHandle<R>,
@@ -342,6 +404,7 @@ pub async fn graphql_cache_hydrate<R: Runtime>(
variables: Option<Variables>,
data: serde_json::Value,
identity: Option<String>,
+ traceparent: Option<String>,
) -> Result<HydrationResultWire, String> {
let result = engine_handle(&state)?
.hydrate_query(
@@ -353,12 +416,7 @@ pub async fn graphql_cache_hydrate<R: Runtime>(
)
.await?;
if result.write_result.reset {
- emit_ops_affected(
- &app,
- &result.write_result.affected_ops,
- &result.write_result.changed,
- None,
- );
+ emit_ops_affected(&app, &result.write_result.affected_ops, None);
if result.write_result.revision_advanced {
emit_cache_changed(
&app,
@@ -369,12 +427,14 @@ pub async fn graphql_cache_hydrate<R: Runtime>(
}
Ok(match result.data {
Some(data) => HydrationResultWire::Data {
+ unchanged_views: result.unchanged_views,
search_changed_buckets: result.search_changed_buckets,
data,
revision: result.write_result.revision,
revision_advanced: result.write_result.revision_advanced,
},
None => HydrationResultWire::Void {
+ unchanged_views: result.unchanged_views,
search_changed_buckets: result.search_changed_buckets,
revision: result.write_result.revision,
revision_advanced: result.write_result.revision_advanced,
@@ -427,7 +487,6 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(
emit_ops_affected(
&app,
&result.result.affected_ops,
- &result.result.changed,
result.result.field_changes.as_ref(),
);
if result.result.revision_advanced {
@@ -537,7 +596,6 @@ pub async fn graphql_cache_defer_optimistic_write<R: Runtime>(
emit_ops_affected(
&app,
&write_result.affected_ops,
- &write_result.changed,
write_result.field_changes.as_ref(),
);
if write_result.revision_advanced {
@@ -600,7 +658,6 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(
emit_ops_affected(
&app,
&write_result.affected_ops,
- &write_result.changed,
write_result.field_changes.as_ref(),
);
if write_result.revision_advanced {
@@ -646,7 +703,6 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
emit_ops_affected(
&app,
&write_result.affected_ops,
- &write_result.changed,
write_result.field_changes.as_ref(),
);
if write_result.revision_advanced {
@@ -669,7 +725,6 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(
emit_ops_affected(
&app,
&write_result.affected_ops,
- &write_result.changed,
write_result.field_changes.as_ref(),
);
if write_result.revision_advanced {
@@ -697,8 +752,8 @@ pub async fn graphql_cache_invalidate<R: Runtime>(
state: State<'_, CacheState>,
keys: Vec<String>,
) -> Result<AffectedOperationsResultWire, String> {
- let affected = engine_handle(&state)?.invalidate(keys.clone()).await?;
- emit_ops_affected(&app, &affected.affected_ops, &keys, None);
+ let affected = engine_handle(&state)?.invalidate(keys).await?;
+ emit_ops_affected(&app, &affected.affected_ops, None);
emit_cache_changed(&app, &affected.revision, false);
Ok(affected)
}
@@ -711,8 +766,8 @@ pub async fn graphql_cache_delete_records<R: Runtime>(
state: State<'_, CacheState>,
keys: Vec<String>,
) -> Result<AffectedOperationsResultWire, String> {
- let affected = engine_handle(&state)?.delete_records(keys.clone()).await?;
- emit_ops_affected(&app, &affected.affected_ops, &keys, None);
+ let affected = engine_handle(&state)?.delete_records(keys).await?;
+ emit_ops_affected(&app, &affected.affected_ops, None);
emit_cache_changed(&app, &affected.revision, false);
Ok(affected)
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands/test.rs b/apps/web/tauri/graphql_cache_plugin/src/commands/test.rs
index 3a2210be9b..8abb46a277 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/commands/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/commands/test.rs
@@ -5,12 +5,14 @@ fn hydration_results_preserve_the_native_advancement_bit() {
for revision_advanced in [false, true] {
for result in [
HydrationResultWire::Data {
+ unchanged_views: vec!["window".into()],
search_changed_buckets: ["note".into()].into(),
data: serde_json::json!({"cursor": null}),
revision: "7".to_string(),
revision_advanced,
},
HydrationResultWire::Void {
+ unchanged_views: vec!["window".into()],
search_changed_buckets: ["note".into()].into(),
revision: "7".to_string(),
revision_advanced,
@@ -19,6 +21,7 @@ fn hydration_results_preserve_the_native_advancement_bit() {
let json = serde_json::to_value(result).unwrap();
assert_eq!(json["revisionAdvanced"], revision_advanced);
assert_eq!(json["revision"], "7");
+ assert_eq!(json["unchangedViews"], serde_json::json!(["window"]));
assert_eq!(json["searchChangedBuckets"], serde_json::json!(["note"]));
assert!(json.get("revision_advanced").is_none());
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
index 161bcbbe5c..6e2b869ee3 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs
@@ -31,13 +31,15 @@ use cache_turso::{TursoStorage, TursoStorageCloseOutcome};
use serde::Serialize;
use std::collections::HashMap;
use std::sync::Arc;
-use tokio::sync::Mutex;
+mod access;
+use access::EngineAccess;
mod calendar;
mod soup;
pub use calendar::CalendarRangeResultWire;
pub use soup::{
- EntityFilterRequest, EntityFilterResult, PredicateBaselineEntry, PredicateFilterResult,
+ EntityFilterRequest, EntityFilterResult, LiveQueryResult, PredicateBaselineEntry,
+ PredicateFilterResult,
};
/// Mirrors `ReadResult` in `apps/web/src/lib/graphql-cache/protocol.ts`.
@@ -57,6 +59,9 @@ pub enum ReadResultWire {
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WriteResultWire {
+ /// Optional complete displayed-window invalidation proofs.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub unchanged_views: Option<Vec<String>>,
/// Effective scalar patches; absent when a query reread is required.
#[serde(skip_serializing_if = "Option::is_none")]
pub field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
@@ -87,6 +92,8 @@ pub struct WriteResultWire {
/// Internal hydration result used to fan out changes before returning only
/// the caller-visible projection across IPC.
pub struct HydrationWriteResultWire {
+ /// Displayed windows proven unchanged by complete engine journal evidence.
+ pub unchanged_views: Vec<String>,
/// Quick Access buckets changed by hydration.
pub search_changed_buckets: std::collections::BTreeSet<String>,
/// Cache changes required for host notifications.
@@ -389,13 +396,14 @@ struct EngineState {
selections: RecordSelectionCache,
}
-/// Cheaply-clonable handle to the shared engine. All methods serialize
-/// through the async mutex; errors are stringified for the IPC boundary
+/// Cheaply-clonable handle to the shared engine. Foreground methods serialize
+/// through the async mutex. Hydration yields and refetches when superseded.
+/// Errors are stringified for the IPC boundary
/// (the JS host rejects the pending call, and the exchange degrades to the
/// network).
#[derive(Clone)]
pub struct EngineHandle {
- inner: Arc<Mutex<EngineState>>,
+ inner: Arc<EngineAccess<EngineState>>,
// Shared by cloned handles, changed when the native engine is reopened.
// Revisions alone may repeat across process restarts.
mail_generation: String,
@@ -403,6 +411,7 @@ pub struct EngineHandle {
fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {
WriteResultWire {
+ unchanged_views: None,
field_changes: result.field_changes,
identity_errors: result.identity_errors,
revision: result.revision.to_string(),
@@ -452,7 +461,7 @@ impl EngineHandle {
);
EngineHandle {
mail_generation: soup_filter_cache_adapter::mail::new_generation(),
- inner: Arc::new(Mutex::new(EngineState {
+ inner: Arc::new(EngineAccess::new(EngineState {
engine,
ops: OpInterner::default(),
selections: RecordSelectionCache::default(),
@@ -514,6 +523,7 @@ impl EngineHandle {
}
/// Cache read; registers `op_id` as active when given.
+ #[tracing::instrument(name = "graphql_cache.native.read", skip_all, err)]
pub async fn read(
&self,
op_id: Option<String>,
@@ -542,6 +552,7 @@ impl EngineHandle {
}
/// Incrementally project a query; operation teardown releases its bindings.
+ #[tracing::instrument(name = "graphql_cache.native.watch", skip_all, err)]
pub async fn watch(
&self,
op_id: String,
@@ -623,6 +634,27 @@ impl EngineHandle {
.await
}
+ /// Reads a retained live view, atomically checking its specification identity.
+ pub async fn resume_entity_filter(
+ &self,
+ id: String,
+ registration_id: cache_core::engine::live_query::LiveQueryRegistration,
+ since: Option<String>,
+ ) -> Result<Option<soup::LiveQueryResult>, String> {
+ let since = since
+ .map(|revision| revision.parse())
+ .transpose()
+ .map_err(|error: cache_core::revision::ParseCacheRevisionError| error.to_string())?;
+ self.inner
+ .lock()
+ .await
+ .engine
+ .resume_live_query(&id, registration_id, since)
+ .await
+ .map(|update| update.map(|update| soup::LiveQueryResult::LiveQuery { update }))
+ .map_err(|error| error.to_string())
+ }
+
/// Recovers cached query variables without materializing each variant.
pub async fn inspect_query_variants(
&self,
@@ -667,6 +699,7 @@ impl EngineHandle {
}
/// Normalizes and stores a network response.
+ #[tracing::instrument(name = "graphql_cache.native.write", skip_all, err)]
pub async fn write(&self, request: WriteRequest) -> Result<WriteResultWire, String> {
let WriteRequest {
origin_op_id,
@@ -677,7 +710,7 @@ impl EngineHandle {
data,
identity,
} = request;
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let origin = origin_op_id.map(|name| ops.intern(&name));
let registration = registration.map(|registration| {
@@ -718,6 +751,7 @@ impl EngineHandle {
/// Stores a query response and returns only fields not marked
/// `@cacheOnly`.
+ #[tracing::instrument(name = "graphql_cache.native.hydrate_query", skip_all, err)]
pub async fn hydrate_query(
&self,
query: String,
@@ -726,7 +760,7 @@ impl EngineHandle {
data: serde_json::Value,
identity: Option<String>,
) -> Result<HydrationWriteResultWire, String> {
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.hydrate().await?;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::write_projections(
engine,
@@ -737,7 +771,7 @@ impl EngineHandle {
identity.as_deref(),
)
.await?;
- engine
+ let result = engine
.hydrate_query_with_projections(
&query,
operation_name.as_deref(),
@@ -747,12 +781,18 @@ impl EngineHandle {
projections,
)
.await
- .map(|result| HydrationWriteResultWire {
- search_changed_buckets: result.search_changed_buckets,
- write_result: wire_write_result(ops, result.write_result),
- data: result.data,
- })
- .map_err(|error| error.to_string())
+ .map_err(|error| error.to_string())?;
+ // Invalidation evidence is optional: a failed proof must not reject a committed hydration.
+ let unchanged_views = engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap_or_default();
+ Ok(HydrationWriteResultWire {
+ unchanged_views,
+ search_changed_buckets: result.search_changed_buckets,
+ write_result: wire_write_result(ops, result.write_result),
+ data: result.data,
+ })
}
/// Durably queues a mutation and its optimistic layer, then attempts to
@@ -776,7 +816,7 @@ impl EngineHandle {
client_metadata: Option<serde_json::Value>,
uncertain_calendar_event_keys: Vec<String>,
) -> Result<EnqueueOptimisticMutationResultWire, String> {
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let origin = origin_op_id.map(|name| ops.intern(&name));
let projections = soup::optimistic_projections(
@@ -920,7 +960,7 @@ impl EngineHandle {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::write_projections(
engine,
@@ -979,7 +1019,7 @@ impl EngineHandle {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
match engine
.rollback_optimistic_write_with_outcome(transaction, claim)
@@ -1005,7 +1045,7 @@ impl EngineHandle {
&self,
keys: Vec<String>,
) -> Result<AffectedOperationsResultWire, String> {
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::invalidation_projections(engine, &keys).await?;
let keys: Vec<EntityKey<'static>> =
@@ -1026,7 +1066,7 @@ impl EngineHandle {
&self,
keys: Vec<String>,
) -> Result<AffectedOperationsResultWire, String> {
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let projections = soup::deletion_projections(engine, &keys).await?;
let keys: Vec<EntityKey<'static>> =
@@ -1053,7 +1093,7 @@ impl EngineHandle {
/// Drops all cached state (logout).
pub async fn clear(&self) -> Result<CacheRevision, String> {
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
state.engine.clear().await.map_err(|e| e.to_string())
}
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/access.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/access.rs
new file mode 100644
index 0000000000..cb87320dbd
--- /dev/null
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/access.rs
@@ -0,0 +1,177 @@
+//! Foreground commands retain FIFO order; cache warming never reserves a turn
+//! ahead of them. Superseded warming must be fetched again, not replayed after
+//! the authoritative write that overtook it.
+use std::ops::{Deref, DerefMut};
+use std::sync::atomic::{AtomicU64, Ordering};
+use tokio::sync::{Mutex, MutexGuard, Notify};
+
+pub(super) struct EngineAccess<T> {
+ value: Mutex<T>,
+ available: Notify,
+ write_epoch: AtomicU64,
+}
+
+impl<T> EngineAccess<T> {
+ pub(super) fn new(value: T) -> Self {
+ Self {
+ value: Mutex::new(value),
+ available: Notify::new(),
+ write_epoch: AtomicU64::new(0),
+ }
+ }
+
+ pub(super) fn into_inner(self) -> T {
+ self.value.into_inner()
+ }
+
+ #[tracing::instrument(name = "graphql_cache.native.lock", skip_all, fields(graphql_cache.lock.kind = "foreground", graphql_cache.lock.wait_ms = tracing::field::Empty))]
+ pub(super) async fn lock(&self) -> AccessGuard<'_, T> {
+ let _wait = AcquisitionWait::new();
+ AccessGuard {
+ value: self.value.lock().await,
+ _release: ReleaseNotice(&self.available),
+ }
+ }
+
+ pub(super) async fn write(&self) -> AccessGuard<'_, T> {
+ self.write_epoch.fetch_add(1, Ordering::SeqCst);
+ self.lock().await
+ }
+
+ #[tracing::instrument(name = "graphql_cache.native.lock", skip_all, fields(graphql_cache.lock.kind = "hydrate", graphql_cache.lock.wait_ms = tracing::field::Empty), err)]
+ pub(super) async fn hydrate(&self) -> Result<AccessGuard<'_, T>, String> {
+ let epoch = self.write_epoch.load(Ordering::SeqCst);
+ let _wait = AcquisitionWait::new();
+ loop {
+ // Register before trying the lock so a release cannot be lost.
+ let notified = self.available.notified();
+ tokio::pin!(notified);
+ notified.as_mut().enable();
+ if epoch != self.write_epoch.load(Ordering::SeqCst) {
+ return Err(
+ "cache hydration superseded by a foreground write; refetch the page".into(),
+ );
+ }
+ if let Ok(value) = self.value.try_lock() {
+ let guard = AccessGuard {
+ value,
+ _release: ReleaseNotice(&self.available),
+ };
+ if epoch != self.write_epoch.load(Ordering::SeqCst) {
+ return Err(
+ "cache hydration superseded by a foreground write; refetch the page".into(),
+ );
+ }
+ return Ok(guard);
+ }
+ notified.await;
+ }
+ }
+}
+
+// Record queue time on every exit, including supersession and cancellation.
+// The returned AccessGuard outlives this timer, so lock hold time is excluded.
+struct AcquisitionWait {
+ span: tracing::Span,
+ started: std::time::Instant,
+}
+impl AcquisitionWait {
+ fn new() -> Self {
+ Self {
+ span: tracing::Span::current(),
+ started: std::time::Instant::now(),
+ }
+ }
+}
+impl Drop for AcquisitionWait {
+ fn drop(&mut self) {
+ self.span.record(
+ "graphql_cache.lock.wait_ms",
+ self.started.elapsed().as_secs_f64() * 1_000.0,
+ );
+ }
+}
+
+pub(super) struct AccessGuard<'a, T> {
+ value: MutexGuard<'a, T>,
+ _release: ReleaseNotice<'a>,
+}
+
+impl<T> Deref for AccessGuard<'_, T> {
+ type Target = T;
+ fn deref(&self) -> &T {
+ &self.value
+ }
+}
+impl<T> DerefMut for AccessGuard<'_, T> {
+ fn deref_mut(&mut self) -> &mut T {
+ &mut self.value
+ }
+}
+// Struct fields drop in declaration order: unlock before waking waiters.
+struct ReleaseNotice<'a>(&'a Notify);
+impl Drop for ReleaseNotice<'_> {
+ fn drop(&mut self) {
+ self.0.notify_waiters();
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use std::future::{Future, poll_fn};
+ use std::task::Poll;
+
+ #[test]
+ fn foreground_overtakes_warming_and_supersedes_its_snapshot() {
+ pollster::block_on(async {
+ let access = EngineAccess::new("initial");
+ let blocker = access.lock().await;
+ let mut hydration = std::pin::pin!(access.hydrate());
+ let mut second_hydration = std::pin::pin!(access.hydrate());
+ let mut third_hydration = std::pin::pin!(access.hydrate());
+ let mut write = std::pin::pin!(access.write());
+ poll_fn(|cx| {
+ assert!(hydration.as_mut().poll(cx).is_pending());
+ assert!(second_hydration.as_mut().poll(cx).is_pending());
+ assert!(third_hydration.as_mut().poll(cx).is_pending());
+ assert!(write.as_mut().poll(cx).is_pending());
+ Poll::Ready(())
+ })
+ .await;
+ drop(blocker);
+ *write.await = "live";
+ assert!(hydration.await.is_err());
+ assert!(second_hydration.await.is_err());
+ assert!(third_hydration.await.is_err());
+ assert_eq!(*access.lock().await, "live");
+ // A newly fetched page can resume warming after the live write.
+ assert_eq!(*access.hydrate().await.expect("fresh hydration"), "live");
+ });
+ }
+
+ #[test]
+ fn reads_overtake_warming_without_discarding_its_snapshot() {
+ pollster::block_on(async {
+ let access = EngineAccess::new(0);
+ let blocker = access.lock().await;
+ let mut hydration = std::pin::pin!(access.hydrate());
+ let mut read = std::pin::pin!(access.lock());
+ poll_fn(|cx| {
+ assert!(hydration.as_mut().poll(cx).is_pending());
+ assert!(read.as_mut().poll(cx).is_pending());
+ Poll::Ready(())
+ })
+ .await;
+ drop(blocker);
+ // Poll warming first: the foreground mutex reservation still wins.
+ poll_fn(|cx| {
+ assert!(hydration.as_mut().poll(cx).is_pending());
+ Poll::Ready(())
+ })
+ .await;
+ drop(read.await);
+ assert_eq!(*hydration.await.expect("still current"), 0);
+ });
+ }
+}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs
index 63515ea2cd..06bbd56aee 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/calendar.rs
@@ -38,14 +38,21 @@ impl EngineHandle {
.map_err(|error| error.to_string())
}
- /// Applies a calendar commit atomically.
+ /// Applies a calendar commit atomically. Callers await occurrence hydration
+ /// before publishing coverage; this commit supersedes unrelated queued warming.
pub async fn calendar_commit(&self, commit: CalendarCommit) -> Result<WriteResultWire, String> {
- let mut state = self.inner.lock().await;
+ let mut state = self.inner.write().await;
let EngineState { engine, ops, .. } = &mut *state;
let result = engine
.calendar_commit(&commit)
.await
.map_err(|error| error.to_string())?;
- Ok(wire_write_result(ops, result))
+ let unchanged_views = engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap_or_default();
+ let mut result = wire_write_result(ops, result);
+ result.unchanged_views = Some(unchanged_views);
+ Ok(result)
}
}
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
index d7fbdbf1c4..dbe32719fc 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs
@@ -100,6 +100,7 @@ fn read(handle: &EngineHandle, op_id: Option<&str>) -> ReadResultWire {
fn empty_write_result() -> WriteResultWire {
WriteResultWire {
+ unchanged_views: None,
field_changes: None,
identity_errors: Vec::new(),
mutation_uuid: None,
diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs
index e0a4cea8f0..6f5221e12c 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test/soup.rs
@@ -169,7 +169,17 @@ fn native_live_query_returns_field_deltas_from_the_shared_engine() {
project_data(true),
Some(VIEWER),
);
- let next = evaluate(&handle, live_request(first["revision"].as_str()));
+ let registration = serde_json::from_value(first["registrationId"].clone()).unwrap();
+ let next = serde_json::to_value(
+ block_on(handle.resume_entity_filter(
+ "native-live".into(),
+ registration,
+ first["revision"].as_str().map(str::to_owned),
+ ))
+ .unwrap()
+ .unwrap(),
+ )
+ .unwrap();
assert_eq!(next["reset"], false);
assert!(next.get("keys").is_none());
assert!(next["upserts"].as_array().unwrap().is_empty());
@@ -178,6 +188,22 @@ fn native_live_query_returns_field_deltas_from_the_shared_engine() {
next["patches"][0]["fields"],
json!([{ "path":["favorite"], "value":true }])
);
+ assert!(
+ block_on(handle.resume_entity_filter(
+ "native-live".into(),
+ registration,
+ Some("invalid".into()),
+ ))
+ .is_err()
+ );
+ let mut release = live_request(None);
+ release.live_query.as_mut().unwrap().release = true;
+ evaluate(&handle, release);
+ assert!(
+ block_on(handle.resume_entity_filter("native-live".into(), registration, None,))
+ .unwrap()
+ .is_none()
+ );
}
#[test]
diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
index 16e5f98f42..fa02621cc3 100644
--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs
+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs
@@ -52,14 +52,15 @@ pub struct OpsAffectedEvent {
pub field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
/// Registered operation ids (`"{clientId}:{urqlKey}"`) to re-execute.
pub op_ids: Vec<String>,
- /// Changed entity keys, for diagnostics/advanced consumers.
- pub keys: Vec<String>,
}
/// Payload of [`CACHE_CHANGED_EVENT`].
#[derive(Clone, Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CacheChangedEvent {
+ /// Exact displayed windows unaffected by every change in this notification.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ unchanged_views: Option<Vec<String>>,
/// Known query-write changes; missing metadata requests a conservative refresh.
#[serde(skip_serializing_if = "Option::is_none")]
pub search_changed_buckets: Option<std::collections::BTreeSet<String>>,
@@ -113,37 +114,41 @@ impl CacheState {
fn emit_ops_affected<R: Runtime>(
app: &AppHandle<R>,
op_ids: &[String],
- keys: &[String],
field_changes: Option<&Vec<cache_core::field_changes::RecordFieldChange>>,
) {
if op_ids.is_empty() {
return;
}
- app.emit(
+ emit_cache_event(
+ app,
OPS_AFFECTED_EVENT,
OpsAffectedEvent {
field_changes: field_changes.cloned(),
op_ids: op_ids.to_vec(),
- keys: keys.to_vec(),
},
- )
- .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))
- .ok();
+ );
}
fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str, reset: bool) {
- emit_cache_changed_with_search_changes(app, revision, reset, None);
+ emit_cache_changed_with_hints(app, revision, reset, None, None);
}
-fn emit_cache_changed_with_search_changes<R: Runtime>(
+fn emit_cache_changed_with_hints<R: Runtime>(
app: &AppHandle<R>,
revision: &str,
reset: bool,
search_changed_buckets: Option<&std::collections::BTreeSet<String>>,
+ unchanged_views: Option<&Vec<String>>,
) {
- app.emit(
+ emit_cache_event(
+ app,
CACHE_CHANGED_EVENT,
CacheChangedEvent {
+ unchanged_views: if reset {
+ None
+ } else {
+ unchanged_views.cloned()
+ },
search_changed_buckets: if reset {
None
} else {
@@ -152,9 +157,7 @@ fn emit_cache_changed_with_search_changes<R: Runtime>(
revision: revision.to_owned(),
reset: reset.then_some(true),
},
- )
- .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))
- .ok();
+ );
}
fn emit_mutation_settled<R: Runtime>(
@@ -166,7 +169,8 @@ fn emit_mutation_settled<R: Runtime>(
error_code: Option<String>,
replacement_transaction_id: Option<String>,
) {
- app.emit(
+ emit_cache_event(
+ app,
MUTATION_SETTLED_EVENT,
MutationSettledEvent {
transaction_id,
@@ -176,7 +180,23 @@ fn emit_mutation_settled<R: Runtime>(
error_code,
replacement_transaction_id,
},
- )
- .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql mutation settlement"))
- .ok();
+ );
+}
+
+/// Serialize notifications once, recording their wire size without copying the
+/// payload back through a second JSON encoder for diagnostics.
+#[tracing::instrument(
+ name = "graphql_cache.ipc.notification",
+ skip_all,
+ fields(event.name = event, graphql_cache.ipc.payload_bytes = tracing::field::Empty)
+)]
+fn emit_cache_event<R: Runtime, S: Serialize>(app: &AppHandle<R>, event: &str, payload: S) {
+ let emit = || -> tauri::Result<()> {
+ let json = serde_json::to_string(&payload)?;
+ tracing::Span::current().record("graphql_cache.ipc.payload_bytes", json.len());
+ app.emit_str(event, json)
+ };
+ emit()
+ .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache event"))
+ .ok();
}
diff --git a/apps/web/tauri/src-tauri/README.md b/apps/web/tauri/src-tauri/README.md
index f543201a15..2fc3de2514 100644
--- a/apps/web/tauri/src-tauri/README.md
+++ b/apps/web/tauri/src-tauri/README.md
@@ -168,6 +168,26 @@ UPDATE_NATIVE_DIAGNOSTIC_TYPES=1 cargo test --manifest-path apps/web/tauri/Cargo
The same tests without that environment variable check for drift.
+## Linux rendering diagnostics
+
+The app leaves WebKitGTK hardware acceleration and DMABUF negotiation at their
+platform defaults. WebKit's default hardware acceleration policy is `ALWAYS`,
+subject to system support; an available GPU, compatible driver, display server,
+and WebKitGTK build determine the actual rendering path. See the upstream
+[hardware policy](https://webkitgtk.org/reference/webkit2gtk/stable/property.Settings.hardware-acceleration-policy.html)
+and [graphics architecture](https://docs.webkit.org/Ports/WebKitGTK%20and%20WPE%20WebKit/Graphics.html).
+
+Distinguish software-only test machines from GPU-equipped desktops. Check device
+access (`/dev/dri`), the actual EGL renderer in the app's runtime environment,
+and driver/display compatibility. A masked JavaScript WebGL renderer string is
+not reliable hardware evidence. Do not globally disable compositing or DMABUF as
+a performance workaround: that can force more painting onto the CPU. Continuous
+status animations must stay inexpensive on software compositing too.
+
+Run native performance investigations, including all WebKit child processes,
+in the memory-capped scope from the
+[running guide](../../../../docs/development/running-locally.md).
+
## Running in development
```sh
diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rs
index cc24e2ba3f..7e42086e1e 100644
--- a/apps/web/tauri/src-tauri/src/lib.rs
+++ b/apps/web/tauri/src-tauri/src/lib.rs
@@ -416,6 +416,7 @@ pub fn run_with(builder: tauri::Builder<AppRuntime>, configure_window: Configure
graphql_cache_plugin::commands::graphql_cache_read_records_by_keys,
graphql_cache_plugin::commands::graphql_cache_search,
graphql_cache_plugin::commands::graphql_cache_entity_filter,
+ graphql_cache_plugin::commands::graphql_cache_entity_filter_resume,
graphql_cache_plugin::commands::graphql_cache_calendar_range,
graphql_cache_plugin::commands::graphql_cache_calendar_commit,
graphql_cache_plugin::commands::graphql_cache_write,
diff --git a/bun.lock b/bun.lock
index b95e612e0f..fff2f17cad 100644
--- a/bun.lock
+++ b/bun.lock
@@ -397,7 +397,6 @@
"@microlabs/otel-cf-workers": "^1.0.0-rc.52",
"@opentelemetry/api": "^1.9.1",
"@opentelemetry/api-logs": "^0.220.0",
- "@opentelemetry/context-zone": "^2.9.0",
"@opentelemetry/core": "^2.9.0",
"@opentelemetry/exporter-logs-otlp-http": "^0.220.0",
"@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
@@ -408,10 +407,12 @@
"@opentelemetry/semantic-conventions": "^1.43.0",
},
"devDependencies": {
+ "@playwright/test": "1.62.0",
"@types/bun": "^1.3.14",
"@types/node": "^24.8.0",
"jsdom": "^26.1.0",
"typescript": "^5.9.3",
+ "vite": "^6.4.1",
"vitest": "5.0.1",
},
},
@@ -579,14 +580,15 @@
"patchedDependencies": {
"@kobalte/[email protected]": "apps/web/patches/@kobalte%[email protected]",
"@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]",
- "@tanstack/[email protected]": "apps/web/patches/@tanstack%[email protected]",
- "[email protected]": "apps/web/patches/[email protected]",
"@tanstack/[email protected]": "apps/web/patches/@tanstack%[email protected]",
- "[email protected]": "apps/web/patches/[email protected]",
"@kobalte/[email protected]": "apps/web/patches/@kobalte%[email protected]",
"[email protected]": "apps/web/patches/[email protected]",
- "@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]",
"@thisbeyond/[email protected]": "apps/web/patches/@thisbeyond%[email protected]",
+ "@opentelemetry/[email protected]": "apps/web/patches/opentelemetry-otlp-exporter-base-0.220.0.patch",
+ "@tanstack/[email protected]": "apps/web/patches/@tanstack%[email protected]",
+ "[email protected]": "apps/web/patches/[email protected]",
+ "[email protected]": "apps/web/patches/[email protected]",
+ "@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]",
"@tauri-apps/[email protected]": "apps/web/patches/@tauri-apps%[email protected]",
},
"overrides": {
@@ -1357,10 +1359,6 @@
"@opentelemetry/api-logs": ["@opentelemetry/[email protected]", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-CmVa4ImJ+ynfrPMNaAXHET6Bhb44SwzmfyVJFq9ni2jgXJR/l7C6gfVFddNmHP+ZOkP9cf4f9DBe68qVLTHc9w=="],
- "@opentelemetry/context-zone": ["@opentelemetry/[email protected]", "", { "dependencies": { "@opentelemetry/context-zone-peer-dep": "2.9.0", "zone.js": "^0.11.0 || ^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0 || ^0.16.0" } }, "sha512-dUH2j6/jh5hgsAFvEqx+9MIjdi8OzBK1u8K6qsb2HE2R1AiR+u00GWCxbDts30JggTX4rwA8YNLO2xF5LC6EFg=="],
-
- "@opentelemetry/context-zone-peer-dep": ["@opentelemetry/[email protected]", "", { "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0", "zone.js": "^0.10.2 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^0.14.0 || ^0.15.0 || ^0.16.0" } }, "sha512-xECINyl1UHLNbaF1my3K5AqJGyox1ysLidplInAb/XTfBxc2CLDRuS4rUxiJs8irW/PkEDujdc/IPUqkJFnrzg=="],
-
"@opentelemetry/core": ["@opentelemetry/[email protected]", "", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-m2nckMT80NnmjTYSPjJQObBJ+8dgkoajEOUbznL8AHZ3T3yHRk2P7gI1PhEBc1+lOnrYE9UWrWHqJDsmqjmNbw=="],
"@opentelemetry/exporter-logs-otlp-http": ["@opentelemetry/[email protected]", "", { "dependencies": { "@opentelemetry/api-logs": "0.220.0", "@opentelemetry/core": "2.9.0", "@opentelemetry/otlp-exporter-base": "0.220.0", "@opentelemetry/otlp-transformer": "0.220.0", "@opentelemetry/sdk-logs": "0.220.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-8186thl+pTw64iz/qEEen5oJZoZ/gO73XruChdaGlYdWOdBIQ42r+vHLf6a7vIDqTD4b8ZOoMlyxptanECaI9A=="],
@@ -3911,8 +3909,6 @@
"zod-validation-error": ["[email protected]", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-hmk+pkyKq7Q71PiWVSDUc3VfpzpvcRHZ3QPw9yEMVvmtCekaMeOHnbr3WbxfrgEnQTv6haGP4cmv0Ojmihzsxw=="],
- "zone.js": ["[email protected]", "", {}, "sha512-Eky7p2Z1Ig3NnbfodSPoARCjKBSTFMnE/ACsP1L/XJEfY4SdOFce19BsUCWVwL6K5ABZFy5J3bjcMWffX+YM3Q=="],
-
"zwitch": ["[email protected]", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
"@antfu/install-pkg/tinyexec": ["[email protected]", "", {}, "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg=="],
diff --git a/crates/client/cache-core/AGENTS.md b/crates/client/cache-core/AGENTS.md
index f68ac42550..45dd006e69 100644
--- a/crates/client/cache-core/AGENTS.md
+++ b/crates/client/cache-core/AGENTS.md
@@ -19,6 +19,9 @@ GraphQL response shape for callers. A concrete `Storage` impl (e.g.
- `src/engine.rs`: the `CacheEngine` — the crate's entry point, owns queued
mutations, watched queries, and optimistic resolution.
+- `src/engine/window_observation.rs`: bounded immutable predicate-window proofs
+ over the complete change journal, selected dependencies and catalog input fields;
+ unknown evidence never suppresses invalidation.
- `src/normalize.rs` / `src/denormalize.rs`: GraphQL response ↔ normalized record
transforms.
- `src/store.rs`: the `Storage` trait every backend (e.g. `cache-turso`) implements.
@@ -50,6 +53,12 @@ GraphQL response shape for callers. A concrete `Storage` impl (e.g.
- Change what a query can select: `src/predicate.rs` → `src/record_selection.rs`
→ `src/query_inspection.rs`.
+Live views retain at most 32 validated specifications. A registration token
+identifies one retained specification, not the caller's reusable view id.
+`resume_live_query` hydrates durable optimistic state before token lookup;
+the engine owner serializes token lookup and the read. Replacement, release,
+eviction and reset make it miss. A miss requires full registration and never reuses another specification.
+
## Checks
- `cargo test -p cache-core` (`SQLX_OFFLINE` unset).
diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rs
index e3c3e6e737..b30f3b322c 100644
--- a/crates/client/cache-core/src/engine.rs
+++ b/crates/client/cache-core/src/engine.rs
@@ -8,6 +8,7 @@ mod test;
pub mod live_query;
pub mod watch_query;
+mod window_observation;
use crate::calendar::{CalendarError, EVENT_TYPENAME};
use crate::denormalize::{DenormalizeError, ReadOutcome, ReadPlans, ReadSession, RecordSource};
@@ -357,6 +358,7 @@ const DOCUMENT_CACHE_CAPACITY: usize = 128;
pub struct Engine<S: Storage> {
schema: std::sync::Arc<crate::meta::Schema>,
live_queries: live_query::LiveQueries,
+ window_observations: window_observation::WindowObservations,
query_watches: watch_query::QueryWatches,
storage: S,
revision: CacheRevision,
@@ -390,6 +392,7 @@ impl<S: Storage> Engine<S> {
Engine {
schema,
live_queries: live_query::LiveQueries::default(),
+ window_observations: window_observation::WindowObservations::default(),
query_watches: watch_query::QueryWatches::default(),
storage,
revision: CacheRevision::ZERO,
@@ -946,7 +949,8 @@ impl<S: Storage> Engine<S> {
selection: &RecordSelection,
keys: &[EntityKey<'static>],
) -> Result<Revisioned<Vec<SelectedRecord>>, EngineError<S::Error>> {
- let (records, _) = self.read_records_tracked(selection, keys).await?;
+ let (records, dependencies) = self.read_records_tracked(selection, keys).await?;
+ self.bind_window_dependencies(keys, &dependencies);
Ok(self.revisioned(records))
}
@@ -2938,6 +2942,7 @@ impl<S: Storage> Engine<S> {
self.ensure_revision_can_advance()?;
self.hot.clear();
self.live_queries = live_query::LiveQueries::default();
+ self.window_observations = window_observation::WindowObservations::default();
self.query_watches = watch_query::QueryWatches::default();
self.docs.clear();
self.optimistic.clear();
@@ -3018,6 +3023,7 @@ impl<S: Storage> Engine<S> {
self.storage.clear().await.map_err(EngineError::Storage)?;
self.hot.clear();
self.live_queries = live_query::LiveQueries::default();
+ self.window_observations = window_observation::WindowObservations::default();
self.query_watches = watch_query::QueryWatches::default();
self.optimistic.clear();
self.optimistic_hydrated = true;
diff --git a/crates/client/cache-core/src/engine/calendar.rs b/crates/client/cache-core/src/engine/calendar.rs
index 5885624b43..40d4b36dfc 100644
--- a/crates/client/cache-core/src/engine/calendar.rs
+++ b/crates/client/cache-core/src/engine/calendar.rs
@@ -98,6 +98,18 @@ impl<S: CalendarRangeStorage> Engine<S> {
}
let affected_ops = self.deps.ops_for_keys(changed.iter());
let revision = self.advance_revision()?;
+ // Coverage/sync metadata does not change predicate membership. Record
+ // every normalized deletion instead of leaving an unknown journal gap.
+ self.live_queries.record(
+ revision,
+ super::live_query::Changes {
+ records: changed.clone(),
+ projections: changed
+ .iter()
+ .filter_map(|key| predicate_index::RecordKey::new(key.to_string()).ok())
+ .collect(),
+ },
+ );
Ok(WriteResult {
// Deletions carry no values, so invalidation is exact even beneath
// optimistic layers.
diff --git a/crates/client/cache-core/src/engine/live_query.rs b/crates/client/cache-core/src/engine/live_query.rs
index afafdc2d90..30b8e64a75 100644
--- a/crates/client/cache-core/src/engine/live_query.rs
+++ b/crates/client/cache-core/src/engine/live_query.rs
@@ -5,7 +5,7 @@
//! publishes one coherent delta, including rollback, at the engine revision.
use super::*;
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
use std::{collections::VecDeque, sync::Arc};
const VIEW_CAPACITY: usize = 32;
@@ -24,10 +24,19 @@ pub struct LiveQuerySpec {
pub selection: Arc<RecordSelection>,
}
+/// Identity of one retained live-view specification, not a persistent cache key.
+#[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(transparent)]
+pub struct LiveQueryRegistration(Uuid);
+
/// Changes since the subscriber's last accepted view revision.
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct LiveQueryUpdate {
+ /// Identifies this retained specification; invalid after replacement or eviction.
+ pub registration_id: LiveQueryRegistration,
+ /// Immutable proof identity for this exact evaluated window.
+ pub observation_id: String,
/// Exact engine revision observed by this atomic read.
pub revision: String,
/// The subscriber must discard previous rows (first read, eviction or gap).
@@ -131,6 +140,7 @@ pub(super) struct Changes {
}
struct View {
+ registration_id: LiveQueryRegistration,
spec: LiveQuerySpec,
revision: CacheRevision,
membership: PredicateReconciliation,
@@ -255,6 +265,40 @@ impl<S: PredicateIndexStorage> Engine<S> {
return Err(RecordSelectionError::InvalidKey.into());
}
self.hydrate_optimistic().await?;
+ self.read_registered_live_query(id, spec, since).await
+ }
+
+ /// Reads a retained specification without retransmitting it. A missing or
+ /// replaced registration returns None so the caller can register it again.
+ /// Lookup follows durable optimistic-state hydration and shares the read's
+ /// engine lease. A replaced or cleared specification cannot reuse this token.
+ pub async fn resume_live_query(
+ &mut self,
+ id: &str,
+ registration_id: LiveQueryRegistration,
+ since: Option<CacheRevision>,
+ ) -> Result<Option<LiveQueryUpdate>, EngineError<S::Error>> {
+ self.hydrate_optimistic().await?;
+ let Some(view) = self
+ .live_queries
+ .views
+ .peek(id)
+ .filter(|view| view.registration_id == registration_id)
+ else {
+ return Ok(None);
+ };
+ let spec = view.spec.clone();
+ self.read_registered_live_query(id, spec, since)
+ .await
+ .map(Some)
+ }
+
+ async fn read_registered_live_query(
+ &mut self,
+ id: &str,
+ spec: LiveQuerySpec,
+ since: Option<CacheRevision>,
+ ) -> Result<LiveQueryUpdate, EngineError<S::Error>> {
let old = self
.live_queries
.views
@@ -279,6 +323,7 @@ impl<S: PredicateIndexStorage> Engine<S> {
.as_ref()
.is_none_or(|view| view.membership.keys != membership.keys);
let mut view = old.unwrap_or_else(|| View {
+ registration_id: LiveQueryRegistration(Uuid::now_v7()),
spec: spec.clone(),
revision: self.revision,
membership: membership.clone(),
@@ -366,7 +411,12 @@ impl<S: PredicateIndexStorage> Engine<S> {
removed.clear();
patches.clear();
}
+ let observation_id = self
+ .observe_live_query_window(&spec, &membership, &view.dependencies)
+ .await?;
let result = LiveQueryUpdate {
+ registration_id: view.registration_id,
+ observation_id,
revision: self.revision.to_string(),
reset,
keys: order_changed.then(|| membership.keys.clone()),
diff --git a/crates/client/cache-core/src/engine/live_query/test.rs b/crates/client/cache-core/src/engine/live_query/test.rs
index 1b8cade17d..5853b2f18e 100644
--- a/crates/client/cache-core/src/engine/live_query/test.rs
+++ b/crates/client/cache-core/src/engine/live_query/test.rs
@@ -291,6 +291,13 @@ fn nested_entity_changes_patch_only_the_selected_alias() {
)
.await
.unwrap();
+ assert!(
+ !engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .contains(&initial.observation_id)
+ );
let change = engine
.read_live_query("nested", query, Some(initial.revision.parse().unwrap()))
.await
@@ -304,3 +311,416 @@ fn nested_entity_changes_patch_only_the_selected_alias() {
);
});
}
+
+#[test]
+fn window_proofs_exclude_offscreen_changes_but_keep_entrants_and_selected_writes() {
+ block_on(async {
+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), 1);
+ for id in 0..40 {
+ seed(&mut engine, &id.to_string(), id).await;
+ }
+ let first = engine
+ .read_live_query("visible", spec(), None)
+ .await
+ .unwrap();
+ seed(&mut engine, "offscreen", -1).await;
+ assert_eq!(
+ engine.unchanged_observed_windows().await.unwrap(),
+ vec![first.observation_id]
+ );
+ // A matching newcomer inside the sort boundary must wake the window.
+ seed(&mut engine, "entrant", 100).await;
+ assert!(
+ engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ engine
+ .read_live_query("visible", spec(), None)
+ .await
+ .unwrap();
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ key("39"),
+ Record {
+ fields: BTreeMap::from([("isRead".into(), CacheValue::Bool(true))]),
+ },
+ )],
+ vec![],
+ )
+ .await
+ .unwrap();
+ assert!(
+ engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ });
+}
+
+#[test]
+fn window_proofs_require_fragment_dependencies_and_fail_closed_on_journal_barriers() {
+ block_on(async {
+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), 1);
+ seed(&mut engine, "visible", 100).await;
+ let selected = spec();
+ let keys = vec![PredicateRecordKey::new(key("visible").to_string()).unwrap()];
+ let id = engine.observe_predicate_window(selected.query, &keys, None, BTreeSet::new());
+ assert!(
+ engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ engine
+ .read_records_by_keys(&selected.selection, &[key("visible")])
+ .await
+ .unwrap();
+ assert_eq!(engine.unchanged_observed_windows().await.unwrap(), vec![id]);
+ // Even an apparently empty change cannot cross an unknown journal entry.
+ engine.advance_revision().unwrap();
+ assert!(
+ engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ });
+}
+
+#[test]
+fn discarded_reads_cannot_relabel_an_old_displayed_window_as_unchanged() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ seed(&mut engine, "visible", 100).await;
+ let accepted = engine
+ .read_live_query("same-subscription", spec(), None)
+ .await
+ .unwrap();
+ seed(&mut engine, "entrant", 101).await;
+ // The engine advances its view, but the caller never accepts this reply.
+ let discarded = engine
+ .read_live_query("same-subscription", spec(), None)
+ .await
+ .unwrap();
+ assert_ne!(accepted.observation_id, discarded.observation_id);
+ seed(&mut engine, "unrelated", -1).await;
+ engine
+ .put_records_with_projections(
+ None,
+ vec![],
+ vec![ProjectionMutation::Replace(projection(
+ "unrelated",
+ true,
+ -1,
+ ))],
+ )
+ .await
+ .unwrap();
+ let unchanged = engine.unchanged_observed_windows().await.unwrap();
+ assert!(!unchanged.contains(&accepted.observation_id));
+ assert!(unchanged.contains(&discarded.observation_id));
+ });
+}
+
+#[test]
+fn evicted_observations_never_suppress_a_refresh() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ seed(&mut engine, "visible", 100).await;
+ let accepted = engine
+ .read_live_query("subscription", spec(), None)
+ .await
+ .unwrap();
+ for _ in 0..64 {
+ engine
+ .read_live_query("subscription", spec(), None)
+ .await
+ .unwrap();
+ }
+ assert!(
+ !engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .contains(&accepted.observation_id)
+ );
+ });
+}
+
+#[test]
+fn predicate_catalog_inputs_track_fields_without_waking_for_unrelated_parent_fields() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ let user = EntityKey::entity("GraphqlUser", &["viewer"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ user.clone(),
+ Record {
+ fields: BTreeMap::from([("emailLinks".into(), CacheValue::List(vec![]))]),
+ },
+ )],
+ vec![],
+ )
+ .await
+ .unwrap();
+ let id = engine.observe_predicate_window(spec().query, &[], None, BTreeSet::new());
+ engine.observe_window_field(
+ &id,
+ user.clone(),
+ "emailLinks".into(),
+ Some(CacheValue::List(vec![])),
+ );
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ user.clone(),
+ Record {
+ fields: BTreeMap::from([(
+ "soup".into(),
+ CacheValue::String("new-page".into()),
+ )]),
+ },
+ )],
+ vec![],
+ )
+ .await
+ .unwrap();
+ assert!(
+ engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .contains(&id)
+ );
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ user,
+ Record {
+ fields: BTreeMap::from([(
+ "emailLinks".into(),
+ CacheValue::List(vec![CacheValue::Ref(EntityKey::entity(
+ "GraphqlEmailLink",
+ &["account"],
+ ))]),
+ )]),
+ },
+ )],
+ vec![],
+ )
+ .await
+ .unwrap();
+ assert!(
+ !engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .contains(&id)
+ );
+ });
+}
+
+#[test]
+fn calendar_coverage_commits_preserve_unaffected_predicate_windows() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ seed(&mut engine, "visible", 100).await;
+ let accepted = engine
+ .read_live_query("subscription", spec(), None)
+ .await
+ .unwrap();
+ engine
+ .calendar_commit(&crate::calendar::CalendarCommit::default())
+ .await
+ .unwrap();
+ assert!(
+ engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .contains(&accepted.observation_id)
+ );
+ let event = EntityKey::entity("GraphqlCalendarEvent", &["event"]);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![(
+ event.clone(),
+ Record {
+ fields: BTreeMap::from([("id".into(), CacheValue::String("event".into()))]),
+ },
+ )],
+ vec![],
+ )
+ .await
+ .unwrap();
+ let dependent = engine.observe_predicate_window(
+ spec().query,
+ &[],
+ None,
+ [event.clone()].into_iter().collect(),
+ );
+ engine
+ .calendar_commit(&crate::calendar::CalendarCommit {
+ deleted_event_keys: vec![event],
+ ..Default::default()
+ })
+ .await
+ .unwrap();
+ let unchanged = engine.unchanged_observed_windows().await.unwrap();
+ assert!(!unchanged.contains(&dependent));
+ assert!(unchanged.contains(&accepted.observation_id));
+ });
+}
+
+#[test]
+fn baseline_members_can_reenter_even_beyond_a_full_indexed_window() {
+ block_on(async {
+ let mut engine = Engine::new(InMemoryStorage::new());
+ for id in 0..40 {
+ seed(&mut engine, &id.to_string(), id).await;
+ }
+ seed(&mut engine, "baseline", -10).await;
+ engine
+ .put_records_with_projections(
+ None,
+ vec![],
+ vec![ProjectionMutation::Replace(projection(
+ "baseline", true, -10,
+ ))],
+ )
+ .await
+ .unwrap();
+ let mut query = spec();
+ query.baseline = vec![PredicateBaselineEntry {
+ record_key: PredicateRecordKey::new(key("baseline").to_string()).unwrap(),
+ sort_value: -10,
+ }];
+ let accepted = engine
+ .read_live_query("subscription", query.clone(), None)
+ .await
+ .unwrap();
+ assert_eq!(accepted.keys.as_ref().unwrap().len(), 20);
+ engine
+ .put_records_with_projections(
+ None,
+ vec![],
+ vec![ProjectionMutation::Replace(projection(
+ "baseline", false, -10,
+ ))],
+ )
+ .await
+ .unwrap();
+ assert!(
+ !engine
+ .unchanged_observed_windows()
+ .await
+ .unwrap()
+ .contains(&accepted.observation_id)
+ );
+ let changed = engine
+ .read_live_query(
+ "subscription",
+ query,
+ Some(accepted.revision.parse().unwrap()),
+ )
+ .await
+ .unwrap();
+ assert!(
+ changed
+ .keys
+ .unwrap()
+ .iter()
+ .any(|entry| entry.as_str() == key("baseline").as_ref())
+ );
+ });
+}
+
+#[test]
+fn continuation_is_bound_to_the_retained_specification() {
+ block_on(async {
+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), 1);
+ seed(&mut engine, "a", 1).await;
+ let initial = engine.read_live_query("view", spec(), None).await.unwrap();
+ let revision = initial.revision.parse().unwrap();
+ let unchanged = engine
+ .resume_live_query("view", initial.registration_id, Some(revision))
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(!unchanged.reset);
+ assert!(unchanged.upserts.is_empty());
+ assert_eq!(unchanged.registration_id, initial.registration_id);
+ seed(&mut engine, "b", 2).await;
+ let delta = engine
+ .resume_live_query("view", initial.registration_id, Some(revision))
+ .await
+ .unwrap()
+ .unwrap();
+ assert!(!delta.reset);
+ assert_eq!(delta.upserts.len(), 1);
+ let mut changed = spec();
+ changed.selection = Arc::new(
+ RecordSelection::parse(
+ crate::meta::bundled_schema_ref(),
+ "fragment Item on GraphqlSoupEmailThread { id }",
+ "Item",
+ )
+ .unwrap(),
+ );
+ let replaced = engine.read_live_query("view", changed, None).await.unwrap();
+ assert_ne!(initial.registration_id, replaced.registration_id);
+ assert!(
+ engine
+ .resume_live_query("view", initial.registration_id, None)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ engine.release_live_query("view");
+ assert!(
+ engine
+ .resume_live_query("view", replaced.registration_id, None)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ });
+}
+
+#[test]
+fn evicted_continuations_require_registration_again() {
+ block_on(async {
+ let mut engine = Engine::with_capacity(InMemoryStorage::new(), 1);
+ let initial = engine.read_live_query("view", spec(), None).await.unwrap();
+ for id in 0..VIEW_CAPACITY {
+ engine
+ .read_live_query(&id.to_string(), spec(), None)
+ .await
+ .unwrap();
+ }
+ assert!(
+ engine
+ .resume_live_query("view", initial.registration_id, None)
+ .await
+ .unwrap()
+ .is_none()
+ );
+ let registered = engine.read_live_query("view", spec(), None).await.unwrap();
+ assert_ne!(initial.registration_id, registered.registration_id);
+ assert!(registered.reset);
+ });
+}
diff --git a/crates/client/cache-core/src/engine/window_observation.rs b/crates/client/cache-core/src/engine/window_observation.rs
new file mode 100644
index 0000000000..3c409c0ac3
--- /dev/null
+++ b/crates/client/cache-core/src/engine/window_observation.rs
@@ -0,0 +1,304 @@
+//! Conservative invalidation proofs for displayed predicate windows.
+//!
+//! This uses the same complete record/projection journal as maintained views.
+//! Search bucket hints are deliberately irrelevant: property and nested-record
+//! changes must participate even when they do not affect search.
+use super::*;
+use crate::value::CacheValue;
+
+pub(super) struct WindowObservation {
+ revision: CacheRevision,
+ query: ValidatedIndexQuery,
+ keys: BTreeSet<EntityKey<'static>>,
+ boundary: Option<(i64, PredicateRecordKey)>,
+ dependencies: BTreeSet<EntityKey<'static>>,
+ bound: BTreeSet<EntityKey<'static>>,
+ fields: BTreeMap<(EntityKey<'static>, String), Option<CacheValue>>,
+}
+
+pub(super) struct WindowObservations {
+ windows: LruCache<String, WindowObservation>,
+ next_id: u64,
+ instance: Uuid,
+}
+
+impl Default for WindowObservations {
+ fn default() -> Self {
+ Self {
+ windows: LruCache::new(NonZeroUsize::new(64).expect("nonzero observation capacity")),
+ next_id: 0,
+ instance: Uuid::new_v4(),
+ }
+ }
+}
+
+impl<S: Storage> Engine<S> {
+ /// Registers a displayed indexed window. The boundary must be a proven
+ /// full-window cutoff; omit it for partial or uncertain membership.
+ /// Selection reads bind recursive record dependencies before proofs apply.
+ pub fn observe_predicate_window(
+ &mut self,
+ query: ValidatedIndexQuery,
+ keys: &[PredicateRecordKey],
+ boundary: Option<(i64, PredicateRecordKey)>,
+ dependencies: BTreeSet<EntityKey<'static>>,
+ ) -> String {
+ let id = self.next_window_id();
+ self.install_window_observation(id.clone(), query, keys, boundary, dependencies, false);
+ id
+ }
+
+ /// Adds a field-level input to the window's compiled predicate. Unrelated
+ /// fields of a catalog record must not invalidate that predicate. Bind the
+ /// exact compile-input value before releasing the engine for another write.
+ pub fn observe_window_field(
+ &mut self,
+ id: &str,
+ key: EntityKey<'static>,
+ field: String,
+ value: Option<CacheValue>,
+ ) {
+ if let Some(window) = self.window_observations.windows.get_mut(id) {
+ window.fields.insert((key, field), value);
+ }
+ }
+
+ fn next_window_id(&mut self) -> String {
+ self.window_observations.next_id += 1;
+ format!(
+ "{}:{}",
+ self.window_observations.instance, self.window_observations.next_id
+ )
+ }
+
+ fn install_window_observation(
+ &mut self,
+ id: String,
+ query: ValidatedIndexQuery,
+ keys: &[PredicateRecordKey],
+ boundary: Option<(i64, PredicateRecordKey)>,
+ dependencies: BTreeSet<EntityKey<'static>>,
+ bound: bool,
+ ) {
+ self.window_observations.windows.put(
+ id,
+ WindowObservation {
+ revision: self.revision,
+ query,
+ keys: keys
+ .iter()
+ .map(|key| EntityKey(key.as_str().to_owned().into()))
+ .collect(),
+ boundary,
+ dependencies,
+ fields: BTreeMap::new(),
+ bound: if bound {
+ keys.iter()
+ .map(|key| EntityKey(key.as_str().to_owned().into()))
+ .collect()
+ } else {
+ BTreeSet::new()
+ },
+ },
+ );
+ }
+
+ pub(super) fn bind_window_dependencies(
+ &mut self,
+ keys: &[EntityKey<'static>],
+ dependencies: &live_query::RowDependencies,
+ ) {
+ for (_, window) in self.window_observations.windows.iter_mut() {
+ for key in keys {
+ if !window.keys.contains(key) {
+ continue;
+ }
+ window.bound.insert(key.clone());
+ window.dependencies.insert(key.clone());
+ if let Some(read) = dependencies.get(key) {
+ window.dependencies.extend(read.iter().cloned());
+ }
+ }
+ }
+ }
+}
+
+impl<S: PredicateIndexStorage> Engine<S> {
+ /// IDs whose displayed membership and selected-record dependencies are
+ /// proven unchanged. Missing IDs always mean unknown, never unchanged.
+ pub async fn unchanged_observed_windows(
+ &mut self,
+ ) -> Result<Vec<String>, EngineError<S::Error>> {
+ // Optimistic composition can shadow authoritative facts. Keep its
+ // existing conservative invalidations rather than checking bare bases.
+ if !self.optimistic.is_empty() {
+ return Ok(Vec::new());
+ }
+ let mut candidates = Vec::new();
+ let mut projection_keys = BTreeSet::new();
+ let mut record_keys = BTreeSet::new();
+ for (id, window) in &self.window_observations.windows {
+ if !window.keys.is_subset(&window.bound) {
+ continue;
+ }
+ let Some(changes) = self
+ .live_queries
+ .changes_since(window.revision, self.revision)
+ else {
+ continue;
+ };
+ if changes
+ .records
+ .iter()
+ .any(|key| window.dependencies.contains(key))
+ || changes.projections.iter().any(|key| {
+ window
+ .keys
+ .contains(&EntityKey(key.as_str().to_owned().into()))
+ || window
+ .dependencies
+ .contains(&EntityKey(key.as_str().to_owned().into()))
+ })
+ {
+ continue;
+ }
+ record_keys.extend(
+ window
+ .fields
+ .keys()
+ .filter_map(|(key, _)| changes.records.contains(key).then_some(key.clone())),
+ );
+ projection_keys.extend(changes.projections.iter().cloned());
+ candidates.push((id, window, changes));
+ }
+ let projection_keys: Vec<_> = projection_keys.into_iter().collect();
+ let states = if projection_keys.is_empty() {
+ Vec::new()
+ } else {
+ self.storage
+ .load_projection_states(&projection_keys)
+ .await
+ .map_err(EngineError::Storage)?
+ };
+ let states: HashMap<_, _> = projection_keys.into_iter().zip(states).collect();
+ let record_keys: Vec<_> = record_keys.into_iter().collect();
+ let records = if record_keys.is_empty() {
+ Vec::new()
+ } else {
+ self.storage
+ .get_batch(&record_keys)
+ .await
+ .map_err(EngineError::Storage)?
+ };
+ let records: HashMap<_, _> = record_keys.into_iter().zip(records).collect();
+ let unchanged: Vec<_> = candidates
+ .into_iter()
+ .filter_map(|(id, window, changes)| {
+ let field_changed = window.fields.iter().any(|((key, field), value)| {
+ if !changes.records.contains(key) {
+ return false;
+ }
+ let Some(Some(record)) = records.get(key) else {
+ return true;
+ };
+ record.fields.get(field) != value.as_ref()
+ });
+ if field_changed {
+ return None;
+ }
+ let may_enter = changes.projections.iter().any(|key| {
+ let Some(state) = states.get(key) else {
+ return true;
+ };
+ let Some(state) = state else {
+ return false;
+ };
+ if !window
+ .query
+ .includes_scope(state.profile(), state.partition())
+ {
+ return false;
+ }
+ let ProjectionState::Complete(document) = state else {
+ return true;
+ };
+ let query = window.query.as_query();
+ if !query.partitions.iter().any(|part| {
+ part.partition == document.partition && document.matches(&part.predicate)
+ }) {
+ return false;
+ }
+ let value = document
+ .sort_facts
+ .iter()
+ .find(|fact| fact.attribute == query.sort_attribute)
+ .map(|fact| fact.value);
+ match (value, &window.boundary) {
+ (Some(value), Some((edge, edge_key))) => {
+ !window.query.sorts_after((value, key), (*edge, edge_key))
+ }
+ _ => true,
+ }
+ });
+ (!may_enter).then(|| id.clone())
+ })
+ .collect();
+ for id in &unchanged {
+ if let Some(window) = self.window_observations.windows.get_mut(id) {
+ window.revision = self.revision;
+ }
+ }
+ Ok(unchanged)
+ }
+
+ pub(super) async fn observe_live_query_window(
+ &mut self,
+ spec: &live_query::LiveQuerySpec,
+ membership: &PredicateReconciliation,
+ dependencies: &live_query::RowDependencies,
+ ) -> Result<String, EngineError<S::Error>> {
+ let mut boundary = None;
+ if membership.retained_keys.is_empty()
+ && membership.keys.len() >= usize::from(spec.query.as_query().limit)
+ && let Some(key) = membership.keys.last()
+ {
+ let states = self
+ .storage
+ .load_projection_states(std::slice::from_ref(key))
+ .await
+ .map_err(EngineError::Storage)?;
+ if let Some(Some(ProjectionState::Complete(document))) = states.first() {
+ boundary = document
+ .sort_facts
+ .iter()
+ .find(|fact| fact.attribute == spec.query.as_query().sort_attribute)
+ .map(|fact| (fact.value, key.clone()));
+ }
+ }
+ let id = self.next_window_id();
+ self.install_window_observation(
+ id.clone(),
+ spec.query.clone(),
+ &membership.keys,
+ boundary,
+ dependencies
+ .values()
+ .flatten()
+ .cloned()
+ .chain(
+ membership
+ .keys
+ .iter()
+ .map(|key| EntityKey(key.as_str().to_owned().into())),
+ )
+ .chain(
+ spec.baseline
+ .iter()
+ .map(|entry| EntityKey(entry.record_key.as_str().to_owned().into())),
+ )
+ .collect(),
+ true,
+ );
+ Ok(id)
+ }
+}
diff --git a/crates/client/cache-wasm/AGENTS.md b/crates/client/cache-wasm/AGENTS.md
index dd1eb99b99..e0c2dd8cb5 100644
--- a/crates/client/cache-wasm/AGENTS.md
+++ b/crates/client/cache-wasm/AGENTS.md
@@ -46,6 +46,8 @@ wasm-bindgen shell exposing `cache-core` + `cache-turso` + `turso-opfs` as a
## Gotchas
+- Preserve successful hydration replies when optional window-proof computation
+ fails; empty proofs retain broad invalidation after the durable write.
- Pass the existing entity-filter `baseline` to Mail pagination too; `retainedKeys`
tells the frontend which server rows still lack canonical local metadata.
diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rs
index a9cf59c015..1d8f204bdb 100644
--- a/crates/client/cache-wasm/src/shell.rs
+++ b/crates/client/cache-wasm/src/shell.rs
@@ -150,6 +150,8 @@ struct JsQueryRegistration {
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsWriteResult {
+ #[serde(skip_serializing_if = "Option::is_none")]
+ unchanged_views: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
#[serde(skip_serializing_if = "Vec::is_empty")]
@@ -169,6 +171,7 @@ struct JsWriteResult {
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsHydrationWriteResult {
+ unchanged_views: Vec<String>,
search_changed_buckets: std::collections::BTreeSet<String>,
revision: String,
revision_advanced: bool,
@@ -457,6 +460,7 @@ enum JsRollbackOptimisticWriteResult {
fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {
JsWriteResult {
+ unchanged_views: None,
field_changes: result.field_changes,
identity_errors: result.identity_errors,
revision: result.revision.to_string(),
@@ -1793,7 +1797,14 @@ impl CacheEngine {
)
.await;
let result = state.engine_result(result)?;
+ // A failed optional proof must still deliver the committed write and broad invalidation.
+ let unchanged_views = state
+ .engine_mut()?
+ .unchanged_observed_windows()
+ .await
+ .unwrap_or_default();
to_js(&JsHydrationWriteResult {
+ unchanged_views,
search_changed_buckets: result.search_changed_buckets,
revision: result.write_result.revision.to_string(),
revision_advanced: result.write_result.revision_advanced,
diff --git a/crates/client/cache-wasm/src/shell/calendar.rs b/crates/client/cache-wasm/src/shell/calendar.rs
index 176f32bce4..f2a630a3b3 100644
--- a/crates/client/cache-wasm/src/shell/calendar.rs
+++ b/crates/client/cache-wasm/src/shell/calendar.rs
@@ -49,7 +49,14 @@ impl CacheEngine {
let commit: CalendarCommit = serde_wasm_bindgen::from_value(commit).map_err(err_js)?;
let result = state.engine_mut()?.calendar_commit(&commit).await;
let result = state.engine_result(result)?;
- to_js(&js_write_result(result, &ops.borrow()))
+ let unchanged_views = state
+ .engine_mut()?
+ .unchanged_observed_windows()
+ .await
+ .unwrap_or_default();
+ let mut result = js_write_result(result, &ops.borrow());
+ result.unchanged_views = Some(unchanged_views);
+ to_js(&result)
})
}
}
diff --git a/docs/agent-guide/channels.md b/docs/agent-guide/channels.md
index dc0cc6b24a..a1e58ee18e 100644
--- a/docs/agent-guide/channels.md
+++ b/docs/agent-guide/channels.md
@@ -1627,3 +1627,8 @@ Sending clears the composer immediately while delivery is pending. If delivery
fails and the composer is still empty, its text, mentions, and attachments return.
A new draft typed during delivery stays intact if the earlier send fails. Verify
this with both the Send button on a phone and the desktop composer.
+
+For tab performance QA, switch Attachments → Calls → Participants → Messages
+in both the routed channel and a block split. Each actual selection should
+produce one `channel.tab` interaction with its `channel.*.view` child; repeat
+the current selection and confirm it does not create a new interaction.
diff --git a/docs/agent-guide/crm.md b/docs/agent-guide/crm.md
index 5db5a9497d..acc639c55e 100644
--- a/docs/agent-guide/crm.md
+++ b/docs/agent-guide/crm.md
@@ -494,3 +494,10 @@ columns. Changing scope requires preparing again. Cancel stops preparation. CSV
quoted fields, original date timestamps and spreadsheet formula escaping.
The existing CRM New menus use icons and muted descriptions for Company, Contact, and Pipeline. Pipeline availability and permissions are unchanged.
+
+For loading diagnostics (span names in the
+[observability guide](observability.md#navigation-and-view-phases)), switch
+sections and reopen a record: each restarts the `crm.company` / `crm.contact`
+flow, and disabled sources must not leave it waiting once metadata is ready.
+Traces hold opaque record ids and section categories, never names or addresses.
+Metadata errors may cancel the detail flow when the outer error panel replaces it.
diff --git a/docs/agent-guide/forms.md b/docs/agent-guide/forms.md
index 7b44a5d5d9..adde405f6f 100644
--- a/docs/agent-guide/forms.md
+++ b/docs/agent-guide/forms.md
@@ -292,3 +292,14 @@ includes the target form ID; inspect it and make targeted repairs.
Forms tool UI follows the existing `enable-forms` feature flag; server execution
uses the same authenticated user/delegated-agent permissions as the rest of Forms.
Owners can still close a form or remove access when its draft needs repair.
+
+For timing Build → Responses → Settings, inspect `form.tab` and its panel phase
+in the same trace. Response counts and the database grid have separate waits.
+Switch back to Build and verify that its editing state/layout session survives.
+
+On the respondent route (spans in the
+[observability guide](observability.md#navigation-and-view-phases)), failed
+`form.submit` saves record an error outcome and retain answers;
+retry after restoring transport and verify there is still one saved response.
+Leaving the respondent view cancels its UI measurement; an in-flight save
+still finishes without scrolling or measuring a different view.
diff --git a/docs/agent-guide/observability.md b/docs/agent-guide/observability.md
index 8a77169d66..faf49a8591 100644
--- a/docs/agent-guide/observability.md
+++ b/docs/agent-guide/observability.md
@@ -5,8 +5,8 @@ The local stack ships an LGTM sidecar; the Grafana MCP server exposes it. Dataso
## The trace for the thing you just did (deterministic)
-Every frontend request to the backend proxy carries a W3C `traceparent` header. That trace ID
-is the join key:
+When browser telemetry is enabled, traced frontend requests to the backend proxy
+carry a W3C `traceparent` header. That trace ID is the join key:
1. Perform the UI action.
2. `list_network_requests` (resourceTypes xhr/fetch) → find the mutating request, e.g.
@@ -73,9 +73,6 @@ trace context — timestamps + service are the only join for those.
filter. The span also ignores `traceparent`, so browser traces of email_service
requests end at the `http` client span. The gap is read from the code and not
yet confirmed in Tempo.
-- With `ENABLE_BEARER_TOKEN_AUTH` (Playwright e2e and the native test runner),
- `fetchWithAuth` awaits the API token before `safeFetch`. Its `http` client spans
- then start outside the calling span and root their own traces.
## Account WebSocket sessions
@@ -233,3 +230,296 @@ Backend spans join through the existing `traceparent` trace ID; recording resour
attributes belong to the frontend, and are not automatically copied onto backend
services. Correlate complete traces by finding their frontend span. Always-on
client sampling does not override downstream sampling or prevent transport loss.
+
+## Web performance traces
+
+How to add these flows is in the `instrumentation` skill; this section is how to
+find and read them.
+
+### Finding them
+
+Boot, navigation, view loading and in-view interactions are `perf`-class traces.
+Search `{ resource.service.name = "web-app" && span.macro.sampling.class = "perf" }`,
+or by root name: `app.boot`, `navigation`, `view.<route id>` (with `route.id`),
+`list.open`, `channel.tab`, `form.tab`, `email.tab`, `quick_access.open`,
+`quick_access.input`, `calendar.event.open`, `message.send`, `email.send`,
+`input.typing_burst`, `app.runtime.sample`. Then open the full trace.
+
+- `list.open` runs from a list row's open action (Home, Mail, Soup lists,
+ tasks, CRM) through any notification lookup to the opened view's paint; its
+ `navigation` and view are children. `entity.type` says what opened.
+- `message.send` runs from a channel composer send to the optimistic message's
+ paint opportunity (`message.id`, `channel.id`); delivery stays on the separate
+ `channel.send` trace with the same `message.id`.
+- `email.send` runs from Send (after the composer's checks) to the sent state;
+ `email.send.queued` says whether the durable outbox took it. Early refusals
+ are `cancelled`, failures `error`.
+- `email.tab` contains the restarted `email.list` flow and its
+ `email.list.items` phase; on first load `email.list` is a phase of the mail
+ view.
+- `calendar.event.open` times opening an event's details (`calendar.event.origin`
+ is `grid` or `agenda`).
+
+Traces belong to a sampling class (`apps/web/src/observability/sampling.ts`):
+`perf` is kept for 5% of production users and every user in dev, local builds
+and explicit native recordings; `always` is kept for everyone. Each class is
+decided once per user per class at enablement, from a hash of the signed-in
+user id (the document's `frontend_instance_id` before sign-in) salted with the
+week, so the cohort rotates weekly; `Telemetry.config.sampled('perf')` reads
+it. Spans started before enablement are buffered and placed at export.
+
+A span joins its parent's trace when that trace is exported. Otherwise a phase
+(`span.span`) is dropped with it, and any other span starts its own trace when
+its own class is kept and is dropped when it is not; a span that asks for no
+class is always kept. Unsampled users drop perf traces and install no
+runtime-resource or typing listeners, while requests and other spans started
+inside a dropped perf trace (`Telemetry.span`) start their own trace instead,
+so backend traces are never lost to perf sampling.
+
+### Span model
+
+Every perf trace has one root. Phases are `<area>.<phase>` (`channel.messages`,
+`doc.load.context`); nested flows for a mounted subtree end in `.view` when the
+area has several (`channel.messages.view`). Names are static: no ids, counts or
+content in a name. In Datadog the span name is `resource_name` (the
+`operation_name` is the span kind, such as `Internal`), except HTTP client
+spans, whose `resource_name` is the method and whose path is `@http.url`. The
+`perf-investigation` skill has verified Datadog query shapes.
+
+| Root | `flow.kind` | Started by | `route.id` |
+| --- | --- | --- | --- |
+| `app.boot` | `boot` | `observability/boot.ts` | The innermost view it opened |
+| `navigation` | `navigation` | split-router commit (`runner.ts`) | The innermost view it opened; none when it opened no view |
+| `view.<route id>` | `view` | `RouteView` in `split-router/solid/outlet.tsx`; a root only when no navigation is open, otherwise a phase of it | Its route |
+| Other `<TraceFlow>` roots (`quick_access.results`, `doc.editor` after the view settled) | `view` | `TraceFlow` | Last opened view |
+| `quick_access.open`, `quick_access.input`, `channel.tab`, `form.tab`, `email.tab`, `list.open`, `calendar.event.open` | `interaction` | `beginInteraction` | Last opened view, or the innermost view it opened |
+| `database.cell.editor.open`, `database.cell.commit`, `form.submit`, `message.send`, `email.send`, `input.typing_burst` | `interaction` | `startUiOperation` | Last opened view |
+
+`urql.reconcile` and `graphql_cache.ipc.request` are perf-class spans that are
+not flows (no `flow.kind`); `app.runtime.sample` is a point sample.
+
+Attributes every perf trace carries, set by the owners (`ui-operation.ts`,
+`flow.tsx`, `packages/observability` tracing), not by call sites:
+
+| On | Attributes |
+| --- | --- |
+| Every span in a classed trace, including HTTP client spans started in it | `macro.sampling.class` (the class it asked for, else its parent's) and `macro.sampling.rate` (that class's rate; weight by its inverse) |
+| Roots | `flow.kind`, `route.id` (when known), `ui.operation`, `ui.outcome` (`success`, `cancelled`, `hidden`, `timeout`), `ui.elapsed_ms`, `ui.work_to_ready_ms` (success only), `ui.long_task_count`, `ui.long_task_overlap_ms`, `ui.long_animation_frame_count`, `ui.long_animation_frame_overlap_ms`, `ui.long_animation_frame_blocking_ms`, `ui.visibility`; with an input event, `ui.input_to_ready_ms`, `ui.input_to_paint_opportunity_ms` and `ui.event_*` |
+| Flow roots | `flow.phase_count` (child spans opened), `flow.ready_phase_count` (`usePending` phases already loaded when reached) |
+| Phases | `flow.root` (the root's name), `route.id` (the nearest view's), `flow.outcome` (`success` or `cancelled`) |
+| A phase's parent | `<phase>.waited`: `false` when it was already loaded (cache or an earlier load), `true` when the flow waited for it |
+| Resource (Datadog tags and facets) | `service.name=web-app`, `service.version` (Datadog `version`), `deployment.environment` (Datadog `env`), `app.runtime` (`browser`, `tauri`), `app.platform` (`web`, `desktop`, `ios`, `android`), `os.type` (`darwin`, `windows`, `linux`, `ios`, `android`, `chromeos`, `unknown`), `frontend_instance_id` |
+
+Entity context is opaque ids and categories only, on the phase that loads the
+entity (`block.type` and `document.id` on `block.data`, `channel.id`,
+`entity.type` and `entity.id`); never titles, text, queries or addresses.
+
+Requests join the flow that started them. urql query bindings and TanStack
+queries (`lib/queries/flow-trace.ts`) created inside a flow send their request
+in that flow's context while it loads; an imperative `client.query` sends its
+first request in the span it was called in (`captureTraceParentExchange`). So
+`graphql.transport` and `http <method> <path>` spans are descendants of the
+flow node and carry `traceparent` to the backend. They hang under the flow
+(`view.*` or a nested `TraceFlow`), not under the `usePending` phase that
+watches the query. A refetch after the flow settled, and global background
+queries (pending sends, Command-K sources), start their own traces.
+
+### Boot (`app.boot`)
+
+Search `{ resource.service.name="web-app" && name="app.boot" }` after a cold
+navigation or reload. `app.boot` is an interaction (`beginInteraction` with
+`startTime: 0` and `closeOnJoin`) that starts at browser navigation time,
+including work before JavaScript evaluated. The router's initial `navigation`
+and the first view join it even when the lazy view mounts after the navigation
+commits; a first view that unmounts before loading (a redirect) leaves it open
+for the next. It finishes at that view's paint opportunity; otherwise `ui.outcome` is
+`hidden`, `cancelled` or `timeout` (30 seconds), also copied to `boot.outcome`.
+
+When it finishes, `observability/boot.ts` reconstructs from the Performance API:
+
+- `boot.dns`, `boot.connect`, `boot.tls`, `boot.request`, `boot.response`,
+ `boot.dom` from navigation timing, plus `boot.navigation_type`.
+- `macro.*` performance marks as events, and `boot.auth.refresh` intervals
+ paired from `macro.auth.refresh-start/end`, including refreshes the async
+ session entry completed before the provider registered. This is frontend
+ timing only; that pre-provider request's backend span is not linked.
+- `boot.resource.{script,wasm,font}.{count,encoded_bytes,decoded_bytes,transfer_bytes,duration_ms}`
+ aggregates. No resource URLs or per-resource spans are recorded.
+
+Long-task aggregates come from the shared UI-operation observer, like every
+other root.
+
+Rendering never waits for telemetry enablement or native diagnostics. The
+provider registers immediately and buffers at most 2,048 ended spans; promise
+resource attributes (diagnostic identity) still enrich spans that ended early.
+Exporters and outgoing trace headers stay off until enablement resolves, and a
+denied or failed decision drops the buffer. An explicit native recording keeps
+every span and picks its exporter destination.
+
+### Navigation and view phases
+
+Router commits start a `navigation` interaction; each routed view is a
+`view.<route id>` flow under it, keyed on route params, so an in-place param
+change restarts the flow and its loads are timed like a fresh mount.
+
+Phases you will see:
+
+- Blocks: concurrent `block.component` (lazy module) and `block.data`; routed
+ file details use `document.load`. Either passes its span into `doc.load` →
+ `doc.load.context` and into the sync socket's `traceparent`. `doc.editor` and
+ `doc.editor.initialize` time the editor subtree and its initial sync; snapshot
+ phases share the same flow. One open is one navigation/view trace; there is no
+ `doc.open` root. `doc.create` ends at navigation and the new view owns the
+ load; AI edits have their own `doc.edit` phase.
+- Agents: `agent.session.load` (cache read/fold, session fetch, log fetch, fold
+ and paint timings) when the view acquires a session; `agent.provision` waits
+ for a newly created one; `agent.transcript` waits for the first visible
+ transcript, cached or not. An already shared session adds no load span. The
+ fold stage includes synchronous listener projection, reported separately as
+ `agent.session.load.projection_ms` with its message count; do not add the two.
+ A slow fold with a similarly slow projection is main-thread store work, not
+ WASM.
+- Lists and details: `channel.messages`, `channel.detail`, `email.thread`,
+ `database.detail`, `database.rows`, `calendar.target`, `calendar.occurrences`
+ (per mounted page), `activity.feed`, `activity.overview`, `home.items`,
+ `home.list`, `drive.items`, `reviews.items`, `settings.plan`, shared Soup
+ `list.items` / `list.search.remote` / `list.search.local`, and mobile search
+ `search.names` / `search.rank` / `search.full-text`.
+- Canvas: `canvas.context`, `canvas.location`, `canvas.download` (legacy files
+ only), `canvas.parse`, `canvas.sync`.
+- CRM: `crm.company` / `crm.contact` keyed by record and section, with
+ `crm.record` (metadata) and `crm.items` (enabled record lists), plus
+ `crm.personal-views` / `crm.team-views`.
+- Forms: `form.tab` contains one `form.build`, `form.responses` or
+ `form.settings` child (Responses adds `form.responses.summary` and the grid's
+ row phase); `form.layout` times layout initialization. The respondent route
+ is `view.form-respond` with `form.detail` and `form.response`; `form.submit`
+ runs from Submit to the next paint opportunity, with HTTP below it.
+- Channel tabs: `channel.tab` contains the selected `channel.<tab>.view` phase,
+ for routed and block channels alike.
+- Command-K: `quick_access.open` starts at the hotkey and joins the
+ `quick_access.results` flow, whose `quick_access.sources` phase waits for
+ sources. `quick_access.input` starts at the input event and contains
+ `quick_access.debounce` / `quick_access.sources`; a newer input cancels the
+ previous results flow and moves a still-pending source phase to it. For a slow
+ `quick_access.search`, compare `quick_access.search_page` with
+ `quick_access.materialize` and the `search.page_count`,
+ `search.materialized_count` and `search.index.count` attributes;
+ `search.index.last_build_ms` is the latest index rebuild, not another phase.
+ Only query lengths and counts are recorded. `email.drafts.discover` is
+ event-driven local draft discovery, coalescing same-microtask notifications.
+- Preloading: block intent records `block.preload` with parallel
+ `block.preload.code` and `block.preload.data`; idle warming records
+ `block.preload.background`. To check the waterfall, open a document or
+ conversation from its list in a fresh session, return, and reopen it: hover,
+ focus and pointer press start both the data request and the lazy chunk, and
+ background imports wait for the first view and stop during active requests.
+
+### Reading phases
+
+- A phase already settled when its flow reached it emits `<name>.ready` instead
+ of a span and sets `<name>.waited=false` on its parent. That means it did not
+ wait, not that the cache was hit; use the explicit cache fields on lifecycle
+ spans to compare warm and cold. On the root, `flow.ready_phase_count` against
+ `flow.phase_count` shows how much of a view was already warm.
+- Background refetches after readiness do not extend or reopen a flow.
+- Phases overlap (`block.data` and `block.component` run concurrently); never
+ add durations together.
+- On roots, compare `ui.work_to_ready_ms`, `ui.input_to_ready_ms` and
+ `ui.input_to_paint_opportunity_ms` (when an input event was supplied) with
+ `ui.long_task_*` and `ui.long_animation_frame_*`. These are a two-frame paint
+ opportunity and overlapping main-thread work, not proof a pixel painted or
+ that the flow caused every task.
+- `flow.outcome=success` means the UI reached readiness, which can be a
+ terminal error panel; read connected HTTP spans to tell whether data loaded.
+ Exclude cancelled, hidden, timeout and error outcomes from load percentiles.
+
+### Measuring locally
+
+- Use an isolated Playwright Chrome with CDP `Emulation.setCPUThrottlingRate`
+ `rate: 4`; warm each route once, then collect at least five opens with the
+ same data and viewport. Record the median, dominant phase, long tasks and
+ trace ids before and after.
+- Never compare a cold Vite module compilation with a warm route, or substitute
+ login/error screens for unavailable authenticated surfaces.
+- When a before/after table suggests a regression, alternate A/B (or ABBA/BAAB)
+ for at least seven samples per version with the same account, content,
+ throttle, viewport and view settings; copy local preferences when the
+ frontends use different origins. Keep warm-up reloads and CPU profiling out of
+ the timed samples, and report paint opportunity and the changed phase
+ separately. For layout regressions, also compare CDP layout/style counts.
+- Keep injected error probes separate from successful-latency samples.
+- Cold-start and warm-cache methodology is in
+ [navigation](navigation.md#cold-start-admission).
+
+## Runtime CPU and memory samples
+
+`app.runtime.sample` is a perf-class point sample per ~60 s of visible-tab time
+for perf-sampled users. Hiding pauses it, returning starts a fresh window, and
+late memory reads from an old window are dropped; back/forward-cache restores
+restart it. Group by `app.platform`, `app.runtime`, `os.type` and app version,
+and plot against `runtime.session_age_ms` (age of this document, reset on
+reload):
+
+- `macro.memory.browser.bytes` (source `user_agent_specific`): browser aggregate
+ memory, only when cross-origin isolated and supported. Otherwise
+ `macro.memory.js_heap.{used,total,limit}_bytes` (source `js_heap`), Chromium's
+ heap estimate, not resident memory. `macro.memory.browser.source` is
+ `unavailable` when neither API works.
+- `runtime.long_task.ms` and `runtime.long_animation_frame.blocking_ms` over
+ `runtime.window_ms`: blocking-work fractions, **not CPU utilization** (short
+ tasks, raster and GPU work are missing). Long tasks and LoAF overlap; never
+ add them. Unsupported totals are omitted, not zero: check
+ `runtime.long_task.supported` and `runtime.long_animation_frame.supported`.
+- `runtime.route_views.count`: live route component owners, including hidden
+ retained panes and route ancestors, not history snapshots.
+
+The sampler reads the shared UI-operation observer, whose recent-entry buffer
+holds 200 entries shared with Event Timing, so busy windows undercount
+(`runtime.blocking_work.coverage=bounded_recent_entries`); treat totals as lower
+bounds. During an explicit native memory recording, samples reuse `desktop.ts`'s
+current native sample, so check `macro.memory.status` (`current`, `stale`,
+`pending`), `macro.memory.sample_age_ms` and `macro.memory.frontend.status`
+before comparing WebKit footprints with Chromium heap estimates. Native process
+memory is collected only for explicit macOS recordings.
+
+The backend-free `resources.html` page in
+`apps/web/src/lib/core/util/runtime-browser-test` runs the real provider,
+observer and sampler; its button blocks the main thread for 150 ms, so an
+exported sample can be checked against a known long task.
+
+## Typing bursts
+
+`input.typing_burst` is one perf-class operation per field burst. It starts at
+a marked field's first `beforeinput` (joining its keyboard event when matched)
+and ends on field change, blur, hide, disposal, 750 ms without edits
+(`typing.quiet_ms`) or the shared 30 s operation limit. Fields opt in with a
+static `data-input-surface` category (`typing.surface`): the Lexical wrapper
+marks document, composer and other editors, and Command-K and grid text editors
+mark themselves. Read-only and unmarked fields never start bursts. No text, key
+values, selectors, namespaces or labels are exported.
+
+- `typing.input_count` counts edit events (including paste and composition),
+ not key presses, so it can differ from the interaction count.
+- `typing.event_{input_delay,processing,duration}_{p50,p95}_ms` summarize Event
+ Timing entries that start within the burst: entries are grouped by positive
+ `interactionId`, each metric takes the interaction's maximum, then
+ percentiles. Pointer entries and entries without an interaction id are
+ excluded (the latter counted in `typing.event_timing_unattributed_entry_count`).
+ An empty set has no percentiles, never zeros.
+- Check `typing.event_timing_supported`, `_threshold_ms` (16 ms: faster events
+ are never reported), `_entry_count`, `_interaction_count`,
+ `_dropped_timings` (any timing kind evicted from the shared 200-entry buffer,
+ not lost inputs), `_coverage` (`unsupported`, `thresholded_window`,
+ `buffer_truncated`) and `_delivery` (`available_at_finish`: a blur or timeout
+ can finish before later entries arrive) before comparing bursts.
+- The span includes the quiet boundary, so its duration is not keystroke
+ latency, and these values are not INP. `ui.event_*` describes only the
+ opening event. Do not join them with the retired
+ `typing.paint_opportunity_*` series.
+
+For local comparisons, capture CDP traces at 4× throttle with about 200 edits
+per surface and check that the text reached the intended editor. Keep short
+Command-K queries below universal-compose promotion. For large documents use
+the collaborative editor fixture described in
+[documents](documents.md) and also type in a real app document.
diff --git a/docs/development/running-locally.md b/docs/development/running-locally.md
index e37d2b5966..4cc3ad6203 100644
--- a/docs/development/running-locally.md
+++ b/docs/development/running-locally.md
@@ -52,6 +52,16 @@ For automated Linux desktop offline tests, use `nix develop .#tauri-e2e` and the
[native E2E guide](../../apps/web/tests/native/README.md). It runs the real Tauri
webview/native cache with deterministic API fixtures, without the local stack.
+Run native app probes in their own memory-capped user scope, including inspector
+and WebDriver reproductions. Renderer regressions can allocate enough memory to
+terminate unrelated agents before a stalled probe times out:
+
+```bash
+systemd-run --user --scope -p MemoryMax=6G -p MemorySwapMax=0 \
+ nix develop .#tauri-e2e --command <native-probe-command>
+```
+
+
## Run the frontend against hosted services
The web app talks to hosted `*-dev` services when you run `bun run dev` from the web app.
diff --git a/infra/stacks/monitoring/AGENTS.md b/infra/stacks/monitoring/AGENTS.md
index c78f3fef5c..59b1b8d8f3 100644
--- a/infra/stacks/monitoring/AGENTS.md
+++ b/infra/stacks/monitoring/AGENTS.md
@@ -7,6 +7,8 @@ manual and has only a prod stack, even for monitors covering both environments.
Prod threshold and anomaly monitors are in `monitors/{macrodb,redis,queues,regressions}.ts`
(`prodMonitor()` in `prod-monitor.ts`), each file with a dashboard graphing its
monitors that their messages link to; every monitor notifies through `notify.ts`.
+`dashboards/web-performance.ts` holds the web app performance dashboard with the
+APM retention filter and span-based metrics it reads; it has no monitors.
## Checks
@@ -48,6 +50,11 @@ From `infra/`:
- Do not use native committed-offset lag for the independent notification
consumers. Their per-instance log measurements preserve broadcast semantics.
- `notificationRetentionDashboardUrl` is a stack output, not an app route.
+- `dashboards/web-performance.ts` reads span attributes set by
+ `apps/web/src/observability` (the span model in
+ `docs/agent-guide/observability.md`). Renaming one there silently empties
+ its widgets. Span-based metric names and computes cannot be changed after
+ creation; add a new metric instead.
- `monitors/whatsapp-session.ts` reads log events by `telemetry_event`; its
header is the field contract with `services/whatsapp_session_service`.
Renaming a field there silently turns its monitor into missing data.
diff --git a/infra/stacks/monitoring/dashboards/web-performance.ts b/infra/stacks/monitoring/dashboards/web-performance.ts
new file mode 100644
index 0000000000..46ca888606
--- /dev/null
+++ b/infra/stacks/monitoring/dashboards/web-performance.ts
@@ -0,0 +1,205 @@
+// Web app performance: which flows are slow, for whom, and where the time goes.
+//
+// The web app exports perf-class traces for 5% of production users (see
+// docs/agent-guide/observability.md#span-model). Datadog indexes only a sample
+// of ingested spans, so this file adds a retention filter for those traces and
+// span-based metrics computed from every ingested perf span; the dashboard
+// reads the metrics. Root spans are also covered by APM trace metrics
+// (trace.Internal by resource_name and version), which need no setup.
+//
+// Every attribute named here is set by apps/web/src/observability and
+// packages/observability; renaming one there silently empties its widgets.
+import * as datadog from '@pulumi/datadog';
+import { graphGroup } from '../prod-monitor';
+
+const WEB = 'service:web-app @macro.sampling.class:perf';
+
+// Keeps every exported perf trace searchable, with the backend spans that
+// joined it. Perf traces are already sampled to 5% of production users.
+new datadog.ApmRetentionFilter('web-app-perf-traces', {
+ name: 'web-app perf traces',
+ enabled: true,
+ filterType: 'spans-sampling-processor',
+ filter: { query: WEB },
+ rate: '1.0',
+ traceRate: '1.0',
+});
+
+type GroupBy = datadog.types.input.SpansMetricGroupBy;
+
+const tag = (path: string): GroupBy => ({ path: `@${path}`, tagName: path });
+const SPLITS: GroupBy[] = [
+ { path: 'env', tagName: 'env' },
+ { path: 'resource_name', tagName: 'resource_name' },
+ tag('app.platform'),
+ tag('os.type'),
+];
+
+function distribution(
+ name: string,
+ query: string,
+ path: string,
+ groupBies: GroupBy[]
+): datadog.SpansMetric {
+ return new datadog.SpansMetric(name, {
+ name,
+ filter: { query },
+ compute: {
+ aggregationType: 'distribution',
+ path,
+ includePercentiles: true,
+ },
+ groupBies,
+ });
+}
+
+// Roots: app.boot, navigation, interactions and views that started their own
+// trace. ui.elapsed_ms is the root's duration in milliseconds.
+distribution(
+ 'macro.web.flow.elapsed_ms',
+ `${WEB} @flow.kind:*`,
+ '@ui.elapsed_ms',
+ [...SPLITS, tag('flow.kind'), tag('route.id'), tag('ui.outcome')]
+);
+// Main-thread blocking during each root (overlapping long animation frames).
+distribution(
+ 'macro.web.flow.blocking_ms',
+ `${WEB} @flow.kind:* @ui.outcome:success`,
+ '@ui.long_animation_frame_blocking_ms',
+ [...SPLITS, tag('flow.kind')]
+);
+// Every view, whether a root or a phase of a navigation. @duration is in
+// nanoseconds.
+distribution(
+ 'macro.web.view.duration',
+ `${WEB} resource_name:view.* [email protected]:cancelled [email protected]:(cancelled OR hidden OR timeout)`,
+ '@duration',
+ [...SPLITS, tag('route.id')]
+);
+// Phases that completed, by the root they belong to.
+distribution(
+ 'macro.web.phase.duration',
+ `${WEB} @flow.root:* @flow.outcome:success`,
+ '@duration',
+ [...SPLITS, tag('flow.root')]
+);
+distribution(
+ 'macro.web.runtime.js_heap_used_bytes',
+ `${WEB} resource_name:app.runtime.sample`,
+ '@macro.memory.js_heap.used_bytes',
+ [...SPLITS, tag('app.runtime')]
+);
+distribution(
+ 'macro.web.runtime.blocking_ms',
+ `${WEB} resource_name:app.runtime.sample`,
+ '@runtime.long_animation_frame.blocking_ms',
+ [...SPLITS, tag('app.runtime')]
+);
+distribution(
+ 'macro.web.typing.event_duration_p95_ms',
+ `${WEB} resource_name:input.typing_burst`,
+ '@typing.event_duration_p95_ms',
+ [...SPLITS, tag('typing.surface')]
+);
+
+const FILTER = '{env:$env.value,app.platform:$platform.value,os.type:$os.value';
+const scope = (extra = '') => `${FILTER}${extra ? `,${extra}` : ''}}`;
+const MS = ' / 1000000';
+
+function toplist(
+ title: string,
+ q: string
+): datadog.types.input.DashboardWidget {
+ return { toplistDefinition: { title, requests: [{ q }] } };
+}
+
+function lines(title: string, q: string): datadog.types.input.DashboardWidget {
+ return {
+ timeseriesDefinition: {
+ title,
+ showLegend: true,
+ requests: [{ q, displayType: 'line' }],
+ },
+ };
+}
+
+export const webPerformanceDashboard = new datadog.Dashboard(
+ 'web-performance',
+ {
+ title: 'Web app performance',
+ description:
+ 'Perf-class traces from the web and desktop app (5% of production users, rotating weekly). Declared in infra/stacks/monitoring/dashboards/web-performance.ts; span names and attributes are in docs/agent-guide/observability.md#span-model, and the perf-investigation skill drills into a slow flow.',
+ layoutType: 'ordered',
+ templateVariables: [
+ { name: 'env', prefix: 'env', default: 'prod' },
+ { name: 'platform', prefix: 'app.platform', default: '*' },
+ { name: 'os', prefix: 'os.type', default: '*' },
+ ],
+ widgets: [
+ graphGroup('Slowest flows', [
+ toplist(
+ 'Views: p75 load (ms) by route',
+ `top(p75:macro.web.view.duration${scope()} by {route.id}${MS}, 25, 'mean', 'desc')`
+ ),
+ toplist(
+ 'Views: p95 load (ms) by route',
+ `top(p95:macro.web.view.duration${scope()} by {route.id}${MS}, 25, 'mean', 'desc')`
+ ),
+ toplist(
+ 'Interactions: p95 (ms) by name',
+ `top(p95:macro.web.flow.elapsed_ms${scope('flow.kind:interaction,ui.outcome:success')} by {resource_name}, 25, 'mean', 'desc')`
+ ),
+ toplist(
+ 'Flow volume by name',
+ `top(count:macro.web.flow.elapsed_ms${scope()} by {resource_name}.as_count(), 25, 'sum', 'desc')`
+ ),
+ ]),
+ graphGroup('Boot and navigation', [
+ lines(
+ 'app.boot p75 (ms) by platform and OS',
+ `p75:macro.web.flow.elapsed_ms${scope('resource_name:app.boot,ui.outcome:success')} by {app.platform,os.type}`
+ ),
+ lines(
+ 'navigation p75 (ms) by platform and OS',
+ `p75:macro.web.flow.elapsed_ms${scope('resource_name:navigation,ui.outcome:success')} by {app.platform,os.type}`
+ ),
+ lines(
+ 'app.boot p75 (s) by app version',
+ 'p75:trace.Internal{service:web-app,env:$env.value,resource_name:app.boot} by {version}'
+ ),
+ lines(
+ 'navigation p75 (s) by app version',
+ 'p75:trace.Internal{service:web-app,env:$env.value,resource_name:navigation} by {version}'
+ ),
+ ]),
+ graphGroup('Where the time goes', [
+ toplist(
+ 'Slowest phases: p95 (ms) by phase and root',
+ `top(p95:macro.web.phase.duration${scope()} by {resource_name,flow.root}${MS}, 25, 'mean', 'desc')`
+ ),
+ toplist(
+ 'Main-thread blocking: p95 long-animation-frame ms by flow',
+ `top(p95:macro.web.flow.blocking_ms${scope()} by {resource_name}, 25, 'mean', 'desc')`
+ ),
+ lines(
+ 'Views p75 (ms) by OS',
+ `p75:macro.web.view.duration${scope()} by {os.type}${MS}`
+ ),
+ lines(
+ 'Typing: p95 event duration (ms) by surface',
+ `p95:macro.web.typing.event_duration_p95_ms${scope()} by {typing.surface}`
+ ),
+ ]),
+ graphGroup('Runtime resources (visible tabs, ~60 s samples)', [
+ lines(
+ 'JS heap used p50 / p95 (bytes) by platform',
+ `p50:macro.web.runtime.js_heap_used_bytes${scope()} by {app.platform}, p95:macro.web.runtime.js_heap_used_bytes${scope()} by {app.platform}`
+ ),
+ lines(
+ 'Long-animation-frame blocking per sample p95 (ms) by platform',
+ `p95:macro.web.runtime.blocking_ms${scope()} by {app.platform}`
+ ),
+ ]),
+ ],
+ }
+);
diff --git a/infra/stacks/monitoring/index.ts b/infra/stacks/monitoring/index.ts
index 5b3f400dae..02ff13bba9 100644
--- a/infra/stacks/monitoring/index.ts
+++ b/infra/stacks/monitoring/index.ts
@@ -27,6 +27,8 @@ import './monitors/redis';
import './monitors/regressions';
import './monitors/whatsapp-session';
import { notificationRetentionDashboard } from './monitors/notification-retention';
+import { webPerformanceDashboard } from './dashboards/web-performance';
export const notificationRetentionDashboardUrl =
notificationRetentionDashboard.url;
+export const webPerformanceDashboardUrl = webPerformanceDashboard.url;
diff --git a/nix-support/node_modules-hashes.json b/nix-support/node_modules-hashes.json
index 51a11ffdb8..470b1981ba 100644
--- a/nix-support/node_modules-hashes.json
+++ b/nix-support/node_modules-hashes.json
@@ -1,6 +1,6 @@
{
"nodeModules": {
- "aarch64-darwin": "sha256-DYQqGiu4+hooVYvTs+ov0HPeVV6GyFnVwjndsPhUmQY=",
- "x86_64-linux": "sha256-7P+xA87nIIy9+e2/UuDB0oOBcpBEE38nsrKMWJ9uC4w="
+ "aarch64-darwin": "sha256-daaUfzT3EjF5ucPvkP1G0K8J85leYVepAwIGo95/Mzk=",
+ "x86_64-linux": "sha256-Ug6LzaWhu4Ms4vNh4csy6cj6wn9C01tY3TFZ57MxXdU="
}
}
diff --git a/package.json b/package.json
index 9d2486fde1..4241264035 100644
--- a/package.json
+++ b/package.json
@@ -34,6 +34,7 @@
},
"packageManager": "[email protected]",
"patchedDependencies": {
+ "@opentelemetry/[email protected]": "apps/web/patches/opentelemetry-otlp-exporter-base-0.220.0.patch",
"@thisbeyond/[email protected]": "apps/web/patches/@thisbeyond%[email protected]",
"@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]",
"@kobalte/[email protected]": "apps/web/patches/@kobalte%[email protected]",
diff --git a/packages/collaboration/README.md b/packages/collaboration/README.md
index 1738bc4c86..c335b6d138 100644
--- a/packages/collaboration/README.md
+++ b/packages/collaboration/README.md
@@ -17,3 +17,8 @@ Shared collaboration runtime used by the web app and non-browser workers.
Browser authentication, sync HTTP endpoints, and document history UI remain in
`apps/web` because they depend on app state and browser policy.
+
+Document load callers may pass `parentSpan` to the Loro manager and sync engine.
+Seed and catch-up phases then retain their caller's trace across asynchronous
+work. These components own their child phases and never end the supplied span.
+Omitting context preserves independent instrumentation for non-view callers.
diff --git a/packages/collaboration/src/collab/engine.ts b/packages/collaboration/src/collab/engine.ts
index 0927bec5ec..f57247eeb1 100644
--- a/packages/collaboration/src/collab/engine.ts
+++ b/packages/collaboration/src/collab/engine.ts
@@ -1,5 +1,5 @@
import { type InferType, SyncDirection } from '@loro-mirror/core';
-import type { Attributes } from '@macro-inc/observability';
+import type { Attributes, Span } from '@macro-inc/observability';
import { Mutex } from 'async-mutex';
import type { VersionVector } from 'loro-crdt';
import type { ResultAsync } from 'neverthrow';
@@ -55,6 +55,7 @@ export type SyncSources = {
export type SyncEngineParams<S extends GenericRootSchema, D> = {
loroManager: SyncEngineManager<S>;
+ parentSpan?: Span;
awareness: Awareness<D>;
syncs: SyncSources;
bindings: EngineBindings<S>;
@@ -73,6 +74,7 @@ export class SyncEngine<S extends GenericRootSchema, D> {
return this._isRunning;
}
+ private readonly parentSpan?: Span;
private readonly loroManager: SyncEngineManager<S>;
private readonly awareness: Awareness<D>;
private readonly syncs: SyncSources;
@@ -97,6 +99,7 @@ export class SyncEngine<S extends GenericRootSchema, D> {
constructor({
loroManager,
+ parentSpan,
awareness,
syncs,
bindings,
@@ -106,6 +109,7 @@ export class SyncEngine<S extends GenericRootSchema, D> {
makeChatter = () => noopChatter(),
}: SyncEngineParams<S, D>) {
this.loroManager = loroManager;
+ this.parentSpan = parentSpan;
this.awareness = awareness;
this.syncs = syncs;
this.bindings = bindings;
@@ -432,7 +436,12 @@ export class SyncEngine<S extends GenericRootSchema, D> {
// The catch-up flow: "give me everything after the version I hold".
// The span shows the anchor version, what came back, and whether it
// applied — the trail for "client was stale and (never) reconciled".
- const span = telemetrySpan(this.syncs.live.documentId, 'doc.sync.catchup');
+ const span = telemetrySpan(
+ this.syncs.live.documentId,
+ 'doc.sync.catchup',
+ undefined,
+ this.parentSpan
+ );
span.setAttr('since.version', vvAttr(since));
span.setAttr('attempt', attempt);
this.log('debug', `engine: requestUpdatesSince (attempt ${attempt})`);
diff --git a/packages/collaboration/src/collab/manager.ts b/packages/collaboration/src/collab/manager.ts
index d71650d06b..f7f900ffa7 100644
--- a/packages/collaboration/src/collab/manager.ts
+++ b/packages/collaboration/src/collab/manager.ts
@@ -4,6 +4,7 @@ import {
SyncDirection,
type UpdateMetadata,
} from '@loro-mirror/core';
+import type { Span } from '@macro-inc/observability';
import {
type Container,
type ContainerID,
@@ -54,6 +55,8 @@ export type SnapshotIngest =
export type LoroManagerOptions = {
documentId: string;
+ /** Caller-owned initial document flow, never ended by the manager. */
+ parentSpan?: Span;
/**
* Keep a JSON mirror of the schema's state and report it through
* `onStateChange` (the default). Editors that read the LoroDoc directly
@@ -575,40 +578,45 @@ export class LoroManager<S extends GenericRootSchema = GenericRootSchema>
// The winner of the snapshot race seeds the doc; its kind, size, and
// resulting version are the anchor every later sync question ("since
// what?") is asked against.
- return telemetrySpan(this.options.documentId, 'doc.seed', async (span) => {
- span.setAttr('seed.kind', input.kind);
- span.setAttr('snapshot.bytes', input.snapshot.length);
- const initResult = await this.initializeFromSnapshot(input.snapshot);
- if (initResult.isErr()) {
- logSyncService({
- documentId: this.options.documentId,
- level: 'error',
- context: {},
- message: `ingest(${input.kind}): seed failed`,
- });
- span.error(`seed from ${input.kind} snapshot failed`);
- return false;
- }
-
- // WAL entries are causally anchored to the local snapshot, so they're only
- // safe to replay on top of the local seed we just applied.
- if (input.kind === 'local' && input.walUpdates?.length) {
- span.setAttr('wal.replayed', input.walUpdates.length);
- const replayResult = this.importBatchUpdates(input.walUpdates);
- if (replayResult.isErr()) {
+ return telemetrySpan(
+ this.options.documentId,
+ 'doc.seed',
+ async (span) => {
+ span.setAttr('seed.kind', input.kind);
+ span.setAttr('snapshot.bytes', input.snapshot.length);
+ const initResult = await this.initializeFromSnapshot(input.snapshot);
+ if (initResult.isErr()) {
logSyncService({
documentId: this.options.documentId,
level: 'error',
context: {},
- message: `ingest(${input.kind}): WAL replay failed`,
+ message: `ingest(${input.kind}): seed failed`,
});
- span.error('WAL replay onto local seed failed');
+ span.error(`seed from ${input.kind} snapshot failed`);
+ return false;
}
- }
- span.setAttr('version.after', frontiersAttr(this._doc));
- return true;
- });
+ // WAL entries are causally anchored to the local snapshot, so they're only
+ // safe to replay on top of the local seed we just applied.
+ if (input.kind === 'local' && input.walUpdates?.length) {
+ span.setAttr('wal.replayed', input.walUpdates.length);
+ const replayResult = this.importBatchUpdates(input.walUpdates);
+ if (replayResult.isErr()) {
+ logSyncService({
+ documentId: this.options.documentId,
+ level: 'error',
+ context: {},
+ message: `ingest(${input.kind}): WAL replay failed`,
+ });
+ span.error('WAL replay onto local seed failed');
+ }
+ }
+
+ span.setAttr('version.after', frontiersAttr(this._doc));
+ return true;
+ },
+ this.options.parentSpan
+ );
}
/** Tear down subscriptions and free the underlying doc. */
diff --git a/packages/collaboration/src/collab/telemetry.test.ts b/packages/collaboration/src/collab/telemetry.test.ts
index d98e605c04..9ca3446791 100644
--- a/packages/collaboration/src/collab/telemetry.test.ts
+++ b/packages/collaboration/src/collab/telemetry.test.ts
@@ -1,4 +1,4 @@
-import { type Span, Telemetry } from '@macro-inc/observability';
+import { NOOP_SPAN, type Span, Telemetry } from '@macro-inc/observability';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { disposeTelemetryFor, telemetrySpan } from './telemetry';
@@ -47,3 +47,19 @@ describe('telemetrySpan', () => {
expect(span.setAttr).toHaveBeenCalledWith('session.id', expect.any(String));
});
});
+
+test('creates document phases from an explicit caller without an ambient root', async () => {
+ const child = NOOP_SPAN;
+ const parent = NOOP_SPAN;
+ const makeChild = vi.spyOn(parent, 'span');
+ const ambient = vi.spyOn(Telemetry, 'span');
+ const phase = telemetrySpan(
+ documentId,
+ 'doc.sync.catchup',
+ undefined,
+ parent
+ );
+ expect(phase).toBe(child);
+ expect(makeChild).toHaveBeenCalledWith('doc.sync.catchup');
+ expect(ambient).not.toHaveBeenCalled();
+});
diff --git a/packages/collaboration/src/collab/telemetry.ts b/packages/collaboration/src/collab/telemetry.ts
index 22305cf063..a2f49ab43b 100644
--- a/packages/collaboration/src/collab/telemetry.ts
+++ b/packages/collaboration/src/collab/telemetry.ts
@@ -37,25 +37,35 @@ function setDocumentSpanAttributes(documentId: string, span: Span): void {
}
}
+// The span-returning overload comes first: with strictNullChecks off
+// (ai-editing-worker), `undefined` would otherwise match the async one.
+export function telemetrySpan(
+ documentId: string,
+ name: string,
+ operation?: undefined,
+ parentSpan?: Span
+): Span;
export function telemetrySpan<T>(
documentId: string,
name: string,
- operation: SpanOperation<T>
+ operation: SpanOperation<T>,
+ parentSpan?: Span
): Promise<T>;
-export function telemetrySpan(documentId: string, name: string): Span;
export function telemetrySpan<T>(
documentId: string,
name: string,
- operation?: SpanOperation<T>
+ operation?: SpanOperation<T>,
+ parentSpan?: Span
): Span | Promise<T> {
+ const tracer = parentSpan ?? Telemetry;
if (operation) {
- return Telemetry.span(name, async (span) => {
+ return tracer.span(name, async (span) => {
setDocumentSpanAttributes(documentId, span);
return operation(span);
});
}
- const span = Telemetry.span(name);
+ const span = tracer.span(name);
setDocumentSpanAttributes(documentId, span);
return span;
}
diff --git a/packages/observability/README.md b/packages/observability/README.md
new file mode 100644
index 0000000000..754f5716dc
--- /dev/null
+++ b/packages/observability/README.md
@@ -0,0 +1,32 @@
+# Observability
+
+`Telemetry.init` shares tracing, logs, runtime identity and sampling decisions.
+Native startup can register immediately and resolve recording settings and
+collector URLs asynchronously.
+
+Sampling is per class and generic: the application passes
+`sampling: Record<Class, number>` and a `samplingKey`, and registers its class
+names by augmenting `TelemetryRegister`. At enablement each class is kept when
+`hash(samplingKey() + class) < rate`; explicit recordings keep every class.
+`Telemetry.span(name, { sampling })` puts a span in a class. A span joins its
+parent's trace when that trace is exported; otherwise a phase (`span.span`) is
+dropped with it, and any other span starts its own trace when its class is
+kept (a span without a class always is) and is dropped when it is not. Spans
+buffered before enablement are placed at export, moving those that leave a
+dropped trace to a new trace id. Every span in a classed trace is exported with
+`macro.sampling.class` and `macro.sampling.rate`.
+
+Browser runtimes can supply `exportFetch` independently of their authenticated
+application transport. The web app uses its captured webview fetch with omitted
+credentials for both trace and log exports, including collectors discovered during
+native startup. Collector CORS rules apply; rejected exports never fall back to
+the native cookie jar.
+
+The pinned OTLP exporter-base patch adds explicit fetch injection to its browser
+transport. It preserves the upstream serializers, retry, timeout, batching and
+keepalive rules. The injected fetch takes precedence over global fetch discovery.
+
+Run `bun run test` and `bun run type-check` here. `bun run test:browser` exercises
+the real browser exporters against a local CORS collector, including startup
+recordings, trace/log delivery, retries, cookie omission and CORS refusal. Set
+`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to an installed Chrome if needed.
diff --git a/packages/observability/browser-test/export.browser.e2e.ts b/packages/observability/browser-test/export.browser.e2e.ts
new file mode 100644
index 0000000000..4854700247
--- /dev/null
+++ b/packages/observability/browser-test/export.browser.e2e.ts
@@ -0,0 +1,96 @@
+import { createServer, type IncomingHttpHeaders } from 'node:http';
+import { expect, test } from '@playwright/test';
+import type {} from './main';
+
+for (const cors of [true, false]) {
+ test(`export uses the configured webview collector with CORS ${cors ? 'allowed' : 'denied'}`, async ({
+ page,
+ context,
+ }) => {
+ const requests: {
+ path: string;
+ headers: IncomingHttpHeaders;
+ body: string;
+ }[] = [];
+ const attempts = new Map<string, number>();
+ const server = createServer((request, response) => {
+ if (cors) {
+ response.setHeader('Access-Control-Allow-Origin', '*');
+ response.setHeader('Access-Control-Allow-Headers', 'content-type');
+ response.setHeader('Access-Control-Allow-Methods', 'POST,OPTIONS');
+ }
+ if (request.method === 'OPTIONS') {
+ response.writeHead(204).end();
+ return;
+ }
+ let body = '';
+ request.setEncoding('utf8');
+ request.on('data', (chunk: string) => {
+ body += chunk;
+ });
+ request.on('end', () => {
+ const path = request.url ?? '';
+ const count = (attempts.get(path) ?? 0) + 1;
+ attempts.set(path, count);
+ requests.push({ path, headers: request.headers, body });
+ response.setHeader('Content-Type', 'application/json');
+ if (count === 1) {
+ response.setHeader('Retry-After', '0');
+ response.writeHead(503).end('{}');
+ } else response.writeHead(200).end('{}');
+ });
+ });
+ await new Promise<void>((resolve) =>
+ server.listen(0, '127.0.0.1', resolve)
+ );
+ const address = server.address();
+ if (!address || typeof address === 'string')
+ throw new Error('No collector');
+ try {
+ await context.addCookies([
+ {
+ name: 'probe-session',
+ value: 'private',
+ domain: '127.0.0.1',
+ path: '/',
+ },
+ ]);
+ await page.goto('/');
+ await page.waitForFunction(
+ () => typeof window.runExporterProbe === 'function'
+ );
+ const result = await page.evaluate(
+ (collector) => window.runExporterProbe(collector),
+ `http://127.0.0.1:${address.port}`
+ );
+ expect(result.nativeCalls).toBe(0);
+ expect(result.requests.length).toBeGreaterThan(0);
+ expect(
+ result.requests.every((request) => request.credentials === 'omit')
+ ).toBe(true);
+ expect(result.requests.every((request) => request.mode === 'cors')).toBe(
+ true
+ );
+ expect(result.failed).toBe(!cors);
+ if (!cors) {
+ expect(requests).toHaveLength(0);
+ return;
+ }
+ expect(attempts.get('/v1/traces')).toBeGreaterThanOrEqual(2);
+ expect(attempts.get('/v1/logs')).toBeGreaterThanOrEqual(2);
+ expect(
+ requests.every((request) => request.headers.cookie === undefined)
+ ).toBe(true);
+ const traces = requests.find((request) => request.path === '/v1/traces');
+ const logs = requests.find((request) => request.path === '/v1/logs');
+ expect(traces?.body).toContain('export.early');
+ expect(traces?.body).toContain('export.ready');
+ expect(logs?.body).toContain('export.log');
+ } finally {
+ server.closeAllConnections();
+ await new Promise<void>((resolve, reject) =>
+ server.close((error) => (error ? reject(error) : resolve()))
+ );
+ }
+ });
+}
diff --git a/packages/observability/browser-test/index.html b/packages/observability/browser-test/index.html
new file mode 100644
index 0000000000..fd7f587503
--- /dev/null
+++ b/packages/observability/browser-test/index.html
@@ -0,0 +1,5 @@
+<!doctype html>
+<html lang="en">
+ <head><meta charset="utf-8" /><title>Telemetry transport probe</title></head>
+ <body><script type="module" src="/main.ts"></script></body>
+</html>
diff --git a/packages/observability/browser-test/main.ts b/packages/observability/browser-test/main.ts
new file mode 100644
index 0000000000..058e0a82e6
--- /dev/null
+++ b/packages/observability/browser-test/main.ts
@@ -0,0 +1,80 @@
+import type {
+ TelemetryInitConfig,
+ TelemetryStartupOptions,
+} from '../src/config';
+import { Telemetry } from '../src/index';
+import { createWebTracingProvider } from '../src/web';
+
+export interface ProbeResult {
+ nativeCalls: number;
+ failed: boolean;
+ requests: {
+ url: string;
+ credentials?: RequestCredentials;
+ mode?: RequestMode;
+ }[];
+}
+
+declare global {
+ interface Window {
+ runExporterProbe: (collector: string) => Promise<ProbeResult>;
+ }
+}
+
+window.runExporterProbe = async (collector) => {
+ const browserFetch = globalThis.fetch.bind(globalThis);
+ const result: ProbeResult = { nativeCalls: 0, failed: false, requests: [] };
+ const rejectNativeFetch = async () => {
+ result.nativeCalls++;
+ throw new Error(
+ 'Telemetry reached the authenticated application transport'
+ );
+ };
+ globalThis.fetch = Object.assign(rejectNativeFetch, browserFetch);
+ const startup = Promise.resolve().then(
+ (): TelemetryStartupOptions => ({
+ recording: true,
+ tracesUrl: `${collector}/v1/traces`,
+ logsUrl: `${collector}/v1/logs`,
+ })
+ );
+ const config: TelemetryInitConfig = {
+ serviceName: 'webview-export-probe',
+ environment: 'test',
+ enabled: async () => true,
+ sampling: { perf: 0 },
+ samplingKey: () => 'webview-export-probe',
+ tracesUrl: 'http://invalid.example/fallback/v1/traces',
+ logsUrl: 'http://invalid.example/fallback/v1/logs',
+ startup,
+ exportFetch: (input, init) => {
+ const options: RequestInit = { ...init, credentials: 'omit' };
+ result.requests.push({
+ url: String(input),
+ credentials: options.credentials,
+ mode: options.mode,
+ });
+ return browserFetch(input, options);
+ },
+ };
+ try {
+ const ready = Telemetry.init({
+ ...config,
+ tracingProvider: (resource, getUserId, sampling) =>
+ createWebTracingProvider(config, resource, getUserId, sampling),
+ });
+ Telemetry.span('export.early', { sampling: 'perf' }).end();
+ await ready;
+ Telemetry.span('export.ready', { sampling: 'perf' }).end();
+ Telemetry.info('export.log');
+ await Telemetry.flush();
+ } catch {
+ result.failed = true;
+ } finally {
+ await Telemetry.shutdown().catch(() => {
+ result.failed = true;
+ });
+ globalThis.fetch = browserFetch;
+ }
+ return result;
+};
diff --git a/packages/observability/browser-test/playwright.config.ts b/packages/observability/browser-test/playwright.config.ts
new file mode 100644
index 0000000000..9397cbd74a
--- /dev/null
+++ b/packages/observability/browser-test/playwright.config.ts
@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from '@playwright/test';
+
+const port = Number(process.env.OTLP_BROWSER_PORT ?? 33428);
+export default defineConfig({
+ testDir: fileURLToPath(new URL('.', import.meta.url)),
+ testMatch: '*.browser.e2e.ts',
+ workers: 1,
+ reporter: 'line',
+ use: {
+ baseURL: `http://127.0.0.1:${port}`,
+ launchOptions: {
+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+ },
+ },
+ webServer: {
+ command: `bunx vite --config browser-test/vite.config.ts --port ${port} --strictPort`,
+ cwd: fileURLToPath(new URL('..', import.meta.url)),
+ url: `http://127.0.0.1:${port}`,
+ },
+});
diff --git a/packages/observability/browser-test/vite.config.ts b/packages/observability/browser-test/vite.config.ts
new file mode 100644
index 0000000000..747e2e9b41
--- /dev/null
+++ b/packages/observability/browser-test/vite.config.ts
@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ root: fileURLToPath(new URL('.', import.meta.url)),
+ cacheDir: fileURLToPath(
+ new URL('../node_modules/.vite/browser-test', import.meta.url)
+ ),
+ server: { host: '127.0.0.1' },
+});
diff --git a/packages/observability/package.json b/packages/observability/package.json
index e56f1762f6..41464ff386 100644
--- a/packages/observability/package.json
+++ b/packages/observability/package.json
@@ -7,19 +7,18 @@
".": "./src/index.ts",
"./core": "./src/core.ts",
"./web": "./src/web.ts",
- "./worker": "./src/worker.ts",
- "./zone": "./src/zone.ts"
+ "./worker": "./src/worker.ts"
},
"scripts": {
"lint": "biome check .",
"test": "vitest run --config vitest.config.ts",
- "type-check": "tsc --noEmit --project tsconfig.json"
+ "type-check": "tsc --noEmit --project tsconfig.json",
+ "test:browser": "playwright test --config browser-test/playwright.config.ts"
},
"dependencies": {
"@microlabs/otel-cf-workers": "^1.0.0-rc.52",
"@opentelemetry/api": "^1.9.1",
"@opentelemetry/api-logs": "^0.220.0",
- "@opentelemetry/context-zone": "^2.9.0",
"@opentelemetry/core": "^2.9.0",
"@opentelemetry/exporter-logs-otlp-http": "^0.220.0",
"@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
@@ -34,6 +33,8 @@
"@types/node": "^24.8.0",
"jsdom": "^26.1.0",
"typescript": "^5.9.3",
- "vitest": "5.0.1"
+ "vitest": "5.0.1",
+ "@playwright/test": "1.62.0",
+ "vite": "^6.4.1"
}
}
diff --git a/packages/observability/src/config.ts b/packages/observability/src/config.ts
index 70345a824a..c3af2ba458 100644
--- a/packages/observability/src/config.ts
+++ b/packages/observability/src/config.ts
@@ -2,31 +2,77 @@ import type {
ContextManager,
AttributeValue as OtelAttributeValue,
} from '@opentelemetry/api';
+import type { DetectedResourceAttributes } from '@opentelemetry/resources';
import type { TelemetryTracingProviderFactory } from './provider';
+import type { SamplingClass, TraceSampling } from './sampling';
export type Attribute = OtelAttributeValue;
export type Attributes = Record<string, Attribute | undefined>;
export type LogAttributes = Attributes;
+export type ResourceAttributes = DetectedResourceAttributes;
-export interface TelemetryInitConfig {
+/** Native diagnostic settings discovered after the tracing provider registers. */
+export interface TelemetryStartupOptions {
+ tracesUrl?: string;
+ logsUrl?: string;
+ recording: boolean;
+}
+
+/**
+ * Per-class sampling. Each class is kept for a share of users, decided once
+ * per user per class at enablement; spans that ask for no class are kept.
+ */
+export type TelemetrySamplingConfig<Classes extends string> =
+ | {
+ /** Share of users, 0 to 1, whose traces of each class are exported. */
+ sampling: Readonly<Record<Classes, number>>;
+ /** The stable identity a decision is made for, read at enablement. */
+ samplingKey: () => string;
+ }
+ | { sampling?: undefined; samplingKey?: undefined };
+
+export type TelemetryInitConfig<Classes extends string = SamplingClass> =
+ TelemetryBaseConfig & TelemetrySamplingConfig<Classes>;
+
+interface TelemetryBaseConfig {
serviceName: string;
environment: string;
tracesUrl?: string;
logsUrl?: string;
contextManager?: ContextManager;
+ /** Browser export transport, independent of authenticated application HTTP. */
+ exportFetch?: (
+ input: RequestInfo | URL,
+ init?: RequestInit
+ ) => Promise<Response>;
tracingProvider?: TelemetryTracingProviderFactory;
/** Stable identity shared by this runtime's traces and logs. */
- resourceAttributes?: Attributes;
+ resourceAttributes?: ResourceAttributes;
/** Snapshot of live diagnostics, read synchronously at span start/end. */
spanAttributes?: () => Attributes;
- /** Explicit diagnostic recordings capture all emitted spans. */
+ /** Explicit diagnostic recordings keep every sampling class. */
recording?: boolean;
+ /** Resolve exporter and recording settings without blocking provider registration. */
+ startup?: Promise<TelemetryStartupOptions>;
enabled: () => Promise<boolean>;
}
/** Mutable attributes applied to telemetry created after they change. */
export class TelemetryRuntimeConfig {
#userId: string | undefined;
+ readonly #sampling: TraceSampling;
+
+ constructor(sampling: TraceSampling) {
+ this.#sampling = sampling;
+ }
+
+ /**
+ * Whether this runtime exports traces of a sampling class. False until the
+ * class is decided at enablement, and while telemetry is disabled.
+ */
+ sampled(samplingClass: SamplingClass): boolean {
+ return this.#sampling.kept(samplingClass) === true;
+ }
get userId(): string | undefined {
return this.#userId;
diff --git a/packages/observability/src/constants.ts b/packages/observability/src/constants.ts
index 85010dd888..01b44c5a94 100644
--- a/packages/observability/src/constants.ts
+++ b/packages/observability/src/constants.ts
@@ -1,4 +1,8 @@
-export const INSTRUMENTATION_SCOPE_NAME = "@macro-inc/observability";
-export const ATTR_USER_ID = "usr.id";
-export const ATTR_DEPLOYMENT_ENVIRONMENT = "deployment.environment";
-export const CONSOLE_PREFIX = "[observability]";
+export const INSTRUMENTATION_SCOPE_NAME = '@macro-inc/observability';
+export const ATTR_USER_ID = 'usr.id';
+export const ATTR_DEPLOYMENT_ENVIRONMENT = 'deployment.environment';
+export const CONSOLE_PREFIX = '[observability]';
+/** The sampling class that exported a span, on every span in a classed trace. */
+export const ATTR_SAMPLING_CLASS = 'macro.sampling.class';
+/** That class's rate, 0 to 1: weight a span by its inverse to count all sessions. */
+export const ATTR_SAMPLING_RATE = 'macro.sampling.rate';
diff --git a/packages/observability/src/core.ts b/packages/observability/src/core.ts
index 8a43a80583..9af23d3ced 100644
--- a/packages/observability/src/core.ts
+++ b/packages/observability/src/core.ts
@@ -1,13 +1,22 @@
export type {
- Attribute,
- Attributes,
- LogAttributes,
- TelemetryInitConfig,
-} from "./config";
-export { TelemetryRuntimeConfig } from "./config";
+ Attribute,
+ Attributes,
+ LogAttributes,
+ ResourceAttributes,
+ TelemetryInitConfig,
+ TelemetryStartupOptions,
+} from './config';
+export { TelemetryRuntimeConfig } from './config';
export type {
- TelemetryTracingProvider,
- TelemetryTracingProviderFactory,
-} from "./provider";
-export type { Span } from "./span";
-export { Telemetry } from "./telemetry";
+ TelemetryTracingProvider,
+ TelemetryTracingProviderFactory,
+} from './provider';
+export type {
+ SamplingClass,
+ TelemetryRegister,
+ TraceSampling,
+} from './sampling';
+export type { Span, TraceContext } from './span';
+export { NOOP_SPAN } from './span-noop';
+export { Telemetry } from './telemetry';
+export type { SpanOptions } from './tracing';
diff --git a/packages/observability/src/deferred-span-processor.test.ts b/packages/observability/src/deferred-span-processor.test.ts
new file mode 100644
index 0000000000..7cf9945281
--- /dev/null
+++ b/packages/observability/src/deferred-span-processor.test.ts
@@ -0,0 +1,79 @@
+import { ROOT_CONTEXT } from '@opentelemetry/api';
+import {
+ BasicTracerProvider,
+ InMemorySpanExporter,
+ SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { expect, test, vi } from 'vitest';
+import { DeferredSpanProcessor } from './deferred-span-processor';
+
+test('retains early parentage but exports nothing until enabled', async () => {
+ let decide: (allowed: boolean) => void = () => {};
+ const decision = new Promise<boolean>((resolve) => {
+ decide = resolve;
+ });
+ const exporter = new InMemorySpanExporter();
+ const create = vi.fn(() => new SimpleSpanProcessor(exporter));
+ const processor = new DeferredSpanProcessor(decision, create);
+ const provider = new BasicTracerProvider({ spanProcessors: [processor] });
+ const root = provider
+ .getTracer('test')
+ .startSpan('app.boot', {}, ROOT_CONTEXT);
+ root.end();
+ expect(create).not.toHaveBeenCalled();
+ expect(exporter.getFinishedSpans()).toHaveLength(0);
+ decide(true);
+ await processor.forceFlush();
+ expect(exporter.getFinishedSpans().map((span) => span.name)).toEqual([
+ 'app.boot',
+ ]);
+ await provider.shutdown();
+});
+
+test.each(['denied', 'failed', 'shutdown'] as const)(
+ 'drops early spans when %s',
+ async (outcome) => {
+ let decide: (allowed: boolean) => void = () => {};
+ let reject: (error: Error) => void = () => {};
+ const decision = new Promise<boolean>((resolve, fail) => {
+ decide = resolve;
+ reject = fail;
+ });
+ const create = vi.fn(
+ () => new SimpleSpanProcessor(new InMemorySpanExporter())
+ );
+ const processor = new DeferredSpanProcessor(decision, create);
+ const provider = new BasicTracerProvider({ spanProcessors: [processor] });
+ provider.getTracer('test').startSpan('early').end();
+ if (outcome === 'shutdown') await processor.shutdown();
+ if (outcome === 'failed') reject(new Error('unavailable'));
+ else decide(outcome === 'shutdown');
+ await processor.forceFlush();
+ provider.getTracer('test').startSpan('late').end();
+ expect(create).not.toHaveBeenCalled();
+ await provider.shutdown();
+ }
+);
+
+test('shuts down a processor whose asynchronous creation completes after disposal', async () => {
+ let finish: (processor: SimpleSpanProcessor) => void = () => {};
+ let started: () => void = () => {};
+ const creating = new Promise<void>((resolve) => {
+ started = resolve;
+ });
+ const exporter = new InMemorySpanExporter();
+ const inner = new SimpleSpanProcessor(exporter);
+ const shutdown = vi.spyOn(inner, 'shutdown');
+ const processor = new DeferredSpanProcessor(Promise.resolve(true), () => {
+ started();
+ return new Promise<SimpleSpanProcessor>((resolve) => {
+ finish = resolve;
+ });
+ });
+ await creating;
+ await processor.shutdown();
+ finish(inner);
+ await processor.forceFlush();
+ expect(shutdown).toHaveBeenCalledOnce();
+ expect(exporter.getFinishedSpans()).toHaveLength(0);
+});
diff --git a/packages/observability/src/deferred-span-processor.ts b/packages/observability/src/deferred-span-processor.ts
new file mode 100644
index 0000000000..65dd611e6f
--- /dev/null
+++ b/packages/observability/src/deferred-span-processor.ts
@@ -0,0 +1,65 @@
+import type { Context } from '@opentelemetry/api';
+import type {
+ ReadableSpan,
+ Span,
+ SpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+
+/** Keep early spans in memory; never construct an exporter before consent. */
+export class DeferredSpanProcessor implements SpanProcessor {
+ #pending: ReadableSpan[] = [];
+ #processor: SpanProcessor | undefined;
+ #closed = false;
+ readonly #ready: Promise<void>;
+
+ constructor(
+ enabled: Promise<boolean>,
+ create: () => SpanProcessor | Promise<SpanProcessor>
+ ) {
+ this.#ready = this.#initialize(enabled, create);
+ }
+
+ async #initialize(
+ enabled: Promise<boolean>,
+ create: () => SpanProcessor | Promise<SpanProcessor>
+ ) {
+ let allowed = false;
+ try {
+ allowed = await enabled;
+ if (!this.#closed && allowed) {
+ const processor = await create();
+ if (this.#closed) await processor.shutdown();
+ else {
+ this.#processor = processor;
+ for (const span of this.#pending) processor.onEnd(span);
+ }
+ }
+ } catch {
+ // Unavailable consent or startup settings must fail closed.
+ allowed = false;
+ }
+ this.#pending = [];
+ if (!allowed) this.#closed = true;
+ }
+
+ onStart(span: Span, parent: Context): void {
+ this.#processor?.onStart(span, parent);
+ }
+
+ onEnd(span: ReadableSpan): void {
+ if (this.#closed) return;
+ if (this.#processor) this.#processor.onEnd(span);
+ else if (this.#pending.length < 2048) this.#pending.push(span);
+ }
+
+ async forceFlush(): Promise<void> {
+ await this.#ready;
+ await this.#processor?.forceFlush();
+ }
+
+ async shutdown(): Promise<void> {
+ this.#closed = true;
+ this.#pending = [];
+ await this.#processor?.shutdown();
+ }
+}
diff --git a/packages/observability/src/index.ts b/packages/observability/src/index.ts
index cf304f99e2..49968d4d75 100644
--- a/packages/observability/src/index.ts
+++ b/packages/observability/src/index.ts
@@ -1,9 +1,14 @@
export type {
- Attribute,
- Attributes,
- LogAttributes,
- TelemetryInitConfig,
-} from "./config";
-export { TelemetryRuntimeConfig } from "./config";
-export type { Span } from "./span";
-export { Telemetry } from "./telemetry";
+ Attribute,
+ Attributes,
+ LogAttributes,
+ ResourceAttributes,
+ TelemetryInitConfig,
+ TelemetryStartupOptions,
+} from './config';
+export { TelemetryRuntimeConfig } from './config';
+export type { SamplingClass, TelemetryRegister } from './sampling';
+export type { Span, TraceContext } from './span';
+export { NOOP_SPAN } from './span-noop';
+export { Telemetry } from './telemetry';
+export type { SpanOptions } from './tracing';
diff --git a/packages/observability/src/logging.test.ts b/packages/observability/src/logging.test.ts
index 931635c8e3..a480af1adb 100644
--- a/packages/observability/src/logging.test.ts
+++ b/packages/observability/src/logging.test.ts
@@ -3,10 +3,10 @@ import { context, ROOT_CONTEXT } from '@opentelemetry/api';
import { logs } from '@opentelemetry/api-logs';
import { resourceFromAttributes } from '@opentelemetry/resources';
import type { InMemoryLogRecordExporter } from '@opentelemetry/sdk-logs';
+import { StackContextManager } from '@opentelemetry/sdk-trace-web';
import { afterEach, expect, test, vi } from 'vitest';
import { Logging } from './logging';
import { suppressUserId } from './privacy';
-import { ZoneContextManager } from './zone';
const exporters: InMemoryLogRecordExporter[] = [];
vi.mock('@opentelemetry/exporter-logs-otlp-http', async () => {
@@ -27,7 +27,7 @@ afterEach(() => {
});
test('the production log provider suppresses identity only in anonymous contexts', async () => {
- context.setGlobalContextManager(new ZoneContextManager().enable());
+ context.setGlobalContextManager(new StackContextManager().enable());
const logging = new Logging();
logging.init(
{
diff --git a/packages/observability/src/logging.ts b/packages/observability/src/logging.ts
index 300288f858..9889d2c5cf 100644
--- a/packages/observability/src/logging.ts
+++ b/packages/observability/src/logging.ts
@@ -26,7 +26,7 @@ export class Logging {
readonly #logger: Logger = logs.getLogger(INSTRUMENTATION_SCOPE_NAME);
init(
- config: TelemetryInitConfig,
+ config: TelemetryInitConfig<string>,
resource: Resource,
getUserId: () => string | undefined
): void {
@@ -44,7 +44,10 @@ export class Logging {
shutdown: () => Promise.resolve(),
},
new BatchLogRecordProcessor({
- exporter: new OTLPLogExporter({ url: config.logsUrl }),
+ exporter: new OTLPLogExporter({
+ url: config.logsUrl,
+ fetch: config.exportFetch,
+ }),
}),
],
});
diff --git a/packages/observability/src/provider.ts b/packages/observability/src/provider.ts
index 2893cfa0f3..2418e08149 100644
--- a/packages/observability/src/provider.ts
+++ b/packages/observability/src/provider.ts
@@ -1,14 +1,17 @@
-import type { TracerProvider } from "@opentelemetry/api";
-import type { Resource } from "@opentelemetry/resources";
+import type { TracerProvider } from '@opentelemetry/api';
+import type { Resource } from '@opentelemetry/resources';
+import type { TraceSampling } from './sampling';
/** A runtime-specific OpenTelemetry tracer provider. */
export type TelemetryTracingProvider = TracerProvider & {
- forceFlush(): Promise<void>;
- shutdown(): Promise<void>;
+ forceFlush(): Promise<void>;
+ shutdown(): Promise<void>;
};
-/** Creates a tracer provider after telemetry has been enabled. */
+/** Creates a tracer provider; buffered providers gate exporters on enablement. */
export type TelemetryTracingProviderFactory = (
- resource: Resource,
- getUserId: () => string | undefined,
+ resource: Resource,
+ getUserId: () => string | undefined,
+ /** Samples spans and decides, once its classes are decided, which to export. */
+ sampling: TraceSampling
) => TelemetryTracingProvider;
diff --git a/packages/observability/src/sampling.test.ts b/packages/observability/src/sampling.test.ts
new file mode 100644
index 0000000000..cd949240e7
--- /dev/null
+++ b/packages/observability/src/sampling.test.ts
@@ -0,0 +1,57 @@
+import { expect, test, vi } from 'vitest';
+import { keepsClass } from './sampling';
+import { Telemetry } from './telemetry';
+
+test('a key makes the same decision for a class every time', () => {
+ expect(keepsClass('user-1:2900', 'perf', 0.05)).toBe(
+ keepsClass('user-1:2900', 'perf', 0.05)
+ );
+ expect(keepsClass('user-1:2900', 'perf', 0)).toBe(false);
+ expect(keepsClass('user-1:2900', 'perf', 1)).toBe(true);
+});
+
+test('a rate keeps that share of keys, independently for each class', () => {
+ const keys = Array.from({ length: 20_000 }, (_, index) => `user-${index}`);
+ const perf = keys.filter((key) => keepsClass(key, 'perf', 0.05));
+ expect(perf.length / keys.length).toBeGreaterThan(0.045);
+ expect(perf.length / keys.length).toBeLessThan(0.055);
+ const both = keys.filter(
+ (key) => keepsClass(key, 'perf', 0.5) && keepsClass(key, 'always', 0.5)
+ );
+ expect(both.length / keys.length).toBeGreaterThan(0.23);
+ expect(both.length / keys.length).toBeLessThan(0.27);
+});
+
+test('the rotating salt in a key moves a user between cohorts', () => {
+ const keys = Array.from({ length: 2_000 }, (_, index) => `user-${index}`);
+ const thisWeek = keys.filter((key) =>
+ keepsClass(`${key}:2900`, 'perf', 0.05)
+ );
+ const nextWeek = thisWeek.filter((key) =>
+ keepsClass(`${key}:2901`, 'perf', 0.05)
+ );
+ expect(nextWeek.length).toBeLessThan(thisWeek.length / 2);
+});
+
+test('classes are decided from the sampling key read at enablement', async () => {
+ let enable: (enabled: boolean) => void = () => {};
+ const enabled = new Promise<boolean>((resolve) => {
+ enable = resolve;
+ });
+ const samplingKey = vi.fn(() => 'user-1:2900');
+ const initialization = Telemetry.init({
+ serviceName: 'test',
+ environment: 'test',
+ enabled: () => enabled,
+ sampling: { always: 1, never: 0 },
+ samplingKey,
+ });
+ await Promise.resolve();
+ expect(samplingKey).not.toHaveBeenCalled();
+ expect(Telemetry.config.sampled('always')).toBe(false);
+ enable(true);
+ await initialization;
+ expect(samplingKey).toHaveBeenCalledOnce();
+ expect(Telemetry.config.sampled('always')).toBe(true);
+ expect(Telemetry.config.sampled('never')).toBe(false);
+});
diff --git a/packages/observability/src/sampling.ts b/packages/observability/src/sampling.ts
new file mode 100644
index 0000000000..313a90c707
--- /dev/null
+++ b/packages/observability/src/sampling.ts
@@ -0,0 +1,302 @@
+import {
+ type Context,
+ createContextKey,
+ INVALID_SPAN_CONTEXT,
+ type SpanContext,
+ TraceFlags,
+ trace,
+} from '@opentelemetry/api';
+import {
+ type ReadableSpan,
+ type Sampler,
+ SamplingDecision,
+ type SamplingResult,
+} from '@opentelemetry/sdk-trace-base';
+import { ATTR_SAMPLING_CLASS, ATTR_SAMPLING_RATE } from './constants';
+
+/**
+ * Applications name their sampling classes by augmenting this interface:
+ *
+ * ```ts
+ * declare module '@macro-inc/observability' {
+ * interface TelemetryRegister {
+ * samplingClass: 'always' | 'perf';
+ * }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by applications.
+export interface TelemetryRegister {}
+
+/** A sampling class registered by the application, else any string. */
+export type SamplingClass = TelemetryRegister extends {
+ samplingClass: infer Registered extends string;
+}
+ ? Registered
+ : string;
+
+/** A uniform position in [0, 1) for a string: FNV-1a, then MurmurHash3's finalizer. */
+function bucket(value: string): number {
+ let hash = 0x811c9dc5;
+ for (let index = 0; index < value.length; index++) {
+ hash ^= value.charCodeAt(index);
+ hash = Math.imul(hash, 0x01000193);
+ }
+ hash ^= hash >>> 16;
+ hash = Math.imul(hash, 0x85ebca6b);
+ hash ^= hash >>> 13;
+ hash = Math.imul(hash, 0xc2b2ae35);
+ hash ^= hash >>> 16;
+ return (hash >>> 0) / 2 ** 32;
+}
+
+/**
+ * Whether a sampling key keeps a class. The same key always makes the same
+ * decision for a class, and its decisions for different classes are
+ * independent.
+ */
+export function keepsClass(
+ key: string,
+ samplingClass: string,
+ rate: number
+): boolean {
+ return bucket(key + samplingClass) < rate;
+}
+
+/** The spans one started span is placed among, once its classes are decided. */
+type Placement =
+ | { readonly exported: false }
+ | {
+ readonly exported: true;
+ /** The span whose trace this one is exported in. */
+ readonly root: SpanRecord;
+ readonly samplingClass: string | undefined;
+ };
+
+const DROPPED: Placement = { exported: false };
+
+/** What sampling needs to know about a span started through `Tracing`. */
+export interface SpanRecord {
+ /** The span this one was started under, in the same OpenTelemetry trace. */
+ readonly parent: SpanRecord | undefined;
+ /** A phase shares its parent's trace and is dropped with it. */
+ readonly phase: boolean;
+ readonly requested: string | undefined;
+ spanContext: SpanContext;
+ placement?: Placement;
+ /** Set on a root that left its parent's trace after the span started. */
+ traceId?: string;
+}
+
+/** Marks a context whose next span is already known to be dropped. */
+const DROPPED_KEY = createContextKey('@macro-inc/observability/dropped');
+
+function randomTraceId(): string {
+ const bytes = crypto.getRandomValues(new Uint8Array(16));
+ return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(
+ ''
+ );
+}
+
+/**
+ * Per-class sampling for one runtime. Each class is kept or dropped once, at
+ * enablement, so spans started before then are placed when they are exported.
+ *
+ * A span joins its parent's trace if that trace is exported. Otherwise a phase
+ * is dropped with it, and any other span starts its own trace when its own
+ * class is kept (an unclassed span always is) and is dropped when it is not.
+ */
+export class TraceSampling implements Sampler {
+ #rates: Readonly<Record<string, number>> = {};
+ #kept: ReadonlyMap<string, boolean> | undefined;
+ readonly #records = new WeakMap<object, SpanRecord>();
+ #resolveDecided: () => void = () => {};
+ /** Settles once every class is decided. */
+ readonly decided = new Promise<void>((resolve) => {
+ this.#resolveDecided = resolve;
+ });
+
+ configure(rates: Readonly<Record<string, number>>): void {
+ this.#rates = rates;
+ }
+
+ /** Decide every configured class once. */
+ decide(keep: (samplingClass: string, rate: number) => boolean): void {
+ if (this.#kept) return;
+ this.#kept = new Map(
+ Object.entries(this.#rates).map(([samplingClass, rate]) => [
+ samplingClass,
+ keep(samplingClass, rate),
+ ])
+ );
+ this.#resolveDecided();
+ }
+
+ /** Unclassed and unconfigured classes are kept; undefined until decided. */
+ kept(samplingClass: string | undefined): boolean | undefined {
+ if (samplingClass === undefined || !(samplingClass in this.#rates))
+ return true;
+ return this.#kept?.get(samplingClass);
+ }
+
+ rate(samplingClass: string): number {
+ return this.#rates[samplingClass] ?? 1;
+ }
+
+ /**
+ * Register a span about to start under `parent`. Returns its record and the
+ * context to start it in: its parent's exported trace, a new trace when it
+ * leaves a dropped one, or a context marked dropped.
+ */
+ start(
+ parent: Context,
+ phase: boolean,
+ requested: string | undefined
+ ): { record: SpanRecord; context: Context } {
+ const parentSpan = trace.getSpan(parent);
+ const parentRecord = parentSpan && this.#records.get(parentSpan);
+ const parentPlacement = parentRecord && this.#place(parentRecord);
+ let context = parent.deleteValue(DROPPED_KEY);
+ let recordParent = parentRecord;
+ if (parentRecord && parentPlacement?.exported) {
+ context = trace.setSpanContext(
+ context,
+ this.#exportedContext(parentRecord, parentPlacement)
+ );
+ } else if (parentPlacement && !phase) {
+ context = trace.deleteSpan(context);
+ recordParent = undefined;
+ }
+ const record: SpanRecord = {
+ parent: recordParent,
+ phase,
+ requested,
+ spanContext: INVALID_SPAN_CONTEXT,
+ };
+ if (this.#place(record)?.exported === false)
+ context = context.setValue(DROPPED_KEY, true);
+ return { record, context };
+ }
+
+ /** Associate a started span with its record. */
+ started(span: object, record: SpanRecord, spanContext: SpanContext): void {
+ record.spanContext = spanContext;
+ this.#records.set(span, record);
+ }
+
+ shouldSample(context: Context): SamplingResult {
+ return {
+ decision:
+ context.getValue(DROPPED_KEY) === true
+ ? SamplingDecision.NOT_RECORD
+ : SamplingDecision.RECORD_AND_SAMPLED,
+ };
+ }
+
+ toString(): string {
+ return 'TraceSampling';
+ }
+
+ /** The context to propagate for a span: unsampled when it is dropped. */
+ spanContext(span: { spanContext(): SpanContext }): SpanContext {
+ const original = span.spanContext();
+ const record = this.#records.get(span);
+ const placement = record && this.#place(record);
+ if (!record || !placement) return original;
+ if (!placement.exported)
+ return { ...original, traceFlags: TraceFlags.NONE };
+ return this.#exportedContext(record, placement);
+ }
+
+ /**
+ * The span to export, or undefined when it is dropped. Call only after the
+ * classes are decided. A span is tagged with the class it asked for, else
+ * the one its parent was tagged with.
+ */
+ exported(span: ReadableSpan): ReadableSpan | undefined {
+ const record = this.#records.get(span);
+ if (!record) return span;
+ const placement = this.#place(record);
+ if (!placement?.exported) return undefined;
+ const samplingClass = placement.samplingClass;
+ const spanContext = this.#exportedContext(record, placement);
+ if (samplingClass === undefined && spanContext === record.spanContext)
+ return span;
+ const tags =
+ samplingClass === undefined
+ ? {}
+ : {
+ [ATTR_SAMPLING_CLASS]: samplingClass,
+ [ATTR_SAMPLING_RATE]: this.rate(samplingClass),
+ };
+ let parentSpanContext = span.parentSpanContext;
+ if (placement.root === record && record.parent)
+ parentSpanContext = undefined;
+ else if (parentSpanContext && spanContext !== record.spanContext)
+ parentSpanContext = {
+ ...parentSpanContext,
+ traceId: spanContext.traceId,
+ };
+ return {
+ name: span.name,
+ kind: span.kind,
+ spanContext: () => spanContext,
+ parentSpanContext,
+ startTime: span.startTime,
+ endTime: span.endTime,
+ status: span.status,
+ attributes: { ...span.attributes, ...tags },
+ links: span.links,
+ events: span.events,
+ duration: span.duration,
+ ended: span.ended,
+ resource: span.resource,
+ instrumentationScope: span.instrumentationScope,
+ droppedAttributesCount: span.droppedAttributesCount,
+ droppedEventsCount: span.droppedEventsCount,
+ droppedLinksCount: span.droppedLinksCount,
+ };
+ }
+
+ /** Undefined while a class it depends on is undecided. */
+ #place(record: SpanRecord): Placement | undefined {
+ if (record.placement) return record.placement;
+ let placement: Placement | undefined;
+ if (record.parent) {
+ const parent = this.#place(record.parent);
+ if (!parent) return undefined;
+ if (parent.exported)
+ placement = {
+ exported: true,
+ root: parent.root,
+ samplingClass: record.requested ?? parent.samplingClass,
+ };
+ else if (record.phase) placement = DROPPED;
+ }
+ if (!placement) {
+ const kept = this.kept(record.requested);
+ if (kept === undefined) return undefined;
+ placement = kept
+ ? { exported: true, root: record, samplingClass: record.requested }
+ : DROPPED;
+ }
+ record.placement = placement;
+ return placement;
+ }
+
+ /** A root that left its parent's trace moves its spans to a new trace id. */
+ #exportedContext(
+ record: SpanRecord,
+ placement: Placement & { exported: true }
+ ): SpanContext {
+ const root = placement.root;
+ if (!root.parent) return record.spanContext;
+ root.traceId ??= randomTraceId();
+ if (record.spanContext.traceId === root.traceId) return record.spanContext;
+ return {
+ ...record.spanContext,
+ traceId: root.traceId,
+ traceFlags: TraceFlags.SAMPLED,
+ };
+ }
+}
diff --git a/packages/observability/src/span-noop.ts b/packages/observability/src/span-noop.ts
new file mode 100644
index 0000000000..d7117c8b15
--- /dev/null
+++ b/packages/observability/src/span-noop.ts
@@ -0,0 +1,26 @@
+import type { Span } from './span';
+
+class NoopSpan implements Span {
+ span<T>(name: string, operation: (span: Span) => Promise<T>): Promise<T>;
+ span(name: string): Span;
+ span<T>(
+ _name: string,
+ operation?: (span: Span) => Promise<T>
+ ): Span | Promise<T> {
+ return operation ? operation(this) : this;
+ }
+
+ run<T>(operation: () => T): T {
+ return operation();
+ }
+
+ setAttr(): void {}
+ event(): void {}
+ error(): void {}
+ traceparent(): undefined {}
+ injectTraceHeaders(): void {}
+ end(): void {}
+}
+
+/** A span that records nothing, for code that runs outside any trace. */
+export const NOOP_SPAN: Span = new NoopSpan();
diff --git a/packages/observability/src/span.ts b/packages/observability/src/span.ts
index 366e37ab7a..e61fe0061a 100644
--- a/packages/observability/src/span.ts
+++ b/packages/observability/src/span.ts
@@ -1,108 +1,119 @@
import {
- type Context,
- context,
- isSpanContextValid,
- type Attributes as OtelAttributes,
- type Span as OtelSpan,
- propagation,
- SpanStatusCode,
-} from "@opentelemetry/api";
-import type { Attribute, Attributes } from "./config";
+ type Context,
+ context,
+ isSpanContextValid,
+ type Attributes as OtelAttributes,
+ type Span as OtelSpan,
+ propagation,
+ SpanStatusCode,
+ trace,
+} from '@opentelemetry/api';
+import type { Attribute, Attributes } from './config';
+
+/** An explicit context retained across a queue/authentication boundary; owns no span. */
+export interface TraceContext {
+ run<T>(operation: () => T): T;
+}
/** A manually managed span. Calling {@link Span.end} ends it. */
-export interface Span {
- /** Start a child span, or run and end one around an async operation. */
- span<T>(name: string, operation: (span: Span) => Promise<T>): Promise<T>;
- span(name: string): Span;
- /** Run with this span as the active OpenTelemetry context. */
- run<T>(operation: () => T): T;
- /** Set one span attribute. */
- setAttr(name: string, value: Attribute): void;
- /** Add a point-in-time event. */
- event(name: string, attributes?: Attributes): void;
- /** Record an exception and mark the span as failed. */
- error(error: unknown): void;
- /** Return this span's W3C trace context for transports without headers. */
- traceparent(): string | undefined;
- /** Inject this span's W3C trace context into an HTTP header carrier. */
- injectTraceHeaders(headers: Record<string, string>): void;
- /** End the span. Safe to call more than once. */
- end(): void;
+export interface Span extends TraceContext {
+ /** Start a child span, or run and end one around an async operation. */
+ span<T>(name: string, operation: (span: Span) => Promise<T>): Promise<T>;
+ span(name: string): Span;
+ /** Run with this span as the active OpenTelemetry context. */
+ run<T>(operation: () => T): T;
+ /** Set one span attribute. */
+ setAttr(name: string, value: Attribute): void;
+ /** Add a point-in-time event. */
+ event(name: string, attributes?: Attributes, timestamp?: number): void;
+ /** Record an exception and mark the span as failed. */
+ error(error: unknown): void;
+ /** Return this span's W3C trace context for transports without headers. */
+ traceparent(): string | undefined;
+ /** Inject this span's W3C trace context into an HTTP header carrier. */
+ injectTraceHeaders(headers: Record<string, string>): void;
+ /** End the span. Safe to call more than once. */
+ end(timestamp?: number): void;
}
export class SpanImpl implements Span {
- #ended = false;
+ #ended = false;
- constructor(
- private readonly otelSpan: OtelSpan,
- private readonly ctx: Context,
- private readonly startChild: (name: string, parent: Context) => Span,
- ) {}
+ constructor(
+ private readonly otelSpan: OtelSpan,
+ private readonly ctx: Context,
+ private readonly startChild: (name: string, parent: Context) => Span,
+ private readonly canPropagate: () => boolean = () => true,
+ private readonly propagationContext: () => Context = () => ctx
+ ) {}
- span<T>(name: string, operation: (span: Span) => Promise<T>): Promise<T>;
- span(name: string): Span;
- span<T>(
- name: string,
- operation?: (span: Span) => Promise<T>,
- ): Span | Promise<T> {
- const span = this.startChild(name, this.ctx);
- if (!operation) return span;
+ span<T>(name: string, operation: (span: Span) => Promise<T>): Promise<T>;
+ span(name: string): Span;
+ span<T>(
+ name: string,
+ operation?: (span: Span) => Promise<T>
+ ): Span | Promise<T> {
+ const span = this.startChild(name, this.ctx);
+ if (!operation) return span;
- return span.run(async () => {
- try {
- return await operation(span);
- } finally {
- span.end();
- }
- });
- }
+ return span.run(async () => {
+ try {
+ return await operation(span);
+ } finally {
+ span.end();
+ }
+ });
+ }
- run<T>(operation: () => T): T {
- return context.with(this.ctx, operation);
- }
+ run<T>(operation: () => T): T {
+ return context.with(this.ctx, operation);
+ }
- setAttr(name: string, value: Attribute): void {
- if (!this.#ended) this.otelSpan.setAttribute(name, value);
- }
+ setAttr(name: string, value: Attribute): void {
+ if (!this.#ended) this.otelSpan.setAttribute(name, value);
+ }
- event(name: string, attributes?: Attributes): void {
- if (!this.#ended)
- this.otelSpan.addEvent(name, attributes as OtelAttributes);
- }
+ event(name: string, attributes?: Attributes, timestamp?: number): void {
+ if (!this.#ended)
+ this.otelSpan.addEvent(name, attributes as OtelAttributes, timestamp);
+ }
- error(error: unknown): void {
- if (this.#ended) return;
- const exception = SpanImpl.normalizeError(error);
- this.otelSpan.recordException(exception);
- this.otelSpan.setStatus({
- code: SpanStatusCode.ERROR,
- message:
- typeof exception === "string" ? exception : (exception.message ?? ""),
- });
- }
+ error(error: unknown): void {
+ if (this.#ended) return;
+ const exception = SpanImpl.normalizeError(error);
+ this.otelSpan.recordException(exception);
+ this.otelSpan.setStatus({
+ code: SpanStatusCode.ERROR,
+ message:
+ typeof exception === 'string' ? exception : (exception.message ?? ''),
+ });
+ }
- traceparent(): string | undefined {
- const spanContext = this.otelSpan.spanContext();
- if (!isSpanContextValid(spanContext)) return undefined;
- const { traceId, spanId, traceFlags } = spanContext;
- return `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, "0")}`;
- }
+ traceparent(): string | undefined {
+ if (!this.canPropagate()) return undefined;
+ const spanContext = trace.getSpanContext(this.propagationContext());
+ if (!spanContext) return undefined;
+ if (!isSpanContextValid(spanContext)) return undefined;
+ const { traceId, spanId, traceFlags } = spanContext;
+ return `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, '0')}`;
+ }
- injectTraceHeaders(headers: Record<string, string>): void {
- if (!this.#ended) propagation.inject(this.ctx, headers);
- }
+ injectTraceHeaders(headers: Record<string, string>): void {
+ if (!this.#ended && this.canPropagate())
+ propagation.inject(this.propagationContext(), headers);
+ }
- end(): void {
- if (this.#ended) return;
- this.#ended = true;
- this.otelSpan.end();
- }
+ end(timestamp?: number): void {
+ if (this.#ended) return;
+ this.#ended = true;
+ this.otelSpan.end(timestamp);
+ }
- private static normalizeError(error: unknown): Error | string {
- return error instanceof Error ||
- typeof error === "string" ||
- (typeof error === "object" && error !== null && "message" in error)
- ? (error as Error | string)
- : String(error);
- }
+ private static normalizeError(error: unknown): Error | string {
+ return error instanceof Error ||
+ typeof error === 'string' ||
+ (typeof error === 'object' && error !== null && 'message' in error)
+ ? (error as Error | string)
+ : String(error);
+ }
}
diff --git a/packages/observability/src/startup.test.ts b/packages/observability/src/startup.test.ts
new file mode 100644
index 0000000000..2fc86c5cbe
--- /dev/null
+++ b/packages/observability/src/startup.test.ts
@@ -0,0 +1,225 @@
+import { context, propagation, trace } from '@opentelemetry/api';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import type { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
+import { afterEach, expect, it, vi } from 'vitest';
+import type { TelemetryInitConfig, TelemetryStartupOptions } from './config';
+import { TraceSampling } from './sampling';
+import { Tracing } from './tracing';
+import { createWebTracingProvider, StackContextManager } from './web';
+
+const exporters: InMemorySpanExporter[] = [];
+const destinations: Array<string | undefined> = [];
+vi.mock('@opentelemetry/exporter-trace-otlp-http', async () => {
+ const { InMemorySpanExporter } = await import(
+ '@opentelemetry/sdk-trace-base'
+ );
+ return {
+ OTLPTraceExporter: class extends InMemorySpanExporter {
+ constructor(options: { url?: string }) {
+ super();
+ exporters.push(this);
+ destinations.push(options.url);
+ }
+ },
+ };
+});
+afterEach(() => {
+ trace.disable();
+ context.disable();
+ propagation.disable();
+ exporters.length = 0;
+ destinations.length = 0;
+});
+
+it('registers immediately, retains early recording spans, and waits for its destination and identity', async () => {
+ let resolve: (settings: TelemetryStartupOptions) => void = () => {};
+ const startup = new Promise<TelemetryStartupOptions>((done) => {
+ resolve = done;
+ });
+ const config: TelemetryInitConfig = {
+ serviceName: 'test',
+ environment: 'prod',
+ startup,
+ enabled: async () => true,
+ contextManager: new StackContextManager(),
+ };
+ const resource = resourceFromAttributes({
+ 'service.instance.id': startup.then(() => 'launch-1'),
+ });
+ const sampling = new TraceSampling();
+ sampling.configure({ perf: 0 });
+ const provider = createWebTracingProvider(
+ config,
+ resource,
+ () => undefined,
+ sampling
+ );
+ const tracing = new Tracing();
+ tracing.init(
+ { ...config, tracingProvider: () => provider },
+ resource,
+ () => undefined,
+ sampling
+ );
+ const root = tracing.span('early-recording', { sampling: 'perf' });
+ const child = root.span('early-child');
+ child.end();
+ root.end();
+ expect(exporters).toHaveLength(0);
+ expect(root.traceparent()).toBeUndefined();
+ resolve({
+ recording: true,
+ tracesUrl: 'http://localhost:4318/custom/v1/traces',
+ });
+ // A recording keeps every class.
+ sampling.decide(() => true);
+ await tracing.flush();
+ expect(destinations).toEqual(['http://localhost:4318/custom/v1/traces']);
+ const spans = exporters[0].getFinishedSpans();
+ expect(spans.map((span) => span.name)).toEqual([
+ 'early-child',
+ 'early-recording',
+ ]);
+ expect(spans[0].parentSpanContext?.spanId).toBe(
+ spans[1].spanContext().spanId
+ );
+ expect(
+ spans.every(
+ (span) => span.resource.attributes['service.instance.id'] === 'launch-1'
+ )
+ ).toBe(true);
+ expect(root.traceparent()).toMatch(/-01$/);
+ await tracing.shutdown();
+});
+
+it('drops normal unsampled early spans and late children and normalizes both propagation APIs', async () => {
+ let resolve: (settings: TelemetryStartupOptions) => void = () => {};
+ const startup = new Promise<TelemetryStartupOptions>((done) => {
+ resolve = done;
+ });
+ const config: TelemetryInitConfig = {
+ serviceName: 'test',
+ environment: 'prod',
+ startup,
+ tracesUrl: 'http://localhost/v1/traces',
+ enabled: async () => true,
+ contextManager: new StackContextManager(),
+ };
+ const tracing = new Tracing();
+ const resource = resourceFromAttributes({});
+ const sampling = new TraceSampling();
+ sampling.configure({ perf: 0.05 });
+ tracing.init(
+ {
+ ...config,
+ tracingProvider: (resource, user, sampling) =>
+ createWebTracingProvider(config, resource, user, sampling),
+ },
+ resource,
+ () => undefined,
+ sampling
+ );
+ const early = tracing.span('normal-perf', { sampling: 'perf' });
+ early.span('early-child').end();
+ resolve({ recording: false, tracesUrl: config.tracesUrl });
+ sampling.decide(() => false);
+ await tracing.flush();
+ expect(early.traceparent()).toMatch(/-00$/);
+ const headers: Record<string, string> = {};
+ early.injectTraceHeaders(headers);
+ expect(headers.traceparent).toMatch(/-00$/);
+ early.span('late-child').end();
+ early.end();
+ tracing.span('ordinary').end();
+ await tracing.flush();
+ expect(exporters[0].getFinishedSpans().map((span) => span.name)).toEqual([
+ 'ordinary',
+ ]);
+ await tracing.shutdown();
+});
+
+it('constructs no exporter when enablement is denied, including a resolved native destination', async () => {
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'test',
+ environment: 'prod',
+ enabled: async () => false,
+ startup: Promise.resolve({
+ recording: false,
+ tracesUrl: 'http://localhost/v1/traces',
+ }),
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ new TraceSampling()
+ );
+ provider.getTracer('test').startSpan('early').end();
+ await provider.forceFlush();
+ expect(exporters).toHaveLength(0);
+ await provider.shutdown();
+});
+
+it('preserves sampled normal roots and children across startup resolution', async () => {
+ let resolve: (settings: TelemetryStartupOptions) => void = () => {};
+ const startup = new Promise<TelemetryStartupOptions>((done) => {
+ resolve = done;
+ });
+ const config: TelemetryInitConfig = {
+ serviceName: 'test',
+ environment: 'prod',
+ startup,
+ enabled: async () => true,
+ contextManager: new StackContextManager(),
+ };
+ const tracing = new Tracing();
+ const sampling = new TraceSampling();
+ sampling.configure({ perf: 0.05 });
+ tracing.init(
+ {
+ ...config,
+ tracingProvider: (resource, user, sampling) =>
+ createWebTracingProvider(config, resource, user, sampling),
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const early = tracing.span('sampled-perf', { sampling: 'perf' });
+ early.span('early-child').end();
+ resolve({ recording: false, tracesUrl: 'http://localhost/v1/traces' });
+ sampling.decide(() => true);
+ await tracing.flush();
+ early.span('late-child').end();
+ early.end();
+ await tracing.flush();
+ expect(exporters[0].getFinishedSpans().map((span) => span.name)).toEqual([
+ 'early-child',
+ 'late-child',
+ 'sampled-perf',
+ ]);
+ expect(early.traceparent()).toMatch(/-01$/);
+ await tracing.shutdown();
+});
+
+it('fails closed when native startup settings reject', async () => {
+ let reject: (error: Error) => void = () => {};
+ const startup = new Promise<TelemetryStartupOptions>((_resolve, fail) => {
+ reject = fail;
+ });
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'test',
+ environment: 'prod',
+ enabled: async () => true,
+ startup,
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ new TraceSampling()
+ );
+ provider.getTracer('test').startSpan('early').end();
+ reject(new Error('unavailable'));
+ await provider.forceFlush();
+ expect(exporters).toHaveLength(0);
+ await provider.shutdown();
+});
diff --git a/packages/observability/src/telemetry.test.ts b/packages/observability/src/telemetry.test.ts
index 1015583530..841f9edff8 100644
--- a/packages/observability/src/telemetry.test.ts
+++ b/packages/observability/src/telemetry.test.ts
@@ -1,221 +1,246 @@
// @vitest-environment jsdom
-import { context, trace } from "@opentelemetry/api";
-import { logs } from "@opentelemetry/api-logs";
+import { context, trace } from '@opentelemetry/api';
+import { logs } from '@opentelemetry/api-logs';
import {
- InMemoryLogRecordExporter,
- LoggerProvider,
- SimpleLogRecordProcessor,
-} from "@opentelemetry/sdk-logs";
+ InMemoryLogRecordExporter,
+ LoggerProvider,
+ SimpleLogRecordProcessor,
+} from '@opentelemetry/sdk-logs';
import {
- BasicTracerProvider,
- InMemorySpanExporter,
- SimpleSpanProcessor,
-} from "@opentelemetry/sdk-trace-base";
-import { beforeEach, describe, expect, test } from "vitest";
-import { Telemetry } from "./index";
-import { userIdSuppressed } from "./privacy";
-import { ZoneContextManager } from "./zone";
+ BasicTracerProvider,
+ InMemorySpanExporter,
+ SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { StackContextManager } from '@opentelemetry/sdk-trace-web';
+import { beforeEach, describe, expect, test } from 'vitest';
+import { Telemetry } from './index';
+import { userIdSuppressed } from './privacy';
-context.setGlobalContextManager(new ZoneContextManager().enable());
+context.setGlobalContextManager(new StackContextManager().enable());
const spanExporter = new InMemorySpanExporter();
trace.setGlobalTracerProvider(
- new BasicTracerProvider({
- spanProcessors: [
- {
- onStart: (span, parentContext) => {
- if (!userIdSuppressed(parentContext)) {
- span.setAttribute("usr.id", "test-user");
- }
- },
- onEnd: () => {},
- forceFlush: () => Promise.resolve(),
- shutdown: () => Promise.resolve(),
- },
- new SimpleSpanProcessor(spanExporter),
- ],
- }),
+ new BasicTracerProvider({
+ spanProcessors: [
+ {
+ onStart: (span, parentContext) => {
+ if (!userIdSuppressed(parentContext)) {
+ span.setAttribute('usr.id', 'test-user');
+ }
+ },
+ onEnd: () => {},
+ forceFlush: () => Promise.resolve(),
+ shutdown: () => Promise.resolve(),
+ },
+ new SimpleSpanProcessor(spanExporter),
+ ],
+ })
);
const logExporter = new InMemoryLogRecordExporter();
logs.setGlobalLoggerProvider(
- new LoggerProvider({
- processors: [new SimpleLogRecordProcessor({ exporter: logExporter })],
- }),
+ new LoggerProvider({
+ processors: [new SimpleLogRecordProcessor({ exporter: logExporter })],
+ })
);
-describe("Telemetry", () => {
- beforeEach(() => {
- spanExporter.reset();
- logExporter.reset();
- });
-
- test("awaits the async enablement decision", async () => {
- let decide!: (enabled: boolean) => void;
- let markDecisionRequested!: () => void;
- const decisionRequested = new Promise<void>((resolve) => {
- markDecisionRequested = resolve;
- });
- let initialized = false;
- const initialization = Telemetry.init({
- serviceName: "web-app",
- environment: "test",
- enabled: () =>
- new Promise<boolean>((resolve) => {
- decide = resolve;
- markDecisionRequested();
- }),
- }).then(() => {
- initialized = true;
- });
-
- await decisionRequested;
- expect(initialized).toBe(false);
-
- decide(false);
- await initialization;
- expect(initialized).toBe(true);
- });
-
- test("a span exports only when ended", () => {
- const span = Telemetry.span("doc.open");
- span.setAttr("document.id", "abc");
- expect(spanExporter.getFinishedSpans()).toHaveLength(0);
-
- span.end();
- span.end();
-
- expect(spanExporter.getFinishedSpans()).toHaveLength(1);
- expect(spanExporter.getFinishedSpans()[0]?.attributes).toMatchObject({
- "document.id": "abc",
- });
- });
-
- test("anonymous span trees are detached roots and suppress identity", () => {
- const regular = Telemetry.span("regular");
- const anonymous = regular.run(() =>
- Telemetry.anonymousSpan("cache.request"),
- );
- const child = anonymous.span("cache.storage");
- child.end();
- anonymous.end();
- regular.end();
-
- const spans = new Map(
- spanExporter.getFinishedSpans().map((span) => [span.name, span]),
- );
- expect(spans.get("regular")?.attributes["usr.id"]).toBe("test-user");
- expect(spans.get("cache.request")?.attributes).not.toHaveProperty("usr.id");
- expect(spans.get("cache.request")?.parentSpanContext).toBeUndefined();
- expect(spans.get("cache.storage")?.attributes).not.toHaveProperty("usr.id");
- });
-
- test("ends a callback span after the async operation", async () => {
- let complete: () => void = () => {};
- const operation = Telemetry.span("doc.save", async (span) => {
- span.setAttr("document.id", "abc");
- await new Promise<void>((resolve) => {
- complete = resolve;
- });
- return 42;
- });
-
- await Promise.resolve();
- expect(spanExporter.getFinishedSpans()).toHaveLength(0);
- complete();
- expect(await operation).toBe(42);
- expect(spanExporter.getFinishedSpans()).toHaveLength(1);
- });
-
- test("ends a callback span when the async operation throws", async () => {
- const failure = new Error("failed");
-
- await expect(
- Telemetry.span("doc.save", async () => {
- throw failure;
- }),
- ).rejects.toBe(failure);
- expect(spanExporter.getFinishedSpans()).toHaveLength(1);
- });
-
- test("starts children from the parent span context", () => {
- const root = Telemetry.span("doc.open");
- const child = root.span("doc.load");
- child.end();
- root.end();
-
- const spans = new Map(
- spanExporter.getFinishedSpans().map((span) => [span.name, span]),
- );
- expect(spans.get("doc.load")?.parentSpanContext?.spanId).toBe(
- spans.get("doc.open")?.spanContext().spanId,
- );
- });
-
- test("ends a callback child span after the async operation", async () => {
- const root = Telemetry.span("doc.open");
- let complete: () => void = () => {};
- const operation = root.span("doc.snapshot.dss-cache", async (span) => {
- span.setAttr("snapshot.source", "dss");
- await new Promise<void>((resolve) => {
- complete = resolve;
- });
- return "unavailable";
- });
-
- await Promise.resolve();
- expect(spanExporter.getFinishedSpans()).toHaveLength(0);
- complete();
- expect(await operation).toBe("unavailable");
- root.end();
-
- const spans = new Map(
- spanExporter.getFinishedSpans().map((span) => [span.name, span]),
- );
- expect(spans.get("doc.snapshot.dss-cache")?.attributes).toMatchObject({
- "snapshot.source": "dss",
- });
- expect(spans.get("doc.snapshot.dss-cache")?.parentSpanContext?.spanId).toBe(
- spans.get("doc.open")?.spanContext().spanId,
- );
- });
-
- test("run makes the span active", () => {
- const root = Telemetry.span("doc.open");
- const child = root.run(() => Telemetry.span("http request"));
- child.end();
- root.end();
-
- const spans = new Map(
- spanExporter.getFinishedSpans().map((span) => [span.name, span]),
- );
- expect(spans.get("http request")?.parentSpanContext?.spanId).toBe(
- spans.get("doc.open")?.spanContext().spanId,
- );
- });
-
- test("records span errors", () => {
- const span = Telemetry.span("doc.open");
- span.error(new Error("boom"));
- span.end();
-
- const [exported] = spanExporter.getFinishedSpans();
- expect(exported?.status.code).not.toBe(0);
- expect(exported?.events[0]?.name).toBe("exception");
- });
-
- test("emits structured logs", () => {
- Telemetry.warn("WAL flush not acked", {
- "document.id": "doc-1",
- dirty: 3,
- });
-
- const [record] = logExporter.getFinishedLogRecords();
- expect(record?.severityText).toBe("warn");
- expect(record?.body).toBe("WAL flush not acked");
- expect(record?.attributes).toMatchObject({
- "document.id": "doc-1",
- dirty: 3,
- });
- });
+describe('Telemetry', () => {
+ beforeEach(() => {
+ spanExporter.reset();
+ logExporter.reset();
+ });
+
+ test('awaits the async enablement decision', async () => {
+ let decide!: (enabled: boolean) => void;
+ let markDecisionRequested!: () => void;
+ const decisionRequested = new Promise<void>((resolve) => {
+ markDecisionRequested = resolve;
+ });
+ let initialized = false;
+ const initialization = Telemetry.init({
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: () =>
+ new Promise<boolean>((resolve) => {
+ decide = resolve;
+ markDecisionRequested();
+ }),
+ }).then(() => {
+ initialized = true;
+ });
+
+ await decisionRequested;
+ expect(initialized).toBe(false);
+
+ decide(true);
+ await initialization;
+ expect(initialized).toBe(true);
+ });
+
+ test('a span exports only when ended', () => {
+ const span = Telemetry.span('doc.open');
+ span.setAttr('document.id', 'abc');
+ expect(spanExporter.getFinishedSpans()).toHaveLength(0);
+
+ span.end();
+ span.end();
+
+ expect(spanExporter.getFinishedSpans()).toHaveLength(1);
+ expect(spanExporter.getFinishedSpans()[0]?.attributes).toMatchObject({
+ 'document.id': 'abc',
+ });
+ });
+
+ test('anonymous span trees are detached roots and suppress identity', () => {
+ const regular = Telemetry.span('regular');
+ const anonymous = regular.run(() =>
+ Telemetry.anonymousSpan('cache.request')
+ );
+ const child = anonymous.span('cache.storage');
+ child.end();
+ anonymous.end();
+ regular.end();
+
+ const spans = new Map(
+ spanExporter.getFinishedSpans().map((span) => [span.name, span])
+ );
+ expect(spans.get('regular')?.attributes['usr.id']).toBe('test-user');
+ expect(spans.get('cache.request')?.attributes).not.toHaveProperty('usr.id');
+ expect(spans.get('cache.request')?.parentSpanContext).toBeUndefined();
+ expect(spans.get('cache.storage')?.attributes).not.toHaveProperty('usr.id');
+ });
+
+ test('captured context survives an await and restores an unrelated caller', async () => {
+ const root = Telemetry.span('queued.action');
+ const parent = root.run(() => Telemetry.captureContext());
+ await Promise.resolve();
+ const other = Telemetry.span('other.action');
+ other.run(() => {
+ parent.run(() =>
+ Telemetry.span('queued.request', { kind: 'client' }).end()
+ );
+ Telemetry.span('other.child').end();
+ });
+ root.end();
+ other.end();
+ const spans = new Map(
+ spanExporter.getFinishedSpans().map((span) => [span.name, span])
+ );
+ expect(spans.get('queued.request')?.parentSpanContext?.spanId).toBe(
+ spans.get('queued.action')?.spanContext().spanId
+ );
+ expect(spans.get('other.child')?.parentSpanContext?.spanId).toBe(
+ spans.get('other.action')?.spanContext().spanId
+ );
+ expect(spans.size).toBe(4);
+ });
+
+ test('ends a callback span after the async operation', async () => {
+ let complete: () => void = () => {};
+ const operation = Telemetry.span('doc.save', async (span) => {
+ span.setAttr('document.id', 'abc');
+ await new Promise<void>((resolve) => {
+ complete = resolve;
+ });
+ return 42;
+ });
+
+ await Promise.resolve();
+ expect(spanExporter.getFinishedSpans()).toHaveLength(0);
+ complete();
+ expect(await operation).toBe(42);
+ expect(spanExporter.getFinishedSpans()).toHaveLength(1);
+ });
+
+ test('ends a callback span when the async operation throws', async () => {
+ const failure = new Error('failed');
+
+ await expect(
+ Telemetry.span('doc.save', async () => {
+ throw failure;
+ })
+ ).rejects.toBe(failure);
+ expect(spanExporter.getFinishedSpans()).toHaveLength(1);
+ });
+
+ test('starts children from the parent span context', () => {
+ const root = Telemetry.span('doc.open');
+ const child = root.span('doc.load');
+ child.end();
+ root.end();
+
+ const spans = new Map(
+ spanExporter.getFinishedSpans().map((span) => [span.name, span])
+ );
+ expect(spans.get('doc.load')?.parentSpanContext?.spanId).toBe(
+ spans.get('doc.open')?.spanContext().spanId
+ );
+ });
+
+ test('ends a callback child span after the async operation', async () => {
+ const root = Telemetry.span('doc.open');
+ let complete: () => void = () => {};
+ const operation = root.span('doc.snapshot.dss-cache', async (span) => {
+ span.setAttr('snapshot.source', 'dss');
+ await new Promise<void>((resolve) => {
+ complete = resolve;
+ });
+ return 'unavailable';
+ });
+
+ await Promise.resolve();
+ expect(spanExporter.getFinishedSpans()).toHaveLength(0);
+ complete();
+ expect(await operation).toBe('unavailable');
+ root.end();
+
+ const spans = new Map(
+ spanExporter.getFinishedSpans().map((span) => [span.name, span])
+ );
+ expect(spans.get('doc.snapshot.dss-cache')?.attributes).toMatchObject({
+ 'snapshot.source': 'dss',
+ });
+ expect(spans.get('doc.snapshot.dss-cache')?.parentSpanContext?.spanId).toBe(
+ spans.get('doc.open')?.spanContext().spanId
+ );
+ });
+
+ test('run makes the span active', () => {
+ const root = Telemetry.span('doc.open');
+ const child = root.run(() => Telemetry.span('http request'));
+ child.end();
+ root.end();
+
+ const spans = new Map(
+ spanExporter.getFinishedSpans().map((span) => [span.name, span])
+ );
+ expect(spans.get('http request')?.parentSpanContext?.spanId).toBe(
+ spans.get('doc.open')?.spanContext().spanId
+ );
+ });
+
+ test('records span errors', () => {
+ const span = Telemetry.span('doc.open');
+ span.error(new Error('boom'));
+ span.end();
+
+ const [exported] = spanExporter.getFinishedSpans();
+ expect(exported?.status.code).not.toBe(0);
+ expect(exported?.events[0]?.name).toBe('exception');
+ });
+
+ test('emits structured logs', () => {
+ Telemetry.warn('WAL flush not acked', {
+ 'document.id': 'doc-1',
+ dirty: 3,
+ });
+
+ const [record] = logExporter.getFinishedLogRecords();
+ expect(record?.severityText).toBe('warn');
+ expect(record?.body).toBe('WAL flush not acked');
+ expect(record?.attributes).toMatchObject({
+ 'document.id': 'doc-1',
+ dirty: 3,
+ });
+ });
});
diff --git a/packages/observability/src/telemetry.ts b/packages/observability/src/telemetry.ts
index 5790a51523..0ca346e38d 100644
--- a/packages/observability/src/telemetry.ts
+++ b/packages/observability/src/telemetry.ts
@@ -8,33 +8,56 @@ import {
} from './config';
import { ATTR_DEPLOYMENT_ENVIRONMENT, CONSOLE_PREFIX } from './constants';
import { Logging } from './logging';
-import type { Span } from './span';
-import { Tracing } from './tracing';
+import { keepsClass, type SamplingClass, TraceSampling } from './sampling';
+import type { Span, TraceContext } from './span';
+import { type SpanOptions, Tracing } from './tracing';
type SpanOperation<T> = (span: Span) => Promise<T>;
export class Telemetry {
static readonly #tracing = new Tracing();
static readonly #logging = new Logging();
+ static readonly #sampling = new TraceSampling();
static #initialization: Promise<void> | undefined;
private constructor() {}
- static readonly config = new TelemetryRuntimeConfig();
+ static readonly config = new TelemetryRuntimeConfig(Telemetry.#sampling);
- /** Initialize providers once, after the optional async enablement decision. */
- static init(config: TelemetryInitConfig): Promise<void> {
+ /** Initialize providers once, with an optional buffer while enablement resolves. */
+ static init<Classes extends string = SamplingClass>(
+ config: TelemetryInitConfig<Classes>
+ ): Promise<void> {
Telemetry.#initialization ??= Telemetry.#initialize(config);
return Telemetry.#initialization;
}
+ /**
+ * Start a span in the active trace. When that trace is dropped by sampling,
+ * the span starts its own trace if its `sampling` class is kept (always,
+ * without one) and is dropped otherwise.
+ */
static span<T>(name: string, operation: SpanOperation<T>): Promise<T>;
- static span(name: string): Span;
static span<T>(
name: string,
+ options: SpanOptions,
+ operation: SpanOperation<T>
+ ): Promise<T>;
+ static span(name: string, options?: SpanOptions): Span;
+ static span<T>(
+ name: string,
+ optionsOrOperation?: SpanOptions | SpanOperation<T>,
operation?: SpanOperation<T>
): Span | Promise<T> {
- return Telemetry.#runSpan(Telemetry.#tracing.span(name), operation);
+ if (typeof optionsOrOperation === 'function')
+ return Telemetry.#runSpan(
+ Telemetry.#tracing.span(name),
+ optionsOrOperation
+ );
+ return Telemetry.#runSpan(
+ Telemetry.#tracing.span(name, optionsOrOperation),
+ operation
+ );
}
/**
@@ -57,18 +80,22 @@ export class Telemetry {
);
}
- /** Start an HTTP client span. Callers must end the returned span. */
- static clientSpan(name: string): Span {
- return Telemetry.#tracing.clientSpan(name);
+ /**
+ * Capture at synchronous transport/queue admission, before its first await.
+ * Prefer a known Span directly; a captured context creates/ends no span.
+ */
+ static captureContext(): TraceContext {
+ return Telemetry.#tracing.captureContext();
}
/** Record a point-in-time sample; timestamp is Unix time in milliseconds. */
static recordSample(
name: string,
attributes: Attributes,
- timestamp: number
+ timestamp: number,
+ sampling?: SamplingClass
): void {
- Telemetry.#tracing.recordSample(name, attributes, timestamp);
+ Telemetry.#tracing.recordSample(name, attributes, timestamp, sampling);
}
static debug(message: string, attributes?: LogAttributes): void {
@@ -113,21 +140,47 @@ export class Telemetry {
});
}
- static async #initialize(config: TelemetryInitConfig): Promise<void> {
- try {
- if (!(await config.enabled())) return;
- } catch (error) {
- console.warn(`${CONSOLE_PREFIX} Failed to resolve enablement`, error);
- return;
- }
-
+ static async #initialize<Classes extends string>(
+ config: TelemetryInitConfig<Classes>
+ ): Promise<void> {
+ // A single shared decision gates both the buffered tracing exporter and logs.
+ const enabled = Telemetry.#enabled(config);
+ const tracingConfig = { ...config, enabled: () => enabled };
const resource = resourceFromAttributes({
...config.resourceAttributes,
[ATTR_SERVICE_NAME]: config.serviceName,
[ATTR_DEPLOYMENT_ENVIRONMENT]: config.environment,
});
const getUserId = () => Telemetry.config.userId;
- Telemetry.#tracing.init(config, resource, getUserId);
- Telemetry.#logging.init(config, resource, getUserId);
+ const sampling = Telemetry.#sampling;
+ sampling.configure(config.sampling ?? {});
+ Telemetry.#tracing.init(tracingConfig, resource, getUserId, sampling);
+ const allowed = await enabled;
+ const resolved =
+ allowed && config.startup
+ ? { ...config, ...(await config.startup) }
+ : config;
+ // Decided at enablement: spans buffered until now are placed at export.
+ const key = allowed ? config.samplingKey?.() : undefined;
+ sampling.decide(
+ (samplingClass, rate) =>
+ allowed &&
+ (resolved.recording === true ||
+ key === undefined ||
+ keepsClass(key, samplingClass, rate))
+ );
+ if (!allowed) return;
+ Telemetry.#logging.init(resolved, resource, getUserId);
+ }
+ static async #enabled<Classes extends string>(
+ config: TelemetryInitConfig<Classes>
+ ): Promise<boolean> {
+ try {
+ const [enabled] = await Promise.all([config.enabled(), config.startup]);
+ return enabled;
+ } catch (error) {
+ console.warn(`${CONSOLE_PREFIX} Failed to resolve enablement`, error);
+ return false;
+ }
}
}
diff --git a/packages/observability/src/tracing.ts b/packages/observability/src/tracing.ts
index eeb3510a24..c2e4c0249d 100644
--- a/packages/observability/src/tracing.ts
+++ b/packages/observability/src/tracing.ts
@@ -1,6 +1,7 @@
import {
type Context,
context,
+ type Span as OtelSpan,
ROOT_CONTEXT,
SpanKind,
trace,
@@ -10,43 +11,78 @@ import type { Attributes, TelemetryInitConfig } from './config';
import { INSTRUMENTATION_SCOPE_NAME } from './constants';
import { suppressUserId } from './privacy';
import type { TelemetryTracingProvider } from './provider';
-import { type Span, SpanImpl } from './span';
+import type { SamplingClass, TraceSampling } from './sampling';
+import { type Span, SpanImpl, type TraceContext } from './span';
+
+export interface SpanOptions {
+ /**
+ * The class whose sampling decision keeps this span when it starts outside
+ * an exported trace. Without one it is always kept.
+ */
+ sampling?: SamplingClass;
+ /** `client` for an outbound request. Defaults to `internal`. */
+ kind?: 'internal' | 'client';
+ /** Start time as Unix time in milliseconds, for a phase that already began. */
+ startTime?: number;
+ attributes?: Attributes;
+}
+
+interface StartOptions extends SpanOptions {
+ /** A phase of its parent: always in its parent's trace, dropped with it. */
+ phase?: boolean;
+}
export class Tracing {
#provider: TelemetryTracingProvider | undefined;
+ #sampling: TraceSampling | undefined;
+ #propagationEnabled = false;
+ #enablement: Promise<void> | undefined;
init(
- config: TelemetryInitConfig,
+ config: TelemetryInitConfig<string>,
resource: Resource,
- getUserId: () => string | undefined
+ getUserId: () => string | undefined,
+ sampling: TraceSampling
): void {
- this.#provider = config.tracingProvider?.(resource, getUserId);
+ this.#sampling = sampling;
+ this.#propagationEnabled = false;
+ this.#enablement = this.#enablePropagation(config, sampling);
+ this.#provider = config.tracingProvider?.(resource, getUserId, sampling);
}
- span(name: string): Span {
- return this.#startSpan(name, context.active());
+ captureContext(): TraceContext {
+ const parent = context.active();
+ return { run: (operation) => context.with(parent, operation) };
}
- /** Starts a detached root span tree with user enrichment suppressed. */
- anonymousSpan(name: string): Span {
- return this.#startSpan(name, suppressUserId(ROOT_CONTEXT));
+ span(name: string, options: SpanOptions = {}): Span {
+ return this.#startSpan(name, context.active(), options);
}
- clientSpan(name: string): Span {
- return this.#startSpan(name, context.active(), SpanKind.CLIENT);
+ /** Starts a detached root span tree with user enrichment suppressed. */
+ anonymousSpan(name: string): Span {
+ return this.#startSpan(name, suppressUserId(ROOT_CONTEXT), {});
}
/** Export a timestamped measurement without retaining a long-lived span. */
- recordSample(name: string, attributes: Attributes, timestamp: number): void {
- const span = trace
- .getTracer(INSTRUMENTATION_SCOPE_NAME)
- .startSpan(name, { startTime: timestamp, attributes }, ROOT_CONTEXT);
+ recordSample(
+ name: string,
+ attributes: Attributes,
+ timestamp: number,
+ sampling?: SamplingClass
+ ): void {
+ const { otelSpan } = this.#startOtelSpan(name, ROOT_CONTEXT, {
+ sampling,
+ attributes,
+ startTime: timestamp,
+ });
// Historical samples must win over live onStart enrichment.
- span.setAttributes(attributes);
- span.end(timestamp);
+ otelSpan.setAttributes(attributes);
+ otelSpan.end(timestamp);
}
async flush(): Promise<void> {
+ await this.#enablement;
await this.#provider?.forceFlush();
}
@@ -55,14 +91,63 @@ export class Tracing {
this.#provider = undefined;
}
- #startSpan(name: string, parent: Context, kind?: SpanKind): Span {
- const otelSpan = trace
- .getTracer(INSTRUMENTATION_SCOPE_NAME)
- .startSpan(name, kind === undefined ? undefined : { kind }, parent);
+ #startOtelSpan(
+ name: string,
+ parent: Context,
+ options: StartOptions
+ ): { otelSpan: OtelSpan; parent: Context } {
+ const started = this.#sampling?.start(
+ parent,
+ options.phase ?? false,
+ options.sampling
+ );
+ const startParent = started?.context ?? parent;
+ const otelSpan = trace.getTracer(INSTRUMENTATION_SCOPE_NAME).startSpan(
+ name,
+ {
+ kind: options.kind === 'client' ? SpanKind.CLIENT : undefined,
+ attributes: options.attributes,
+ startTime: options.startTime,
+ },
+ startParent
+ );
+ if (started)
+ this.#sampling?.started(otelSpan, started.record, otelSpan.spanContext());
+ return { otelSpan, parent: startParent };
+ }
+
+ #startSpan(name: string, parent: Context, options: StartOptions): Span {
+ const { otelSpan, parent: startParent } = this.#startOtelSpan(
+ name,
+ parent,
+ options
+ );
+ const sampling = this.#sampling;
return new SpanImpl(
otelSpan,
- trace.setSpan(parent, otelSpan),
- (childName, childParent) => this.#startSpan(childName, childParent)
+ trace.setSpan(startParent, otelSpan),
+ (childName, childParent) =>
+ this.#startSpan(childName, childParent, { phase: true }),
+ () => this.#propagationEnabled,
+ () =>
+ trace.setSpanContext(
+ startParent,
+ sampling?.spanContext(otelSpan) ?? otelSpan.spanContext()
+ )
);
}
+
+ async #enablePropagation(
+ config: TelemetryInitConfig<string>,
+ sampling: TraceSampling
+ ): Promise<void> {
+ try {
+ const [enabled] = await Promise.all([config.enabled(), config.startup]);
+ // Spans started before enablement propagate once they are placed.
+ await sampling.decided;
+ this.#propagationEnabled = enabled;
+ } catch {
+ this.#propagationEnabled = false;
+ }
+ }
}
diff --git a/packages/observability/src/web.test.ts b/packages/observability/src/web.test.ts
index 4b1179f1a0..9cb7810828 100644
--- a/packages/observability/src/web.test.ts
+++ b/packages/observability/src/web.test.ts
@@ -8,6 +8,7 @@ import {
import { resourceFromAttributes } from '@opentelemetry/resources';
import type { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
import { afterEach, expect, test, vi } from 'vitest';
+import { TraceSampling } from './sampling';
import { Tracing } from './tracing';
import { createWebTracingProvider } from './web';
@@ -34,6 +35,8 @@ afterEach(() => {
test('recording exports even unsampled-parent spans with launch identity and memory at both boundaries', async () => {
let memory = 100;
+ const sampling = new TraceSampling();
+ sampling.decide(() => true);
const provider = createWebTracingProvider(
{
serviceName: 'web-app',
@@ -48,7 +51,8 @@ test('recording exports even unsampled-parent spans with launch identity and mem
'service.instance.id': 'launch-1',
'macro.recording.id': 'recording-1',
}),
- () => 'user-1'
+ () => 'user-1',
+ sampling
);
const parent = trace.setSpanContext(ROOT_CONTEXT, {
traceId: '11111111111111111111111111111111',
@@ -77,6 +81,8 @@ test('recording exports even unsampled-parent spans with launch identity and mem
});
test('buffered samples retain their native timestamp and values despite live enrichment', async () => {
+ const sampling = new TraceSampling();
+ sampling.decide(() => true);
const provider = createWebTracingProvider(
{
serviceName: 'web-app',
@@ -86,7 +92,8 @@ test('buffered samples retain their native timestamp and values despite live enr
spanAttributes: () => ({ 'macro.memory.native.rss_bytes': 999 }),
},
resourceFromAttributes({}),
- () => undefined
+ () => undefined,
+ sampling
);
new Tracing().recordSample(
'app.memory.sample',
@@ -100,3 +107,300 @@ test('buffered samples retain their native timestamp and values despite live enr
expect(sample?.attributes['macro.memory.native.rss_bytes']).toBe(123);
await provider.shutdown();
});
+
+test('an unsampled perf class drops its traces with their phases but keeps unclassed traces', async () => {
+ const sampling = new TraceSampling();
+ sampling.configure({ perf: 0.05 });
+ sampling.decide(() => false);
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: async () => true,
+ tracesUrl: 'http://localhost/v1/traces',
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const tracing = new Tracing();
+ tracing.init(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: async () => true,
+ tracingProvider: () => provider,
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const flow = tracing.span('home.load', { sampling: 'perf' });
+ flow.span('home.load.soup').end();
+ flow.end();
+ tracing.span('doc.open').end();
+ await tracing.flush();
+ expect(
+ exporters
+ .at(-1)
+ ?.getFinishedSpans()
+ .map((span) => span.name)
+ ).toEqual(['doc.open']);
+ expect(flow.traceparent()).toMatch(/-00$/);
+ await provider.shutdown();
+});
+
+test('every span in a kept classed trace carries its class and rate, including requests started in it', async () => {
+ const sampling = new TraceSampling();
+ sampling.configure({ always: 1, perf: 0.05 });
+ sampling.decide(() => true);
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: async () => true,
+ tracesUrl: 'http://localhost/v1/traces',
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const tracing = new Tracing();
+ tracing.init(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: async () => true,
+ tracingProvider: () => provider,
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const flow = tracing.span('view.home', { sampling: 'perf' });
+ const phase = flow.span('home.items');
+ phase.run(() => tracing.span('http GET /items', { kind: 'client' }).end());
+ phase.run(() => tracing.span('cache.write', { sampling: 'always' }).end());
+ phase.end();
+ flow.end();
+ tracing.span('doc.open').end();
+ await tracing.flush();
+ const tags = Object.fromEntries(
+ (exporters.at(-1)?.getFinishedSpans() ?? []).map((span) => [
+ span.name,
+ [
+ span.attributes['macro.sampling.class'],
+ span.attributes['macro.sampling.rate'],
+ ],
+ ])
+ );
+ expect(tags).toEqual({
+ 'http GET /items': ['perf', 0.05],
+ 'cache.write': ['always', 1],
+ 'home.items': ['perf', 0.05],
+ 'view.home': ['perf', 0.05],
+ 'doc.open': [undefined, undefined],
+ });
+ await provider.shutdown();
+});
+
+test('a span in a dropped trace starts its own trace when its class is kept, and is dropped when it is not', async () => {
+ const sampling = new TraceSampling();
+ sampling.configure({ always: 1, perf: 0.05 });
+ sampling.decide((samplingClass) => samplingClass === 'always');
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: async () => true,
+ tracesUrl: 'http://localhost/v1/traces',
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const tracing = new Tracing();
+ tracing.init(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: async () => true,
+ tracingProvider: () => provider,
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const flow = tracing.span('view.home', { sampling: 'perf' });
+ const phase = flow.span('home.items');
+ phase.run(() => {
+ const request = tracing.span('http GET /items', { kind: 'client' });
+ request.span('http GET /items.retry').end();
+ request.end();
+ tracing.span('cache.write', { sampling: 'always' }).end();
+ tracing.span('urql.reconcile', { sampling: 'perf' }).end();
+ });
+ phase.end();
+ flow.end();
+ await tracing.flush();
+ const spans = exporters.at(-1)?.getFinishedSpans() ?? [];
+ expect(spans.map((span) => span.name)).toEqual([
+ 'http GET /items.retry',
+ 'http GET /items',
+ 'cache.write',
+ ]);
+ const [retry, request, write] = spans;
+ expect(request.parentSpanContext).toBeUndefined();
+ expect(retry.parentSpanContext?.spanId).toBe(request.spanContext().spanId);
+ expect(retry.spanContext().traceId).toBe(request.spanContext().traceId);
+ expect(write.parentSpanContext).toBeUndefined();
+ expect(write.spanContext().traceId).not.toBe(request.spanContext().traceId);
+ expect(write.attributes['macro.sampling.class']).toBe('always');
+ expect(request.attributes['macro.sampling.class']).toBeUndefined();
+ await provider.shutdown();
+});
+
+test('a span started in a perf trace before the decision leaves it at export when perf is dropped', async () => {
+ let decide: (enabled: boolean) => void = () => {};
+ const decision = new Promise<boolean>((resolve) => {
+ decide = resolve;
+ });
+ const sampling = new TraceSampling();
+ sampling.configure({ perf: 0.05 });
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: () => decision,
+ tracesUrl: 'http://localhost/v1/traces',
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const tracing = new Tracing();
+ tracing.init(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: () => decision,
+ tracingProvider: () => provider,
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const boot = tracing.span('app.boot', { sampling: 'perf' });
+ const request = boot.run(() =>
+ tracing.span('http GET /items', { kind: 'client' })
+ );
+ const parse = request.span('http GET /items.parse');
+ parse.end();
+ boot.end();
+ decide(true);
+ sampling.decide(() => false);
+ await tracing.flush();
+ const headers: Record<string, string> = {};
+ request.injectTraceHeaders(headers);
+ const late = request.span('http GET /items.read');
+ late.end();
+ request.end();
+ await tracing.flush();
+ const spans = exporters.at(-1)?.getFinishedSpans() ?? [];
+ expect(spans.map((span) => span.name)).toEqual([
+ 'http GET /items.parse',
+ 'http GET /items.read',
+ 'http GET /items',
+ ]);
+ const [early, read, root] = spans;
+ const traceId = root.spanContext().traceId;
+ expect(traceId).not.toBe(boot.traceparent()?.split('-')[1]);
+ expect(root.parentSpanContext).toBeUndefined();
+ expect(early.spanContext().traceId).toBe(traceId);
+ expect(read.spanContext().traceId).toBe(traceId);
+ expect(read.parentSpanContext?.spanId).toBe(root.spanContext().spanId);
+ expect(headers.traceparent).toBe(
+ `00-${traceId}-${root.spanContext().spanId}-01`
+ );
+ await provider.shutdown();
+});
+
+test('early spans keep explicit async parentage and wait for exporter enablement', async () => {
+ let decide: (enabled: boolean) => void = () => {};
+ const decision = new Promise<boolean>((resolve) => {
+ decide = resolve;
+ });
+ const count = exporters.length;
+ const { StackContextManager } = await import('./web');
+ const sampling = new TraceSampling();
+ sampling.configure({ perf: 0.05 });
+ const provider = createWebTracingProvider(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ tracesUrl: 'http://localhost/v1/traces',
+ enabled: () => decision,
+ contextManager: new StackContextManager(),
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const tracing = new Tracing();
+ tracing.init(
+ {
+ serviceName: 'web-app',
+ environment: 'test',
+ enabled: () => decision,
+ tracingProvider: () => provider,
+ },
+ resourceFromAttributes({}),
+ () => undefined,
+ sampling
+ );
+ const boot = tracing.span('app.boot', {
+ sampling: 'perf',
+ startTime: 1700000000000,
+ });
+ const document = boot.span('doc.open');
+ await Promise.resolve();
+ const load = document.span('doc.load');
+ load.end();
+ const mutation = boot.span('graphql.mutation_queue.attempt');
+ await Promise.resolve();
+ const transport = mutation.run(() =>
+ tracing.span('graphql.transport', { kind: 'client' })
+ );
+ const headers: Record<string, string> = {};
+ transport.injectTraceHeaders(headers);
+ expect(headers).toEqual({});
+ expect(boot.traceparent()).toBeUndefined();
+ transport.end();
+ mutation.end();
+ document.end();
+ boot.event('macro.boot.render-start', undefined, 1700000000050);
+ boot.end(1700000000100);
+ expect(exporters).toHaveLength(count);
+ decide(true);
+ sampling.decide(() => true);
+ await tracing.flush();
+ expect(boot.traceparent()).toBeDefined();
+ const spans = exporters.at(-1)?.getFinishedSpans() ?? [];
+ const root = spans.find((span) => span.name === 'app.boot');
+ expect(root?.startTime).toEqual([1700000000, 0]);
+ expect(root?.endTime).toEqual([1700000000, 100000000]);
+ expect(root?.events[0].time).toEqual([1700000000, 50000000]);
+ expect(new Set(spans.map((span) => span.spanContext().traceId)).size).toBe(1);
+ expect(
+ spans.find((span) => span.name === 'doc.load')?.parentSpanContext?.spanId
+ ).toBe(spans.find((span) => span.name === 'doc.open')?.spanContext().spanId);
+ expect(
+ spans.find((span) => span.name === 'graphql.transport')?.parentSpanContext
+ ?.spanId
+ ).toBe(
+ spans
+ .find((span) => span.name === 'graphql.mutation_queue.attempt')
+ ?.spanContext().spanId
+ );
+ await provider.shutdown();
+});
diff --git a/packages/observability/src/web.ts b/packages/observability/src/web.ts
index 82d631c99f..012efbd575 100644
--- a/packages/observability/src/web.ts
+++ b/packages/observability/src/web.ts
@@ -2,24 +2,51 @@ import { W3CTraceContextPropagator } from '@opentelemetry/core';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import type { Resource } from '@opentelemetry/resources';
import {
- AlwaysOnSampler,
BatchSpanProcessor,
+ NoopSpanProcessor,
+ type SpanProcessor,
} from '@opentelemetry/sdk-trace-base';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import type { TelemetryInitConfig } from './config';
import { ATTR_USER_ID } from './constants';
+import { DeferredSpanProcessor } from './deferred-span-processor';
import { userIdSuppressed } from './privacy';
import type { TelemetryTracingProvider } from './provider';
+import type { TraceSampling } from './sampling';
/** Creates the browser OpenTelemetry provider used by the web application. */
export function createWebTracingProvider(
- config: TelemetryInitConfig,
+ config: TelemetryInitConfig<string>,
resource: Resource,
- getUserId: () => string | undefined
+ getUserId: () => string | undefined,
+ sampling: TraceSampling
): TelemetryTracingProvider {
+ const createExporter = async (): Promise<SpanProcessor> => {
+ const settings = config.startup ? await config.startup : config;
+ // Buffered spans are placed by the classes decided at enablement.
+ await sampling.decided;
+ if (!settings.tracesUrl) return new NoopSpanProcessor();
+ const processor = new BatchSpanProcessor(
+ new OTLPTraceExporter({
+ url: settings.tracesUrl,
+ fetch: config.exportFetch,
+ }),
+ // Native recordings can replay up to 3600 samples after a pause.
+ settings.recording ? { maxQueueSize: 8192 } : undefined
+ );
+ return {
+ onStart: (span, parent) => processor.onStart(span, parent),
+ onEnd: (span) => {
+ const exported = sampling.exported(span);
+ if (exported) processor.onEnd(exported);
+ },
+ forceFlush: () => processor.forceFlush(),
+ shutdown: () => processor.shutdown(),
+ };
+ };
const provider = new WebTracerProvider({
resource,
- ...(config.recording && { sampler: new AlwaysOnSampler() }),
+ sampler: sampling,
spanProcessors: [
{
onStart: (span, parentContext) => {
@@ -38,14 +65,8 @@ export function createWebTracingProvider(
forceFlush: () => Promise.resolve(),
shutdown: () => Promise.resolve(),
},
- ...(config.tracesUrl
- ? [
- new BatchSpanProcessor(
- new OTLPTraceExporter({ url: config.tracesUrl }),
- // The native recorder can replay up to 3600 samples after a pause.
- config.recording ? { maxQueueSize: 8192 } : undefined
- ),
- ]
+ ...(config.tracesUrl || config.startup
+ ? [new DeferredSpanProcessor(config.enabled(), createExporter)]
: []),
],
});
@@ -53,5 +74,11 @@ export function createWebTracingProvider(
...(config.contextManager && { contextManager: config.contextManager }),
propagator: new W3CTraceContextPropagator(),
});
- return provider;
+ return {
+ getTracer: (...args) => provider.getTracer(...args),
+ forceFlush: () => provider.forceFlush(),
+ shutdown: () => provider.shutdown(),
+ };
}
+
+export { StackContextManager } from '@opentelemetry/sdk-trace-web';
diff --git a/packages/observability/src/worker.ts b/packages/observability/src/worker.ts
index 808dbb8da8..822640efcf 100644
--- a/packages/observability/src/worker.ts
+++ b/packages/observability/src/worker.ts
@@ -1,29 +1,29 @@
// Cloudflare Workers entry. Importing @microlabs/otel-cf-workers loads the
// `cloudflare:workers` module at module scope, so this stays in its own entry
-// (like zone.ts) and must only be imported from code that runs in workerd.
+// and must only be imported from code that runs in workerd.
import {
- BatchTraceSpanProcessor,
- instrument,
- instrumentDO,
- OTLPExporter,
- type TraceConfig,
-} from "@microlabs/otel-cf-workers";
-import type { Context, Span } from "@opentelemetry/api";
-import { ATTR_DEPLOYMENT_ENVIRONMENT, ATTR_USER_ID } from "./constants";
-import { userIdSuppressed } from "./privacy";
+ BatchTraceSpanProcessor,
+ instrument,
+ instrumentDO,
+ OTLPExporter,
+ type TraceConfig,
+} from '@microlabs/otel-cf-workers';
+import type { Context, Span } from '@opentelemetry/api';
+import { ATTR_DEPLOYMENT_ENVIRONMENT, ATTR_USER_ID } from './constants';
+import { userIdSuppressed } from './privacy';
export type { TraceConfig };
export { instrument, instrumentDO };
export interface WorkerTraceConfigOptions {
- serviceName: string;
- environment: string;
- /** OTLP/HTTP traces endpoint. Spans are not exported when unset. */
- tracesUrl?: string;
- /** Extra headers for the export request (e.g. an intake API key). */
- tracesHeaders?: Record<string, string>;
- /** Read the current user id; called once per span when it starts. */
- getUserId?: () => string | undefined;
+ serviceName: string;
+ environment: string;
+ /** OTLP/HTTP traces endpoint. Spans are not exported when unset. */
+ tracesUrl?: string;
+ /** Extra headers for the export request (e.g. an intake API key). */
+ tracesHeaders?: Record<string, string>;
+ /** Read the current user id; called once per span when it starts. */
+ getUserId?: () => string | undefined;
}
/**
@@ -41,32 +41,32 @@ export interface WorkerTraceConfigOptions {
* environment (and user id) are stamped onto every span here.
*/
export function createWorkerTraceConfig(
- options: WorkerTraceConfigOptions,
+ options: WorkerTraceConfigOptions
): TraceConfig {
- return {
- service: { name: options.serviceName },
- spanProcessors: [
- {
- onStart: (span: Span, parentContext: Context) => {
- span.setAttribute(ATTR_DEPLOYMENT_ENVIRONMENT, options.environment);
- if (userIdSuppressed(parentContext)) return;
- const userId = options.getUserId?.();
- if (userId !== undefined) span.setAttribute(ATTR_USER_ID, userId);
- },
- onEnd: () => {},
- forceFlush: () => Promise.resolve(),
- shutdown: () => Promise.resolve(),
- },
- ...(options.tracesUrl
- ? [
- new BatchTraceSpanProcessor(
- new OTLPExporter({
- url: options.tracesUrl,
- headers: options.tracesHeaders,
- }),
- ),
- ]
- : []),
- ],
- };
+ return {
+ service: { name: options.serviceName },
+ spanProcessors: [
+ {
+ onStart: (span: Span, parentContext: Context) => {
+ span.setAttribute(ATTR_DEPLOYMENT_ENVIRONMENT, options.environment);
+ if (userIdSuppressed(parentContext)) return;
+ const userId = options.getUserId?.();
+ if (userId !== undefined) span.setAttribute(ATTR_USER_ID, userId);
+ },
+ onEnd: () => {},
+ forceFlush: () => Promise.resolve(),
+ shutdown: () => Promise.resolve(),
+ },
+ ...(options.tracesUrl
+ ? [
+ new BatchTraceSpanProcessor(
+ new OTLPExporter({
+ url: options.tracesUrl,
+ headers: options.tracesHeaders,
+ })
+ ),
+ ]
+ : []),
+ ],
+ };
}
diff --git a/packages/observability/src/zone.ts b/packages/observability/src/zone.ts
deleted file mode 100644
index 2340ab0544..0000000000
--- a/packages/observability/src/zone.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-// Importing context-zone loads zone.js, which patches Promise & friends as a
-// module side effect, quarantined in its own entry so it never rides into
-// non-browser consumers. Hosts must import this statically at startup: patching
-// lazily is unreliable, since context would not flow through Promises created
-// before the patch.
-export { ZoneContextManager } from "@opentelemetry/context-zone";
diff --git a/packages/observability/tsconfig.json b/packages/observability/tsconfig.json
index b231a634a4..973fa46eee 100644
--- a/packages/observability/tsconfig.json
+++ b/packages/observability/tsconfig.json
@@ -13,6 +13,6 @@
"target": "ESNext",
"types": ["@types/bun", "@types/node"]
},
- "include": ["src/**/*"],
+ "include": ["src/**/*", "browser-test/**/*"],
"exclude": ["node_modules"]
}
diff --git a/rules/ast-grep/ts-observability-facade.yml b/rules/ast-grep/ts-observability-facade.yml
new file mode 100644
index 0000000000..cdb0e5f3d0
--- /dev/null
+++ b/rules/ast-grep/ts-observability-facade.yml
@@ -0,0 +1,14 @@
+id: ts-observability-facade
+language: typescript
+severity: error
+message: Use the observability facade and explicit parents; browser async context must not depend on global patches.
+files:
+ - apps/web/src/**
+ignores:
+ - '**/*.test.ts'
+ - '**/*.test.tsx'
+ - '**/*.spec.ts'
+ - '**/*.spec.tsx'
+rule:
+ kind: string
+ regex: ^['"](@opentelemetry/[^'"]+|zone\.js[^'"]*|@macro-inc/observability/zone)['"]$
diff --git a/rules/ast-grep/tsx-observability-facade.yml b/rules/ast-grep/tsx-observability-facade.yml
new file mode 100644
index 0000000000..2c19200228
--- /dev/null
+++ b/rules/ast-grep/tsx-observability-facade.yml
@@ -0,0 +1,14 @@
+id: tsx-observability-facade
+language: tsx
+severity: error
+message: Use the observability facade and explicit parents; browser async context must not depend on global patches.
+files:
+ - apps/web/src/**
+ignores:
+ - '**/*.test.ts'
+ - '**/*.test.tsx'
+ - '**/*.spec.ts'
+ - '**/*.spec.tsx'
+rule:
+ kind: string
+ regex: ^['"](@opentelemetry/[^'"]+|zone\.js[^'"]*|@macro-inc/observability/zone)['"]$