Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix(web): retain captured page trace ownership and exact resource identity (#978)

Gener79151531a76b
diff --git a/src/app/scripts/bundle.ts b/src/app/scripts/bundle.ts
index 45af97631..7c1f7836c 100644
--- a/src/app/scripts/bundle.ts
+++ b/src/app/scripts/bundle.ts
@@ -61,7 +61,7 @@ cpSync(join(webSrc, "wrangler.toml"), join(webDest, "wrangler.toml"));
cpSync(join(webSrc, "custom-worker.ts"), join(webDest, "custom-worker.ts"));
mkdirSync(join(webDest, "src", "lib"), { recursive: true });
mkdirSync(join(webDest, "src", "lib", "observability"), { recursive: true });
-for (const runtimeFile of ["worker-runtime.ts", "public-worker-response.ts", "observability/build.ts", "observability/coverage.ts", "observability/schema.ts"]) {
+for (const runtimeFile of ["worker-runtime.ts", "public-worker-response.ts", "observability/build.ts", "observability/coverage.ts", "observability/schema.ts", "observability/trace-response.ts"]) {
cpSync(
join(webSrc, "src", "lib", runtimeFile),
join(webDest, "src", "lib", runtimeFile),
diff --git a/src/app/test/packed-artifact.test.ts b/src/app/test/packed-artifact.test.ts
index 73c89daef..39607356d 100644
--- a/src/app/test/packed-artifact.test.ts
+++ b/src/app/test/packed-artifact.test.ts
@@ -1,7 +1,8 @@
import { afterEach, describe, expect, it, vi } from "vitest";
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import ts from "typescript";
const mocks = vi.hoisted(() => ({
spawnSync: vi.fn(),
@@ -39,7 +40,7 @@ afterEach(() => {
});
describe("packed artifact verifier", () => {
- it("copies the Worker runtime into the packaged entry's relative import path", async () => {
+ it("copies the real Worker runtime module closure into the packaged entry's relative paths", async () => {
const execSync = vi.fn();
const cpSync = vi.fn();
const mkdirSync = vi.fn();
@@ -72,20 +73,23 @@ describe("packed artifact verifier", () => {
const monoRoot = join(appRoot, "..", "..");
const webDest = join(appRoot, "bundled", "web");
expect(mkdirSync).toHaveBeenCalledWith(join(webDest, "src", "lib"), { recursive: true });
- expect(cpSync).toHaveBeenCalledWith(
- join(monoRoot, "src", "web", "src", "lib", "worker-runtime.ts"),
- join(webDest, "src", "lib", "worker-runtime.ts"),
- );
- expect(cpSync).toHaveBeenCalledWith(
- join(monoRoot, "src", "web", "src", "lib", "public-worker-response.ts"),
- join(webDest, "src", "lib", "public-worker-response.ts"),
- );
expect(mkdirSync).toHaveBeenCalledWith(join(webDest, "src", "lib", "observability"), { recursive: true });
- for (const name of ["build.ts", "coverage.ts", "schema.ts"]) {
- expect(cpSync).toHaveBeenCalledWith(
- join(monoRoot, "src", "web", "src", "lib", "observability", name),
- join(webDest, "src", "lib", "observability", name),
- );
+ const copies = new Map(cpSync.mock.calls.map(([source, destination]) => [source, destination]));
+ const pending = [[join(monoRoot, "src", "web", "src", "lib", "worker-runtime.ts"), join(webDest, "src", "lib", "worker-runtime.ts")]];
+ const visited = new Set<string>();
+ for (const [source, destination] of pending) {
+ if (visited.has(source)) continue;
+ visited.add(source);
+ expect(copies.get(source), `packaged runtime dependency: ${source}`).toBe(destination);
+ const module = ts.createSourceFile(source, readFileSync(source, "utf8"), ts.ScriptTarget.Latest);
+ for (const statement of module.statements) {
+ if ((!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement))
+ || (ts.isImportDeclaration(statement) ? statement.importClause?.isTypeOnly : statement.isTypeOnly)) continue;
+ const specifier = statement.moduleSpecifier;
+ if (!specifier || !ts.isStringLiteral(specifier) || !specifier.text.startsWith(".")) continue;
+ const dependency = `${specifier.text}.ts`;
+ pending.push([join(dirname(source), dependency), join(dirname(destination), dependency)]);
+ }
}
});
diff --git a/src/web/src/components/community/shell/shell-frame-types.ts b/src/web/src/components/community/shell/shell-frame-types.ts
index 203e6d0d5..154ce099e 100644
--- a/src/web/src/components/community/shell/shell-frame-types.ts
+++ b/src/web/src/components/community/shell/shell-frame-types.ts
@@ -1,3 +1,4 @@
+import type { Action } from "@/lib/observability/context"
import type { ReactNode } from "react"
import type { OwnerServerDeleteRouteToken } from "@/lib/community/eject-server"
import type { View } from "./shell-types"
@@ -20,6 +21,6 @@ export type ShellFrameProps = {
export type ShellRouter = {
captureIntent?: () => () => boolean
push: (href: string) => void
- pushImmediate?: (href: string) => void
+ pushImmediate?: (href: string, prepare?: (action?: Action) => void) => void
replace: (href: string) => void
}
diff --git a/src/web/src/components/community/shell/use-community-navigation-controller.dom.test.ts b/src/web/src/components/community/shell/use-community-navigation-controller.dom.test.ts
index 4cf1712c1..d9f214cc2 100644
--- a/src/web/src/components/community/shell/use-community-navigation-controller.dom.test.ts
+++ b/src/web/src/components/community/shell/use-community-navigation-controller.dom.test.ts
@@ -3,6 +3,8 @@ import { act, render as rtlRender } from "@/test/react-dom-harness"
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
import { useCommunityNavigationController } from "./use-community-navigation-controller"
import { normalizeCommunityHref, type CommunityCommittedFrame } from "@/lib/community/community-route"
+import { navigationForHref, clearActions } from "@/lib/observability/context"
+import { configureTelemetry, retireTelemetry } from "@/lib/observability/telemetry"
const mocks = vi.hoisted(() => ({
pathname: { current: "/c/me" },
@@ -283,4 +285,19 @@ describe("useCommunityNavigationController", () => {
expect(mocks.push).toHaveBeenCalledWith("/c/channels/s1/c1")
expect(mocks.cancelProof).not.toHaveBeenCalled()
})
+
+ it("prepares Inbox transport with its actual navigation before router submission", async () => {
+ Object.defineProperty(window, "location", { value: { origin: "https://alook.test", href: "https://alook.test/c/me" } })
+ configureTelemetry({ session_id: "chain-session" }, true)
+ const hook = await renderController(), href = "/c/channels/s1/c1"
+ const prepare = vi.fn(action => {
+ expect(action).toBe(navigationForHref(href))
+ expect(action?.done).toBe(false)
+ expect(mocks.push).not.toHaveBeenCalled()
+ })
+ await act(async () => hook.current.pushImmediate(href, prepare))
+ expect(prepare).toHaveBeenCalledOnce()
+ expect(mocks.push).toHaveBeenCalledExactlyOnceWith(href)
+ retireTelemetry(); clearActions()
+ })
})
diff --git a/src/web/src/components/community/shell/use-community-navigation-controller.ts b/src/web/src/components/community/shell/use-community-navigation-controller.ts
index a0df5ae54..fa68c20ef 100644
--- a/src/web/src/components/community/shell/use-community-navigation-controller.ts
+++ b/src/web/src/components/community/shell/use-community-navigation-controller.ts
@@ -1,6 +1,6 @@
"use client"
-import { beginNavigation, navigationNoop } from "@/lib/observability/context"
+import { beginNavigation, navigationNoop, type Action } from "@/lib/observability/context"
import { prepareNavigationMetadata } from "@/lib/community/navigation-metadata"
import { useAtom, useCreateAtom } from "@tanstack/react-store";
@@ -139,9 +139,10 @@ export function useCommunityNavigationController(
submitNavigation(() => router.push(...args))
}, [committedFrame.leafKey, committedFrame.revision, navigationPending, publishedHref, queryClient, router, setNavigationPending, setPendingHref, submitNavigation])
- const pushImmediate = useCallback((href: string) => {
- if (href === publishedHref && !navigationPending) { settledIntentRef.current = null; navigationNoop(href); return }
- beginNavigation(href)
+ const pushImmediate = useCallback((href: string, prepare?: (action?: Action) => void) => {
+ if (href === publishedHref && !navigationPending) { settledIntentRef.current = null; navigationNoop(href); prepare?.(); return }
+ const action = beginNavigation(href)
+ prepare?.(action)
void prepareNavigationMetadata(queryClient, href, "foreground")
supersedeNavigationIntent(gateRef.current)
pendingBaselineRevisionRef.current = committedFrame.revision
diff --git a/src/web/src/components/community/shell/use-shell-inbox-controller.dom.test.ts b/src/web/src/components/community/shell/use-shell-inbox-controller.dom.test.ts
index acfc6baa9..c9c1e941a 100644
--- a/src/web/src/components/community/shell/use-shell-inbox-controller.dom.test.ts
+++ b/src/web/src/components/community/shell/use-shell-inbox-controller.dom.test.ts
@@ -494,7 +494,7 @@ describe("useShellInboxController", () => {
expect(mocks.warmup).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
href: "/c/channels/s1/c1?seq=7",
anchorMessageId: "message-7",
- }), 0)
+ }), 0, 0, undefined)
expect(mocks.begin).not.toHaveBeenCalled()
})
diff --git a/src/web/src/components/community/shell/use-shell-inbox-controller.ts b/src/web/src/components/community/shell/use-shell-inbox-controller.ts
index 4e90ab44a..bbc84c190 100644
--- a/src/web/src/components/community/shell/use-shell-inbox-controller.ts
+++ b/src/web/src/components/community/shell/use-shell-inbox-controller.ts
@@ -1,5 +1,6 @@
"use client"
+import type { Action } from "@/lib/observability/context"
import { useAtom, useCreateAtom } from "@tanstack/react-store";
import { useCallback, useRef, type ComponentProps } from "react"
import { channelHref } from "@/lib/community/community-route"
@@ -61,9 +62,9 @@ export function useShellInboxController({
viewerId,
accessEpoch,
}: Options) {
- const pushInboxHref = useCallback((href: string) => {
- if (router.pushImmediate) router.pushImmediate(href)
- else router.push(href)
+ const pushInboxHref = useCallback((href: string, prepare?: (action?: Action) => void) => {
+ if (router.pushImmediate) router.pushImmediate(href, prepare)
+ else { prepare?.(); router.push(href) }
}, [router])
const attention = useInboxAttention()
const unreadFeed = attention.servers
@@ -124,18 +125,18 @@ export function useShellInboxController({
const epoch = inbox.beginProjection(target, destinationHref)
cancelPendingNavigation()
clearThreadOpenerReadHandoff(queryClient)
- const proofEpoch = startConversationNavigationWarmup(queryClient, {
- ...warmup,
- href: destinationHref,
- viewerId,
- }, accessEpoch)
+ let proofEpoch: number | undefined
let pushedHref = destinationHref
try {
pushedHref = prepare?.() ?? destinationHref
- pushInboxHref(pushedHref)
+ pushInboxHref(pushedHref, action => {
+ proofEpoch = startConversationNavigationWarmup(queryClient, {
+ ...warmup, href: destinationHref, viewerId,
+ }, accessEpoch, 0, action)
+ })
if (inbox.markProjectionSubmitted(epoch)) afterPush?.()
} catch (error) {
- cancelConversationNavigationProof(queryClient, proofEpoch)
+ if (proofEpoch !== undefined) cancelConversationNavigationProof(queryClient, proofEpoch)
const nonce = new URLSearchParams(pushedHref.split("?")[1] ?? "")
.get("inboxThreadOpener")
if (nonce) terminateThreadOpenerReservationHandoff(queryClient, nonce)
@@ -160,18 +161,20 @@ export function useShellInboxController({
const previousOpen = inbox.closeWithoutProjection()
cancelPendingNavigation()
clearThreadOpenerReadHandoff(queryClient)
- const proofEpoch = startConversationNavigationWarmup(queryClient, {
- href,
- viewerId,
- channelId: channel.channelId,
- serverId: server.serverId,
- scopeKind: "channel",
- expectedSurfaceKind: channel.type === "forum" ? "forum" : "channel",
- }, accessEpoch)
+ let proofEpoch: number | undefined
try {
- pushInboxHref(href)
+ pushInboxHref(href, action => {
+ proofEpoch = startConversationNavigationWarmup(queryClient, {
+ href,
+ viewerId,
+ channelId: channel.channelId,
+ serverId: server.serverId,
+ scopeKind: "channel",
+ expectedSurfaceKind: channel.type === "forum" ? "forum" : "channel",
+ }, accessEpoch, 0, action)
+ })
} catch (error) {
- cancelConversationNavigationProof(queryClient, proofEpoch)
+ if (proofEpoch !== undefined) cancelConversationNavigationProof(queryClient, proofEpoch)
cancelPendingNavigation()
inbox.onOpenChange(previousOpen)
throw error
@@ -221,19 +224,21 @@ export function useShellInboxController({
const href = marked.serverId
? `${channelHref(marked.serverId, marked.channelId)}${seqQuery}`
: `/c/me/${marked.channelId}${seqQuery}`
- const proofEpoch = startConversationNavigationWarmup(queryClient, {
- href,
- viewerId,
- channelId: marked.channelId,
- ...(marked.serverId ? { serverId: marked.serverId } : {}),
- scopeKind: marked.serverId ? "channel" : "dm",
- ...(marked.serverId ? { anchorMessageId: marked.m.id } : {}),
- ...(!marked.serverId ? { expectedSurfaceKind: "dm" as const } : {}),
- }, accessEpoch)
+ let proofEpoch: number | undefined
try {
- pushInboxHref(href)
+ pushInboxHref(href, action => {
+ proofEpoch = startConversationNavigationWarmup(queryClient, {
+ href,
+ viewerId,
+ channelId: marked.channelId,
+ ...(marked.serverId ? { serverId: marked.serverId } : {}),
+ scopeKind: marked.serverId ? "channel" : "dm",
+ ...(marked.serverId ? { anchorMessageId: marked.m.id } : {}),
+ ...(!marked.serverId ? { expectedSurfaceKind: "dm" as const } : {}),
+ }, accessEpoch, 0, action)
+ })
} catch (error) {
- cancelConversationNavigationProof(queryClient, proofEpoch)
+ if (proofEpoch !== undefined) cancelConversationNavigationProof(queryClient, proofEpoch)
cancelPendingNavigation()
inbox.onOpenChange(previousOpen)
throw error
diff --git a/src/web/src/contexts/community/route-frame.tsx b/src/web/src/contexts/community/route-frame.tsx
index 5a35b9a98..d605bae45 100644
--- a/src/web/src/contexts/community/route-frame.tsx
+++ b/src/web/src/contexts/community/route-frame.tsx
@@ -1,5 +1,6 @@
"use client"
+import type { Action } from "@/lib/observability/context"
import { createContext, useContext, type RefObject } from "react"
import type { useRouter } from "next/navigation"
import type { Breakpoint } from "@/hooks/use-mobile"
@@ -12,7 +13,7 @@ export type CommunityNavigationController = {
navigationPending: boolean
pendingHref: string | null
push: ReturnType<typeof useRouter>["push"]
- pushImmediate: (href: string) => void
+ pushImmediate: (href: string, prepare?: (action?: Action) => void) => void
replace: (href: string) => void
resolveAndPush: (resolve: () => Promise<string>) => Promise<boolean>
cancelPendingNavigation: () => void
diff --git a/src/web/src/hooks/community/community-ws/registry.ts b/src/web/src/hooks/community/community-ws/registry.ts
index 9a0888dd5..e56c3ab29 100644
--- a/src/web/src/hooks/community/community-ws/registry.ts
+++ b/src/web/src/hooks/community/community-ws/registry.ts
@@ -1,6 +1,6 @@
import { getCommunityRuntime } from "@/stores/community/runtime"
-import { telemetryId } from "@/lib/observability/context"
+import { telemetryId, currentPageObservation, startPageOperation, finishPageOperation, pageOperationAttributes, type PageOperation } from "@/lib/observability/context"
import { emitTelemetry } from "@/lib/observability/telemetry"
import type { CommunityWsEvent } from "@alook/shared"
@@ -168,7 +168,7 @@ export function dispatchCommunityWsEvents(
messageEvent: creates[0]!,
})
}
- const receipts: Array<{ id: string; start: number; type: CommunityEventType }> = []
+ const receipts: Array<{ id: string; start: number; type: CommunityEventType; operation?: PageOperation }> = []
try { runCommunityWsProjectionTransaction(context.queryClient, (projection) => {
const handlerContext: CommunityWsHandlerContext = {
...context,
@@ -188,7 +188,7 @@ export function dispatchCommunityWsEvents(
&& getCommunityRuntime(context.queryClient).ws.actions.isChannelAccessRevoked(channelId, serverId, parentChannelId ?? undefined)) continue
if (channelId && serverId) getCommunityRuntime(context.queryClient).ws.actions.observeChannelScope(serverId, channelId, parentChannelId)
const entry = communityWsRegistry[event.type] as RegistryEntry<typeof event.type>
- const receipt = { id: telemetryId(), start: performance.now(), type: event.type }
+ const receipt = { id: telemetryId(), start: performance.now(), type: event.type, operation: startPageOperation("ws.event_applied", { phase: "commit", source: "ws", event_type: event.type }, currentPageObservation()) }
receipts.push(receipt)
entry.handler(event, handlerContext)
if (event.type !== "community:message.create") projectCommunityWsEventToDb(context.queryClient, event, context.contract)
@@ -202,10 +202,16 @@ export function dispatchCommunityWsEvents(
}
}
}) } catch (error) {
- for (const receipt of receipts) emitTelemetry("ws.event_applied", { ws_event_id: receipt.id, event_type: receipt.type, duration_ms: performance.now() - receipt.start, source: "ws", outcome: "partial", eligibility: "unknown" })
+ for (const receipt of receipts) {
+ finishPageOperation(receipt.operation, "partial")
+ emitTelemetry("ws.event_applied", { ...pageOperationAttributes(receipt.operation), ws_event_id: receipt.id, event_type: receipt.type, duration_ms: performance.now() - receipt.start, source: "ws", outcome: "partial", eligibility: "unknown" })
+ }
throw error
}
- for (const receipt of receipts) emitTelemetry("ws.event_applied", { ws_event_id: receipt.id, event_type: receipt.type, duration_ms: performance.now() - receipt.start, source: "ws", outcome: "success", eligibility: "eligible" })
+ for (const receipt of receipts) {
+ finishPageOperation(receipt.operation, "success")
+ emitTelemetry("ws.event_applied", { ...pageOperationAttributes(receipt.operation), ws_event_id: receipt.id, event_type: receipt.type, duration_ms: performance.now() - receipt.start, source: "ws", outcome: "success", eligibility: "eligible" })
+ }
}
export const communityWsReconnectPolicies = Array.from(new Set(
diff --git a/src/web/src/hooks/community/use-messages.observation.dom.test.ts b/src/web/src/hooks/community/use-messages.observation.dom.test.ts
new file mode 100644
index 000000000..0ba552605
--- /dev/null
+++ b/src/web/src/hooks/community/use-messages.observation.dom.test.ts
@@ -0,0 +1,86 @@
+import { createElement, type PropsWithChildren } from "react"
+import { ROOT_CONTEXT, SpanKind, context, trace } from "@opentelemetry/api"
+import { InMemorySpanExporter, SimpleSpanProcessor, WebTracerProvider } from "@opentelemetry/sdk-trace-web"
+import { COMMUNITY_CONTRACT_HEADER, COMMUNITY_CONTRACT_VERSION } from "@alook/shared"
+import { afterEach, expect, it, vi } from "vitest"
+import { CommunityTestProvider } from "@/test/community-owner-fixture"
+import { createCommunityQueryOwner } from "@/test/community-query-owner"
+import { act, renderHook, waitFor } from "@/test/react-dom-harness"
+import { beginNavigation, clearActions, commitNavigation, finishAction, installActionSpans } from "@/lib/observability/context"
+import { observeTransportSpan } from "@/lib/observability/requests"
+import { configureTelemetry, installTelemetrySink, retireTelemetry } from "@/lib/observability/telemetry"
+import { useDmMessages, useMessages } from "./use-messages"
+
+const providers: WebTracerProvider[] = []
+
+afterEach(async () => {
+ retireTelemetry()
+ clearActions()
+ installActionSpans(undefined)
+ await Promise.all(providers.splice(0).map(provider => provider.shutdown()))
+ context.disable()
+ trace.disable()
+ vi.unstubAllGlobals()
+ window.history.replaceState(null, "", "/")
+})
+
+it.each(["channel", "dm"] as const)("keeps real %s API events and native spans on their captured page across a new commit", async kind => {
+ const exporter = new InMemorySpanExporter()
+ const provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ providers.push(provider)
+ provider.register()
+ const tracer = provider.getTracer("alook.frontend")
+ configureTelemetry({ session_id: "message-page-owner" }, true)
+ const events: Array<{ name: string; attributes: Record<string, string> }> = []
+ installTelemetrySink(event => events.push(event))
+ installActionSpans((name, attributes, startTime, links, parent) => tracer.startSpan(name, { attributes, startTime, links }, parent ? trace.setSpan(ROOT_CONTEXT, parent) : ROOT_CONTEXT))
+ vi.stubGlobal("fetch", vi.fn(async () => {
+ const span = tracer.startSpan("GET messages", { kind: SpanKind.CLIENT })
+ observeTransportSpan(span)
+ span.end()
+ return Response.json({
+ contractVersion: COMMUNITY_CONTRACT_VERSION,
+ channelId: "channel-a",
+ messages: [],
+ page: { olderCursor: null, newerCursor: null, hasMoreOlder: false, hasMoreNewer: false, latestSeq: 0 },
+ surfaceReceipt: { channelId: "channel-a", surfaceKind: kind },
+ }, { headers: { [COMMUNITY_CONTRACT_HEADER]: String(COMMUNITY_CONTRACT_VERSION) } })
+ }))
+ const href = kind === "channel" ? "/c/channels/server-a/channel-a" : "/c/me/channel-a"
+ window.history.replaceState(null, "", href)
+ const owner = beginNavigation(href)!
+ commitNavigation(href)
+ const { client } = await createCommunityQueryOwner()
+ const useSurface = kind === "channel" ? useMessages : useDmMessages
+ function wrapper({ children }: PropsWithChildren) {
+ return createElement(CommunityTestProvider, { client }, children)
+ }
+ let rendered!: ReturnType<typeof renderHook<ReturnType<typeof useMessages>, unknown>>
+ await act(async () => {
+ rendered = renderHook(() => useSurface("channel-a", { serverId: "server-a", lastReadMessageId: null }), { wrapper })
+ })
+ await waitFor(() => expect(rendered.result.current.isSuccess).toBe(true))
+ expect(events.find(event => event.name === "request.finish")?.attributes).toMatchObject({ action_id: owner.id, request_reason: "foreground", outcome: "success" })
+ finishAction(owner, "success", { phase: "primary", region: "messages" })
+ events.length = 0
+ await act(async () => { await rendered.result.current.refetch() })
+ expect(events.find(event => event.name === "request.finish")?.attributes).toMatchObject({ action_id: owner.id, request_reason: "background", outcome: "success" })
+ const owned = exporter.getFinishedSpans().filter(span => span.name === "GET messages")
+ expect(owned).toHaveLength(2)
+ expect(owned.every(span => span.parentSpanContext?.spanId === owner.span!.spanContext().spanId)).toBe(true)
+ window.history.replaceState(null, "", "/c/me/bots")
+ const next = beginNavigation("/c/me/bots")!
+ commitNavigation("/c/me/bots")
+ finishAction(next, "success", { phase: "primary", region: "bots" })
+ events.length = 0
+ await act(async () => { await rendered.result.current.refetch() })
+ const request = events.find(event => event.name === "request.finish")!
+ expect(request.attributes).toMatchObject({ request_reason: "unknown", outcome: "success" })
+ expect(request.attributes).not.toHaveProperty("action_id")
+ expect(request.attributes).not.toHaveProperty("navigation_id")
+ const unowned = exporter.getFinishedSpans().filter(span => span.name === "GET messages").at(-1)!
+ expect(unowned.parentSpanContext).toBeUndefined()
+ expect(unowned.spanContext().traceId).not.toBe(owner.span!.spanContext().traceId)
+ expect(unowned.spanContext().traceId).not.toBe(next.span!.spanContext().traceId)
+ expect(request.attributes.trace_id).toBe(unowned.spanContext().traceId)
+})
diff --git a/src/web/src/hooks/community/use-messages.ts b/src/web/src/hooks/community/use-messages.ts
index 2b2c8c8db..f7147e5de 100644
--- a/src/web/src/hooks/community/use-messages.ts
+++ b/src/web/src/hooks/community/use-messages.ts
@@ -17,6 +17,10 @@ import {
type QueryClient,
} from "@tanstack/react-query"
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react"
+import type { ApiRequestOptions } from "@/lib/api/client"
+import { actionAttributes, navigationForHref, currentPageObservation } from "@/lib/observability/context"
+import { emitTelemetry, telemetryGeneration } from "@/lib/observability/telemetry"
+import { channelHref } from "@/lib/community/community-route"
import { apiFetchCommunity } from "@/lib/community/account-cache-lifecycle"
import { captureChannelMetadataToken, isChannelMetadataTokenCurrent } from "@/hooks/community/channel-metadata"
import { communityKeys } from "@/lib/query-keys"
@@ -109,6 +113,7 @@ type MessagesTransportPage = WireMessagesPage & {
type MessagesTransportOptions = {
onSurfaceReceipt?: (receipt: CommunityMessageSurfaceReceipt) => void
queryClient?: QueryClient
+ observation?: ApiRequestOptions["observation"] | (() => ApiRequestOptions["observation"])
}
function isMessageSurfaceReceipt(value: unknown): value is CommunityMessageSurfaceReceipt {
@@ -154,7 +159,7 @@ async function fetchMessagesTransport(
): Promise<WireMessagesPage> {
const transport = await withConversationReadDeadline(signal, (readSignal) => apiFetchCommunity<MessagesTransportPage>(
url,
- { signal: readSignal }, token,
+ { signal: readSignal, observation: typeof options?.observation === "function" ? options.observation() : options?.observation }, token,
))
const { surfaceReceipt, ...page } = transport
if (isMessageSurfaceReceipt(surfaceReceipt)) {
@@ -176,19 +181,26 @@ export const channelMessagesQueryFn =
}): Promise<MessagesPage> => {
const originalClient = options?.queryClient ?? client
if (!originalClient) throw new DOMException("Missing message query owner", "AbortError")
+ const captured = typeof options?.observation === "function" ? options.observation() : options?.observation
+ const observation: ApiRequestOptions["observation"] = pageParam.mode === "older" || pageParam.mode === "newer"
+ ? { page: captured?.page ?? captured?.action, reason: "pagination" }
+ : pageParam.mode === "since" ? { page: captured?.page ?? captured?.action, reason: "background" }
+ : captured?.action?.done ? { page: captured.action.name === "navigation" ? captured.action : captured.page, reason: "background" } : captured
+ const generation = telemetryGeneration()
const publicationToken = captureCommunityLiveSnapshotToken(originalClient, channelId)
const url = buildMessagesUrl(
`/api/community/channels/${channelId}/messages`,
pageParam,
tag,
)
- const page = await fetchMessagesTransport(originalClient, url, signal, options, publicationToken)
+ const page = await fetchMessagesTransport(originalClient, url, signal, { ...options, observation }, publicationToken)
{
- publishCommunityMessages(originalClient, {
+ const result = publishCommunityMessages(originalClient, {
channelId,
messages: page.messages,
proof: { token: publicationToken, signal },
})
+ if (result === "published" && generation === telemetryGeneration()) emitTelemetry("data.publish", { ...actionAttributes(observation?.action ?? observation?.page), source: "network", cache_stage: "canonical", request_reason: observation?.reason ?? "unknown", eligibility: "eligible", outcome: "success" })
}
return messageWindowPage(page)
}
@@ -942,9 +954,15 @@ function useMessageSurface(channelId: string | null, opts: MessagesOpts | Channe
return tag ? [...baseKey, "tag", tag] as const : baseKey
}, [channelId, kind, tag])
const queryFn = useMemo(() => {
- const options = { queryClient, onSurfaceReceipt: (receipt: CommunityMessageSurfaceReceipt) => recordConversationNavigationReceipt(queryClient, receipt, accessEpoch) }
+ const options = { queryClient, observation: (): ApiRequestOptions["observation"] => {
+ if (!channelId || typeof window === "undefined") return
+ const expected = serverId === null ? `/c/me/${channelId}` : channelHref(serverId, channelId)
+ if (window.location.pathname !== expected) return { page: undefined, reason: "unknown" }
+ const action = navigationForHref(window.location.pathname + window.location.search)
+ return action ? { action, reason: "foreground" } : { page: currentPageObservation(), reason: "background" }
+ }, onSurfaceReceipt: (receipt: CommunityMessageSurfaceReceipt) => recordConversationNavigationReceipt(queryClient, receipt, accessEpoch) }
return kind === "dm" ? dmMessagesQueryFn(channelId ?? "__none__", options) : channelMessagesQueryFn(channelId ?? "__none__", tag, options)
- }, [accessEpoch, channelId, kind, queryClient, tag])
+ }, [accessEpoch, channelId, kind, queryClient, serverId, tag])
const scope = useMemo<MessageScope>(() => serverId === null ? { kind: "dm", id: channelId ?? "__none__" } : { kind: "channel", id: channelId ?? "__none__", serverId }, [channelId, serverId])
const state = useMessageOverlayIds(scope)
const base = useMessagesInner(channelId, queryKey, queryFn, opts, state.liveIds)
diff --git a/src/web/src/lib/community/account-cache-lifecycle.ts b/src/web/src/lib/community/account-cache-lifecycle.ts
index 6a2605f65..515c3be26 100644
--- a/src/web/src/lib/community/account-cache-lifecycle.ts
+++ b/src/web/src/lib/community/account-cache-lifecycle.ts
@@ -1,4 +1,4 @@
-import { commandObservation } from "@/lib/observability/context"
+import { commandObservation, currentPageObservation } from "@/lib/observability/context"
import { clearComposerAttachmentSessionsForAccount } from "./composer-attachment-session"
import { apiFetch, type ApiRequestOptions } from "@/lib/api/client"
import { getCommunityDbRegistry, type CommunityDbRegistry } from "@/lib/community-db/collections"
@@ -52,8 +52,9 @@ export function apiFetchCommunity<T>(
options: ApiRequestOptions | undefined,
token: CommunityLiveSnapshotToken,
): Promise<T> {
+ const observation = options?.observation ?? commandObservation(token) ?? { page: currentPageObservation(), reason: "unknown" }
return loadCommunityRequest((origin) => apiFetch<T>(path, {
- ...options, ...origin, signal: options?.signal,
+ ...options, ...origin, observation, signal: options?.signal,
assertActive: () => { origin.assertActive?.(); options?.assertActive?.() },
}), token, options?.signal ?? undefined)
}
diff --git a/src/web/src/lib/community/conversation-navigation-warmup-owner.dom.test.tsx b/src/web/src/lib/community/conversation-navigation-warmup-owner.dom.test.tsx
index a20c8745e..819b79786 100644
--- a/src/web/src/lib/community/conversation-navigation-warmup-owner.dom.test.tsx
+++ b/src/web/src/lib/community/conversation-navigation-warmup-owner.dom.test.tsx
@@ -15,6 +15,8 @@ import { channelMetadataOptions, isChannelMetadataTokenCurrent } from "@/hooks/c
import { startChannelRouteVerification } from "@/hooks/community/channel-route-verification"
import { useChannelMetadata } from "@/hooks/community/use-channel-metadata"
import { retireCommunityChannelReading } from "@/lib/community-db/sync"
+import { beginNavigation, clearActions, finishAction } from "@/lib/observability/context"
+import { configureTelemetry, installTelemetrySink, retireTelemetry } from "@/lib/observability/telemetry"
vi.mock("@/lib/api/client", async (load) => {
const actual = await load<typeof import("@/lib/api/client")>()
@@ -48,6 +50,7 @@ beforeEach(() => {
})
afterEach(async () => {
await act(async () => {
+ retireTelemetry(); clearActions()
for (const owner of owners.splice(0)) { await owner.cleanup(); owner.queryClient.clear() }
if (anyDescriptor) Object.defineProperty(AbortSignal, "any", anyDescriptor)
else Reflect.deleteProperty(AbortSignal, "any")
@@ -71,6 +74,28 @@ function response(status: number) {
}
describe("warmup original owner and complete intent resources", () => {
+ it("retains the real navigation across original registry readiness and common API merge, then separates pagination and refresh", async () => {
+ const owner = createClient()
+ configureTelemetry({ session_id: "chain-session" }, true)
+ const events: Array<{ name: string; attributes: Record<string, string> }> = []
+ installTelemetrySink(event => events.push(event))
+ const action = beginNavigation(target.href)!
+ const epoch = startConversationNavigationWarmup(owner.client, target, 0, 0, action)
+ await waitFor(() => expect(vi.mocked(apiFetch).mock.calls.some(([path]) => path.includes("/messages"))).toBe(true))
+ const message = vi.mocked(apiFetch).mock.calls.find(([path]) => path.includes("/messages"))!
+ expect(message[1]?.observation).toEqual({ action, reason: "foreground" })
+ await waitFor(() => expect(getConversationNavigationProof(owner.client)).toMatchObject({ epoch, status: "proven" }))
+ expect(events.find(e => e.name === "data.publish")?.attributes).toMatchObject({ action_id: action.id, request_reason: "foreground", source: "network", cache_stage: "canonical" })
+ vi.mocked(apiFetch).mockClear()
+ const read = dmMessagesQueryFn("d1", { queryClient: owner.client, observation: { action, reason: "foreground" } })
+ await read({ pageParam: { mode: "older", cursor: "old" } })
+ expect(vi.mocked(apiFetch).mock.calls[0]?.[1]?.observation).toEqual({ page: action, reason: "pagination" })
+ finishAction(action, "success")
+ vi.mocked(apiFetch).mockClear()
+ await read({ pageParam: { mode: "newest" } })
+ expect(vi.mocked(apiFetch).mock.calls[0]?.[1]?.observation).toEqual({ page: action, reason: "background" })
+ })
+
it.each(["dm", "thread"] as const)("qualifies a revoked %s before warmup capture and keeps that request through prior-body unmount", async (kind) => {
const owner = createClient()
await owner.registry.preload()
diff --git a/src/web/src/lib/community/conversation-navigation-warmup.ts b/src/web/src/lib/community/conversation-navigation-warmup.ts
index 49b289eab..a2b56aecd 100644
--- a/src/web/src/lib/community/conversation-navigation-warmup.ts
+++ b/src/web/src/lib/community/conversation-navigation-warmup.ts
@@ -1,4 +1,5 @@
"use client"
+import type { Action } from "@/lib/observability/context"
import { getCommunityRuntime } from "@/stores/community/runtime"
@@ -40,6 +41,7 @@ export function startConversationNavigationWarmup(
target: ConversationNavigationTarget,
accessEpoch: number,
recoveryAttempt = 0,
+ action?: Action,
) {
if (getCommunityRuntime(queryClient).ws.actions.isChannelAccessRevoked(target.channelId, target.serverId ?? null)) {
void startChannelRouteVerification(queryClient, target.serverId ?? null, target.channelId).catch(() => undefined)
@@ -60,12 +62,14 @@ export function startConversationNavigationWarmup(
const queryFn = target.scopeKind === "dm"
? dmMessagesQueryFn(target.channelId, {
queryClient,
+ observation: { action: recoveryAttempt === 0 ? action : undefined, reason: recoveryAttempt === 0 ? "foreground" : "background" },
onSurfaceReceipt: (receipt) => {
recordConversationNavigationReceipt(queryClient, receipt, accessEpoch, epoch)
},
})
: channelMessagesQueryFn(target.channelId, null, {
queryClient,
+ observation: { action: recoveryAttempt === 0 ? action : undefined, reason: recoveryAttempt === 0 ? "foreground" : "background" },
onSurfaceReceipt: (receipt) => {
recordConversationNavigationReceipt(queryClient, receipt, accessEpoch, epoch)
},
diff --git a/src/web/src/lib/observability/client.ts b/src/web/src/lib/observability/client.ts
index ce77650bc..d528e3301 100644
--- a/src/web/src/lib/observability/client.ts
+++ b/src/web/src/lib/observability/client.ts
@@ -3,15 +3,18 @@ import type { getDefaultOTELInstrumentations } from "@grafana/faro-web-tracing"
import { isMobile, isTauri } from "@alook/shared"
import { ANALYTICS_CONSENT_CHANGE_EVENT, hasAnalyticsConsent } from "../analytics-consent"
import { capabilityLimits, routeTemplate } from "./coverage"
-import { actionSequence, beginNavigation, clearActions, installActionSpans, telemetryId } from "./context"
+import { ROOT_CONTEXT } from "@opentelemetry/api"
+import { actionSequence, beginNavigation, clearActions, installActionSpans, telemetryId, currentPageObservation, actionAttributes, startPageOperation, finishPageOperation } from "./context"
import { alignInitialTelemetrySession, configureTelemetry, emitTelemetry, installTelemetrySink, isTelemetryEligible, telemetryGeneration, reportTelemetryDrops, retireTelemetry } from "./telemetry"
+import { cleanAttributes } from "./schema"
import { sanitizeItem } from "./sanitize"
import { installLongTaskObserver } from "./browser"
import { resolveCommunityModulePlan } from "../community/community-route"
import { observeTransportSpan, finishTransportSpan, installNavigationFetchContext } from "./requests"
import { resolveFrontendIdentity } from "./runtime"
import { resolveObservationBuild } from "./build"
-import { observationEpoch, finishTransportClock } from "./clock"
+import { finishTransportClock } from "./clock"
+import { observeResourceResponse } from "./resource"
type BuildProfile = { url?: string; environment?: string; release?: string; release_status: string; environment_status: string }
function validBuildProfile(profile: BuildProfile) {
@@ -92,7 +95,7 @@ async function activate() {
let storedScope: string | undefined
try { storedScope = VolatileSessionsManager.fetchUserSession()?.sessionMeta?.attributes?.alook_account } catch { clearNativeSession() }
if (!mayResume || storedScope !== accountScope) clearNativeSession()
- httpInstrumentations = createHttp({ fetchInstrumentationOptions: { requestHook: observeTransportSpan, applyCustomAttributesOnSpan: (span, _request, result) => finishTransportSpan(span, result) }, xhrInstrumentationOptions: { applyCustomAttributesOnSpan: finishTransportClock }, ignoreUrls: [build.url!], propagateTraceHeaderCorsUrls: [new RegExp("^" + window.location.origin.replace(/[.*+?^$(){}|[\]\\]/g, "\\$&") + "/")] })
+ httpInstrumentations = createHttp({ fetchInstrumentationOptions: { ignoreNetworkEvents: false, requestHook: observeTransportSpan, applyCustomAttributesOnSpan: (span, _request, result) => finishTransportSpan(span, result) }, xhrInstrumentationOptions: { ignoreNetworkEvents: false, applyCustomAttributesOnSpan: (span, xhr) => { finishTransportClock(span); observeResourceResponse(span, xhr.getResponseHeader("server-timing") ?? "") } }, ignoreUrls: [build.url!], propagateTraceHeaderCorsUrls: [new RegExp("^" + window.location.origin.replace(/[.*+?^$(){}|[\]\\]/g, "\\$&") + "/")] })
const defaults = getWebInstrumentations({ captureConsole: false, enableContentSecurityPolicyInstrumentation: false, enablePerformanceInstrumentation: true })
const initialTransport = transport
faro = initializeFaro({
@@ -109,7 +112,7 @@ async function activate() {
ignoreUrls: [build.url!],
webVitalsInstrumentation: { trackAttributionSources: false },
batching: { enabled: true, itemLimit: 40, sendTimeout: 1000 },
- beforeSend: item => hasAnalyticsConsent() && isTelemetryEligible() ? sanitizeItem(item, sessionId, window.location.origin, identity, eligibleTimestamp, documentVitalsEligible, observationEpoch(eligibleSince)) : null,
+ beforeSend: item => hasAnalyticsConsent() && isTelemetryEligible() ? sanitizeItem(item, sessionId, window.location.origin, identity, eligibleTimestamp, documentVitalsEligible, eligibleTimestamp, eligibleSince) : null,
})
const initialized = faro?.api.getSession()
if (!faro || !initialized?.id || !/^[a-zA-Z0-9_-]{1,80}$/.test(initialized.id) || initialized.attributes?.alook_account !== accountScope) { deactivate(); return }
@@ -131,9 +134,10 @@ async function activate() {
faro.api.setSession({ id: capturedSession, attributes: { isSampled: "true", alook_account: userKey ?? "anon" } })
}
if (!faro) { deactivate(); return }
- installActionSpans((name, attributes, startTime, links) => {
+ installActionSpans((name, attributes, startTime, links, parent) => {
if (!isTelemetryEligible()) return
- return faro?.api.getOTEL()?.trace.getTracer("alook.frontend").startSpan(name, { attributes, startTime, links })
+ const otel = faro?.api.getOTEL()
+ return otel?.trace.getTracer("alook.frontend").startSpan(name, { attributes, startTime, links }, parent ? otel.trace.setSpan(otel.context.active(), parent) : ROOT_CONTEXT)
})
connectSink()
stopNavigationFetch = installNavigationFetchContext()
@@ -225,10 +229,12 @@ export function bootstrapObservability(nextSurface: "web" | "blog") {
if (!control) return
if (control instanceof HTMLAnchorElement && control.href && control.origin === window.location.origin && !control.download && control.target !== "_blank" && !(event instanceof MouseEvent && (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey)) && routeTemplate(control.href, window.location.origin) !== "/unmapped") beginNavigation(control.href, "gesture")
else {
- const before = actionSequence(), generation = telemetryGeneration()
+ const before = actionSequence(), generation = telemetryGeneration(), owner = currentPageObservation(), interactionStart = performance.now()
queueMicrotask(() => {
if (!isTelemetryEligible() || generation !== telemetryGeneration() || actionSequence() !== before) return
- try { if (!faro?.api.getActiveUserAction()) faro?.api.startUserAction("ui_interaction", { session_id: sessionId }) } catch {}
+ const operation = startPageOperation("ui.interaction", { phase: "interaction" }, owner, interactionStart)
+ finishPageOperation(operation, "observed")
+ try { if (!faro?.api.getActiveUserAction()) faro?.api.startUserAction("ui_interaction", cleanAttributes({ ...actionAttributes(owner), session_id: sessionId })) } catch {}
})
}
}, { capture: true, passive: true })
diff --git a/src/web/src/lib/observability/clock-tracing.dom.test.ts b/src/web/src/lib/observability/clock-tracing.dom.test.ts
index ed9c74621..5f5267496 100644
--- a/src/web/src/lib/observability/clock-tracing.dom.test.ts
+++ b/src/web/src/lib/observability/clock-tracing.dom.test.ts
@@ -69,28 +69,28 @@ it("normalizes real native HTTP exports and mirrors, retaining missing-hook and
const flush = async () => { await vi.advanceTimersByTimeAsync(0); now += 4000; await vi.advanceTimersByTimeAsync(3000) }
const path = "/api/agents"
for (const next of ["success", "body", "error", "abort", "http-error"]) {
- mode = next; const start = now
+ mode = next; const wallStart = Date.now()
if (next === "error" || next === "abort") await expect(window.fetch(path)).rejects.toThrow()
else await window.fetch(path)
await flush()
const { spans, events } = exported(), span = spans.filter(s => s.name === "GET /api/agents").at(-1)!
- expect(Number(span.startTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(start, 2)
- expect(Number(span.endTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(start + 12, 2)
+ expect(Number(span.startTimeUnixNano) / 1e6).toBeCloseTo(wallStart, 2)
+ expect(Number(span.endTimeUnixNano) / 1e6).toBeCloseTo(wallStart + 12, 2)
const mirror = events.find(e => e.trace?.span_id === span.spanId)!
expect(mirror.name).toBe("faro.tracing.fetch")
expect(Number(mirror.attributes.duration_ms)).toBeCloseTo(12, 2)
if (next === "http-error") expect(span.status).toEqual({ code: 2 })
}
for (const event of ["load", "error", "abort", "timeout"]) {
- const start = now, xhr = new XMLHttpRequest()
+ const wallStart = Date.now(), xhr = new XMLHttpRequest()
xhr.open("GET", "/api/workspaces"); xhr.send()
now += 17; drift *= -1; vi.setSystemTime(performance.timeOrigin + now + drift)
Object.defineProperty(xhr, "status", { value: event === "load" ? 200 : 0 })
xhr.dispatchEvent(new Event(event))
await flush()
const { spans, events } = exported(), span = spans.filter(s => s.name === "GET /api/workspaces").at(-1)!
- expect(Number(span.startTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(start, 2)
- expect(Number(span.endTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(start + 17, 2)
+ expect(Number(span.startTimeUnixNano) / 1e6).toBeCloseTo(wallStart, 2)
+ expect(Number(span.endTimeUnixNano) / 1e6).toBeCloseTo(wallStart + 17, 2)
const mirror = events.find(e => e.trace?.span_id === span.spanId)!
expect(mirror.name).toBe("faro.tracing.xml-http-request")
expect(Number(mirror.attributes.duration_ms)).toBeCloseTo(17, 2)
@@ -119,9 +119,9 @@ it("normalizes real native HTTP exports and mirrors, retaining missing-hook and
expect(exported().spans.some(s => s.name === "GET /api/community/channels/[id]/messages")).toBe(false)
expect(exported().events.some(e => e.attributes.route_template === "/api/community/channels/[id]/messages")).toBe(false)
}
- mode = "success"; const resumedStart = now
+ mode = "success"; const resumedStart = Date.now()
await window.fetch(path); await flush()
- expect(Number(exported().spans.filter(s => s.name === "GET /api/agents").at(-1)!.startTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(resumedStart, 2)
+ expect(Number(exported().spans.filter(s => s.name === "GET /api/agents").at(-1)!.startTimeUnixNano) / 1e6).toBeCloseTo(resumedStart, 2)
expect(JSON.stringify(sent)).not.toContain("alook.internal.http")
})
@@ -130,9 +130,11 @@ it("preserves public identity, links and explicit manual/preflight timing withou
const { SpanKind, SpanStatusCode, ROOT_CONTEXT, trace } = await import("@opentelemetry/api")
const { WebTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } = await import("@opentelemetry/sdk-trace-web")
const { ObservationClockProcessor } = await import("./clock-tracing")
- const { observationTime, finishTransportClock, transportClockStart, transportClockEnd } = await import("./clock")
+ const { observationTime: toTime, observationOrigin, finishTransportClock, transportClockStart, transportClockEnd } = await import("./clock")
let now = 400
+ vi.spyOn(Date, "now").mockReturnValue(Date.now())
vi.spyOn(performance, "now").mockImplementation(() => now)
+ const origin = observationOrigin(), observationTime = (value: number) => toTime(value, origin)
const exporter = new InMemorySpanExporter(), processor = new ObservationClockProcessor(new SimpleSpanProcessor(exporter))
const provider = new WebTracerProvider({ spanProcessors: [processor] })
const manual = provider.getTracer("alook.frontend").startSpan("navigation", { startTime: observationTime(300) })
diff --git a/src/web/src/lib/observability/clock-tracing.ts b/src/web/src/lib/observability/clock-tracing.ts
index fffca6941..57f98df08 100644
--- a/src/web/src/lib/observability/clock-tracing.ts
+++ b/src/web/src/lib/observability/clock-tracing.ts
@@ -1,7 +1,9 @@
import { SpanKind, type Context, type HrTime } from "@opentelemetry/api"
import { BatchSpanProcessor, type ReadableSpan, type Span, type SpanProcessor } from "@opentelemetry/sdk-trace-web"
import { FaroMetaAttributesSpanProcessor, FaroTraceExporter, TracingInstrumentation, type TracingInstrumentationOptions } from "@grafana/faro-web-tracing"
-import { observationTime, transportClockStart, transportClockEnd } from "./clock"
+import { observationTime, observationOrigin, transportClockStart, transportClockEnd, transportClockOrigin, observationOwnerGeneration, retireObservationSpan } from "./clock"
+import { telemetryGeneration } from "./telemetry"
+import { projectResource } from "./resource"
function nativeHttp(span: ReadableSpan) {
return span.kind === SpanKind.CLIENT && ["@opentelemetry/instrumentation-fetch", "@opentelemetry/instrumentation-xml-http-request"].includes(span.instrumentationScope.name)
@@ -11,24 +13,32 @@ export class ObservationClockProcessor implements SpanProcessor {
constructor(private readonly next: SpanProcessor) {}
onStart(span: Span, parentContext: Context) {
- if (nativeHttp(span)) span.setAttribute(transportClockStart, performance.now())
+ if (nativeHttp(span)) {
+ const owner = parentContext.getValue(observationOwnerGeneration)
+ if (typeof owner === "number" && owner !== telemetryGeneration()) retireObservationSpan(span)
+ const now = performance.now()
+ span.setAttribute(transportClockStart, now)
+ span.setAttribute(transportClockOrigin, observationOrigin(now))
+ }
this.next.onStart(span, parentContext)
}
onEnd(span: ReadableSpan) {
- const start = span.attributes[transportClockStart], end = span.attributes[transportClockEnd]
+ const start = span.attributes[transportClockStart], end = span.attributes[transportClockEnd], origin = span.attributes[transportClockOrigin]
if (!nativeHttp(span) || typeof start !== "number" || typeof end !== "number" || !Number.isFinite(start) || !Number.isFinite(end) || start < 0 || end < start) {
this.next.onEnd(span)
return
}
- const startTime = observationTime(start), endTime = observationTime(end)
+ if (typeof origin !== "number" || !Number.isFinite(origin)) { this.next.onEnd(span); return }
+ const startTime = observationTime(start, origin), endTime = observationTime(end, origin)
+ const resource = projectResource(span, origin)
const duration: HrTime = [endTime[0] - startTime[0], endTime[1] - startTime[1]]
if (duration[1] < 0) { duration[0]--; duration[1] += 1e9 }
const projected: ReadableSpan = {
name: span.name, kind: span.kind, spanContext: () => span.spanContext(), parentSpanContext: span.parentSpanContext,
- startTime, endTime, duration, status: span.status, attributes: span.attributes, links: span.links, events: span.events,
+ startTime, endTime, duration, status: span.status, attributes: { ...resource.attributes, clock_source: "operation_monotonic", clock_domain: "browser", clock_alignment: "unverified", clock_skew_ms: Math.abs(observationOrigin() - origin) }, links: span.links, events: resource.events,
ended: span.ended, resource: span.resource, instrumentationScope: span.instrumentationScope,
- droppedAttributesCount: span.droppedAttributesCount, droppedEventsCount: span.droppedEventsCount, droppedLinksCount: span.droppedLinksCount,
+ droppedAttributesCount: span.droppedAttributesCount, droppedEventsCount: span.droppedEventsCount + resource.discarded, droppedLinksCount: span.droppedLinksCount,
}
this.next.onEnd(projected)
}
diff --git a/src/web/src/lib/observability/clock.ts b/src/web/src/lib/observability/clock.ts
index 721d69d64..b4b8e51f7 100644
--- a/src/web/src/lib/observability/clock.ts
+++ b/src/web/src/lib/observability/clock.ts
@@ -1,18 +1,27 @@
-import type { HrTime, Span } from "@opentelemetry/api"
+import { createContextKey, type HrTime, type Span } from "@opentelemetry/api"
+
+export const observationOwnerGeneration = createContextKey("alook.observation.owner.generation")
+export const retiredObservationSpan = "alook.internal.owner.retired"
+export function retireObservationSpan(span?: Span) { try { span?.setAttribute(retiredObservationSpan, true) } catch {} }
export const transportClockStart = "alook.internal.http.start_ms"
export const transportClockEnd = "alook.internal.http.end_ms"
+export const transportClockOrigin = "alook.internal.http.origin_ms"
export function finishTransportClock(span: Span) {
span.setAttribute(transportClockEnd, performance.now())
}
-export function observationEpoch(now = performance.now()) {
- return performance.timeOrigin + now
+export function observationOrigin(now = performance.now()) {
+ return Date.now() - now
+}
+
+export function observationEpoch(now = performance.now(), origin = observationOrigin()) {
+ return origin + now
}
-export function observationTime(now: number): HrTime {
- const epoch = observationEpoch(now)
+export function observationTime(now: number, origin = observationOrigin()): HrTime {
+ const epoch = observationEpoch(now, origin)
const seconds = Math.floor(epoch / 1000)
return [seconds, Math.floor((epoch - seconds * 1000) * 1e6)]
}
diff --git a/src/web/src/lib/observability/context.test.ts b/src/web/src/lib/observability/context.test.ts
index 75f29a680..3749ab2f2 100644
--- a/src/web/src/lib/observability/context.test.ts
+++ b/src/web/src/lib/observability/context.test.ts
@@ -49,7 +49,7 @@ describe("original observation ownership", () => {
expect(Object.values(dmFields)).not.toContain("undefined")
expect(navigationFields.navigation_id).toBe(navigation.navigationId)
finishAction(dm, undefined)
- expect(dm.span!.setAttribute).not.toHaveBeenCalled()
+ expect(dm.span!.setAttribute).not.toHaveBeenCalledWith("outcome", expect.anything())
finishAction(navigation, "success")
expect(navigation.span!.setAttribute).toHaveBeenCalledWith("outcome", "success")
})
@@ -95,7 +95,7 @@ describe("original observation ownership", () => {
vi.setSystemTime(Date.now() - 86_400_000)
finishAction(action, "success", { phase: "primary", region: "bots" })
expect(events.at(-1)?.attributes.duration_ms).toBe("50")
- expect(end).toHaveBeenCalledWith(observationTime(150))
+ expect(end).toHaveBeenCalledWith(observationTime(150, action.origin))
const emitted: Array<{ timestamp: number }> = []
installTelemetrySink(event => emitted.push(event))
emitTelemetry("business.result", { outcome: "success" })
diff --git a/src/web/src/lib/observability/context.ts b/src/web/src/lib/observability/context.ts
index 7d8355b24..3ab53794e 100644
--- a/src/web/src/lib/observability/context.ts
+++ b/src/web/src/lib/observability/context.ts
@@ -1,17 +1,20 @@
-import { isSpanContextValid, type Span, type HrTime, type Link } from "@opentelemetry/api"
-import { observationTime } from "./clock"
+import { isSpanContextValid, type Span, type HrTime, type Link, context, trace } from "@opentelemetry/api"
+import { recordDocumentTiming } from "./document-timing"
+import { observationTime, observationOrigin, observationOwnerGeneration, retireObservationSpan } from "./clock"
import { routeTemplate, actionNames } from "./coverage"
import { emitTelemetry, isTelemetryEligible, isNativeSessionContinuation, telemetryGeneration, notifyObservation, linkQueuedActionTrace } from "./telemetry"
import { cleanAttributes, type Attributes } from "./schema"
-export type Action = { id: string; navigationId?: string; navigationKind?: "document" | "route"; name: string; route: string; start: number; generation: number; done: boolean; end?: number; outcome?: Attributes["outcome"]; span?: Span; timer?: ReturnType<typeof setTimeout>; prefetch?: Action }
-let makeSpan: ((name: string, attributes: Record<string, string>, startTime: HrTime, links: Link[]) => Span | undefined) | undefined
+export type Action = { id: string; navigationId?: string; navigationKind?: "document" | "route"; name: string; route: string; start: number; origin: number; generation: number; done: boolean; end?: number; outcome?: Attributes["outcome"]; span?: Span; timer?: ReturnType<typeof setTimeout>; prefetch?: Action; parent?: Action; pageId?: string }
+let makeSpan: ((name: string, attributes: Record<string, string>, startTime: HrTime, links: Link[], parent?: Span) => Span | undefined) | undefined
const live = new Set<Action>()
-const deferred = new Set<Action>()
+const deferred = new Set<Action | PageOperation>()
let prefetch: Action | undefined
let prefetchHref: string | undefined
let navigation: Action | undefined
let navigationHref: string | undefined
+let page: Action | undefined
+let pageHref: string | undefined
let committedHref: string | undefined
let gesturePending = false
let sequence = 0
@@ -25,16 +28,23 @@ export function installActionSpans(factory: typeof makeSpan) {
for (const action of deferred) {
deferred.delete(action)
if (!isTelemetryEligible() || action.generation !== telemetryGeneration()) continue
+ if ("page" in action) {
+ action.span = pageOperationSpan(action)
+ if (action.done) endPageOperationSpan(action)
+ continue
+ }
let span: Span | undefined
- try { span = factory(action.name, cleanAttributes(actionAttributes(action)), observationTime(action.start), actionLinks(action)) } catch {}
- if (!isTelemetryEligible() || action.generation !== telemetryGeneration()) { try { span?.end() } catch {}; continue }
+ try { span = action.parent && !action.parent.span ? undefined : factory(action.name, cleanAttributes(actionAttributes(action)), observationTime(action.start, action.origin), actionLinks(action), action.parent?.span) } catch {}
+ if (!isTelemetryEligible() || action.generation !== telemetryGeneration()) { retireObservationSpan(span); try { span?.end() } catch {}; continue }
action.span = span
+ if (span) action.parent = undefined
const attributes = actionAttributes(action)
linkQueuedActionTrace(action.id, action.generation, attributes.trace_id, attributes.span_id)
if (action.done && action.end !== undefined) {
const outcome = cleanAttributes({ outcome: action.outcome }).outcome
if (outcome !== undefined) { try { span?.setAttribute("outcome", outcome) } catch {} }
- try { span?.end(observationTime(action.end)) } catch {}
+ if (action.navigationKind === "document") { try { recordDocumentTiming(span, action.origin, action.end) } catch {} }
+ try { span?.end(observationTime(action.end, action.origin)) } catch {}
}
}
}
@@ -42,18 +52,21 @@ export function installActionSpans(factory: typeof makeSpan) {
export function startAction(name: string, attributes: Attributes = {}, start = performance.now(), sourcePrefetch?: Action): Action | undefined {
if (!isTelemetryEligible() || !names.has(name)) return
if (live.size >= 64) finishAction(live.values().next().value, "cancelled")
- const action: Action = { id: telemetryId(), name, route: String(attributes.route_template ?? currentRoute()), start, generation: telemetryGeneration(), done: false, prefetch: sourcePrefetch }
+ const parent = name === "navigation" ? undefined : currentPageObservation()
+ const action: Action = { id: telemetryId(), name, route: String(attributes.route_template ?? currentRoute()), start, origin: parent?.origin ?? observationOrigin(), generation: telemetryGeneration(), done: false, prefetch: sourcePrefetch, parent, pageId: parent?.navigationId }
if (name === "navigation") { action.navigationId = telemetryId(); action.navigationKind = attributes.navigation_kind === "document" ? "document" : "route" }
const fields = actionAttributes(action)
- try { action.span = makeSpan?.(name, cleanAttributes(fields), observationTime(action.start), actionLinks(action)) } catch {}
- if (!isTelemetryEligible() || (action.generation !== telemetryGeneration() && !isNativeSessionContinuation(action.generation))) {
+ try { action.span = parent && !parent.span ? undefined : makeSpan?.(name, cleanAttributes(fields), observationTime(action.start, action.origin), actionLinks(action), parent?.span)
+ if (action.span) action.parent = undefined } catch {}
+ if (!isTelemetryEligible() || (action.generation !== telemetryGeneration() && !isNativeSessionContinuation(action.generation)) || (parent && parent.generation !== telemetryGeneration())) {
+ retireObservationSpan(action.span)
try { action.span?.end() } catch {}
return
}
action.generation = telemetryGeneration()
sequence++
live.add(action)
- if ((action.navigationId || name === "navigation.prefetch") && !action.span) {
+ if (!action.span) {
if (deferred.size >= 64) deferred.delete(deferred.values().next().value!)
deferred.add(action)
}
@@ -69,7 +82,7 @@ function actionLinks(action: Action): Link[] {
export function actionAttributes(action?: Action): Attributes {
let span
try { span = action?.span?.spanContext() } catch {}
- return action ? { trace_id: span?.traceId, span_id: span?.spanId, action_id: action.id, navigation_id: action.navigationId, navigation_kind: action.navigationKind, prefetch_action_id: action.prefetch?.id, action_name: action.name, route_template: action.route, start_ms: action.start } : {}
+ return action ? { trace_id: span?.traceId, span_id: span?.spanId, action_id: action.id, navigation_id: action.navigationId, page_id: action.pageId ?? action.navigationId, navigation_kind: action.navigationKind, prefetch_action_id: action.prefetch?.id, action_name: action.name, route_template: action.route, start_ms: action.start, observation_origin_ms: action.origin, clock_source: "operation_monotonic", clock_domain: "browser", clock_alignment: "unverified" } : {}
}
export function finishAction(action: Action | undefined, outcome: Attributes["outcome"], fields: Attributes = {}) {
if (!action || action.done) return
@@ -79,17 +92,30 @@ export function finishAction(action: Action | undefined, outcome: Attributes["ou
clearTimeout(action.timer)
live.delete(action)
if (action.generation === telemetryGeneration()) {
- const attributes = { ...actionAttributes(action), ...fields, outcome, duration_ms: action.end - action.start }
+ const attributes = { ...actionAttributes(action), ...fields, outcome, duration_ms: action.end - action.start, clock_skew_ms: Math.abs(observationOrigin() - action.origin) }
emitTelemetry("action.finish", attributes)
- if (action.navigationId && outcome === "success" && fields.phase === "primary") emitTelemetry("navigation.ready", attributes)
+ if (action.navigationId && outcome === "success" && fields.phase === "primary") {
+ if (action === navigation) { page = action; pageHref = navigationHref }
+ emitTelemetry("navigation.ready", attributes)
+ }
const safeOutcome = cleanAttributes({ outcome }).outcome
if (safeOutcome !== undefined) {
try { action.span?.setAttribute("outcome", safeOutcome) } catch {}
}
+ try { action.span?.setAttribute("clock_skew_ms", Math.abs(observationOrigin() - action.origin)) } catch {}
}
- try { action.span?.end(observationTime(action.end)) } catch {}
+ if (action.navigationKind === "document") { try { recordDocumentTiming(action.span, action.origin, action.end) } catch {} }
+ try { action.span?.end(observationTime(action.end, action.origin)) } catch {}
if (action === navigation) notifyObservation()
}
+export function startRegionObservation(action: Action | undefined, region: Attributes["region"]) {
+ if (!action || action.done) return
+ return startPageOperation("region.wait", { region, phase: "commit", source: "unknown" }, action)
+}
+export function finishRegionObservation(operation: PageOperation | undefined, action: Action | undefined, outcome: Attributes["outcome"]) {
+ if (!action || operation?.page !== action) return
+ finishPageOperation(operation, outcome)
+}
export function clearActions() {
for (const action of live) finishAction(action, "cancelled")
deferred.clear()
@@ -98,6 +124,8 @@ export function clearActions() {
navigation = undefined
navigationHref = undefined
gesturePending = false
+ page = undefined
+ pageHref = undefined
}
function normalizedHref(href: string) {
const origin = typeof window === "undefined" ? "https://alook.ai" : window.location.origin
@@ -129,6 +157,7 @@ export function beginNavigation(href: string, phase: "intent" | "transport" | "g
if (navigation?.prefetch) finishAction(navigation.prefetch, "observed")
if (!navigation) return
navigationHref = target
+ if (phase === "document") { page = navigation; pageHref = target }
gesturePending = phase === "gesture"
emitTelemetry("navigation.intent", { ...actionAttributes(navigation), phase: phase === "document" ? "hydrate" : phase === "gesture" ? "intent" : phase, request_reason: "router" })
notifyObservation()
@@ -136,9 +165,12 @@ export function beginNavigation(href: string, phase: "intent" | "transport" | "g
}
export function navigationNoop(href: string) { const action = beginNavigation(href); finishAction(action, "noop") }
export function commitNavigation(href: string, region: "shell" | "page" = "shell") {
+ const previous = committedHref
committedHref = normalizedHref(href)
if (!isTelemetryEligible()) return
- const matched = navigationHref === committedHref && navigation && !navigation.done ? navigation : undefined
+ const matched = navigationHref === committedHref && navigation?.generation === telemetryGeneration() ? navigation : undefined
+ if (matched) { page = matched; pageHref = committedHref }
+ else if (committedHref !== previous) { page = undefined; pageHref = undefined }
emitTelemetry("navigation.commit", { ...actionAttributes(matched), route_template: routeTemplate(href, typeof window === "undefined" ? "https://alook.ai" : window.location.origin), region, phase: "commit" })
notifyObservation()
}
@@ -146,6 +178,53 @@ export function committedNavigationPathname() { return committedHref?.split("?")
export function navigationForHref(href: string) {
return navigation && !navigation.done && navigationHref === normalizedHref(href) ? navigation : undefined
}
+export function currentPageObservation() {
+ if (!isTelemetryEligible() || typeof window === "undefined") return
+ return page?.generation === telemetryGeneration() && pageHref === normalizedHref(window.location.href) ? page : undefined
+}
+export type PageOperation = { page: Action; start: number; generation: number; name: "ws.connect" | "ws.event_applied" | "cache.restore" | "ui.interaction" | "region.wait"; fields: Attributes; span?: Span; done: boolean; end?: number; outcome?: Attributes["outcome"] }
+function pageOperationSpan(operation: PageOperation) {
+ if (!isTelemetryEligible() || operation.generation !== telemetryGeneration() || !operation.page.span) return
+ try {
+ const span = makeSpan?.(operation.name, cleanAttributes({ ...actionAttributes(operation.page), ...operation.fields, span_role: operation.name === "region.wait" ? "region_readiness" : "page_operation" }), observationTime(operation.start, operation.page.origin), [], operation.page.span)
+ if (!isTelemetryEligible() || operation.generation !== telemetryGeneration()) { retireObservationSpan(span); try { span?.end() } catch {}; return }
+ const id = span?.spanContext()
+ if (id) { span?.setAttribute("trace_id", id.traceId); span?.setAttribute("span_id", id.spanId) }
+ return span
+ } catch { return undefined }
+}
+export function startPageOperation(name: PageOperation["name"], fields: Attributes, owner: Action | undefined, start = performance.now()): PageOperation | undefined {
+ if (!owner || !isTelemetryEligible() || owner.generation !== telemetryGeneration()) return
+ const operation: PageOperation = { page: owner, start, generation: owner.generation, name, fields, done: false }
+ operation.span = pageOperationSpan(operation)
+ if (!operation.span) {
+ if (deferred.size >= 64) deferred.delete(deferred.values().next().value!)
+ deferred.add(operation)
+ }
+ return operation
+}
+export function pageOperationAttributes(operation?: PageOperation): Attributes {
+ if (!operation || operation.generation !== telemetryGeneration()) return {}
+ const native = operation.span?.spanContext()
+ return { ...actionAttributes(operation.page), ...operation.fields, trace_id: native?.traceId ?? operation.page.span?.spanContext().traceId, span_id: native?.spanId ?? operation.page.span?.spanContext().spanId, start_ms: operation.start, duration_ms: performance.now() - operation.start }
+}
+export function runPageOperation<T>(operation: PageOperation | undefined, execute: () => T): T {
+ const span = operation?.generation === telemetryGeneration() ? operation.span ?? operation.page.span : undefined
+ return span && isTelemetryEligible() ? context.with(trace.setSpan(context.active().setValue(observationOwnerGeneration, operation!.generation), span), execute) : execute()
+}
+export function finishPageOperation(operation: PageOperation | undefined, outcome: Attributes["outcome"]) {
+ if (!operation || operation.done) return
+ operation.done = true
+ operation.end = performance.now()
+ operation.outcome = outcome
+ operation.span ??= pageOperationSpan(operation)
+ endPageOperationSpan(operation)
+}
+function endPageOperationSpan(operation: PageOperation) {
+ if (!isTelemetryEligible() || operation.generation !== telemetryGeneration()) retireObservationSpan(operation.span)
+ try { operation.span?.setAttribute("outcome", String(operation.outcome)) } catch {}
+ try { operation.span?.end(observationTime(operation.end!, operation.page.origin)) } catch {}
+}
const commandActions = new WeakMap<object, Action>()
export function bindCommandAction(value: unknown, action: Action, depth = 0) {
if (!value || typeof value !== "object" || depth > 3) return
diff --git a/src/web/src/lib/observability/document-timing.test.ts b/src/web/src/lib/observability/document-timing.test.ts
new file mode 100644
index 000000000..444ce0e66
--- /dev/null
+++ b/src/web/src/lib/observability/document-timing.test.ts
@@ -0,0 +1,43 @@
+import { InMemorySpanExporter, SimpleSpanProcessor, WebTracerProvider } from "@opentelemetry/sdk-trace-web"
+import { afterEach, expect, it, vi } from "vitest"
+import { recordDocumentTiming } from "./document-timing"
+
+afterEach(() => vi.restoreAllMocks())
+
+it.each(["selected", "not_selected"])("links the exact document server identity while retaining its %s sampling state", async sampling => {
+ const server = { traceId: "a".repeat(32), spanId: "b".repeat(16), traceFlags: sampling === "selected" ? 1 : 0 }
+ vi.spyOn(performance, "getEntriesByType").mockReturnValue([{
+ responseEnd: 18,
+ serverTiming: [
+ { name: "alook_server", description: `00-${server.traceId}-${server.spanId}-0${server.traceFlags}` },
+ { name: "alook_sampling", description: sampling },
+ ],
+ } as unknown as PerformanceEntry])
+ const exporter = new InMemorySpanExporter()
+ const provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ const span = provider.getTracer("alook.frontend").startSpan("navigation")
+ recordDocumentTiming(span, 100_000, 50)
+ span.end()
+ const recorded = exporter.getFinishedSpans()[0]!
+ expect(recorded.attributes).toMatchObject({ server_identity: "available", server_sampling: sampling, server_trace_id: server.traceId, server_span_id: server.spanId })
+ expect(recorded.links).toEqual([{ context: server, attributes: { relationship: "document_response" } }])
+ expect(recorded.parentSpanContext).toBeUndefined()
+ await provider.shutdown()
+})
+
+it.each(["invalid", "duplicate"])("does not create a server link from %s document identity", async kind => {
+ const identity = { name: "alook_server", description: `00-${"a".repeat(32)}-${"b".repeat(16)}-01` }
+ vi.spyOn(performance, "getEntriesByType").mockReturnValue([{
+ serverTiming: kind === "duplicate" ? [identity, identity] : [{ ...identity, description: "invalid" }],
+ } as unknown as PerformanceEntry])
+ const exporter = new InMemorySpanExporter()
+ const provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ const span = provider.getTracer("alook.frontend").startSpan("navigation")
+ recordDocumentTiming(span, 100_000, 50)
+ span.end()
+ const recorded = exporter.getFinishedSpans()[0]!
+ expect(recorded.attributes).toMatchObject({ server_identity: "unavailable", server_sampling: "unavailable" })
+ expect(recorded.attributes).not.toHaveProperty("server_trace_id")
+ expect(recorded.links).toEqual([])
+ await provider.shutdown()
+})
diff --git a/src/web/src/lib/observability/document-timing.ts b/src/web/src/lib/observability/document-timing.ts
new file mode 100644
index 000000000..3ede16c08
--- /dev/null
+++ b/src/web/src/lib/observability/document-timing.ts
@@ -0,0 +1,29 @@
+import type { Span } from "@opentelemetry/api"
+import { observationTime } from "./clock"
+import { networkEventNames } from "./resource"
+import { responseTraceContext } from "./trace-response"
+
+export const documentEventNames = ["domInteractive", "domContentLoadedEventStart", "domContentLoadedEventEnd", "domComplete", "loadEventStart", "loadEventEnd"] as const
+
+export function recordDocumentTiming(span: Span | undefined, origin: number, ready: number) {
+ if (typeof performance.getEntriesByType !== "function") { span?.setAttribute("document_timing", "unavailable"); return }
+ const entries = performance.getEntriesByType("navigation") as PerformanceNavigationTiming[]
+ if (entries.length !== 1) { span?.setAttribute("document_timing", entries.length ? "ambiguous" : "missing"); return }
+ const entry = entries[0]!
+ const finite = (value: number) => Number.isFinite(value) && value > 0 && value <= ready
+ const names = [...networkEventNames, ...documentEventNames]
+ for (const name of names) if (finite(entry[name])) span?.addEvent(name, observationTime(entry[name], origin))
+ span?.setAttribute("document_timing", documentEventNames.every(name => finite(entry[name])) ? "matched" : "partial")
+ span?.setAttribute("network_event_source", "document_navigation")
+ const serverTiming = Array.from(entry.serverTiming ?? [])
+ const contexts = serverTiming.filter(metric => metric.name === "alook_server")
+ const server = contexts.length === 1 ? responseTraceContext(contexts[0]?.description) : undefined
+ const sampling = serverTiming.filter(metric => metric.name === "alook_sampling")
+ span?.setAttribute("server_identity", server ? "available" : "unavailable")
+ span?.setAttribute("server_sampling", sampling.length === 1 && ["selected", "not_selected"].includes(sampling[0]!.description) ? sampling[0]!.description : "unavailable")
+ if (server) {
+ span?.setAttribute("server_trace_id", server.traceId)
+ span?.setAttribute("server_span_id", server.spanId)
+ span?.addLink({ context: server, attributes: { relationship: "document_response" } })
+ }
+}
diff --git a/src/web/src/lib/observability/navigation-ready-trace.dom.test.tsx b/src/web/src/lib/observability/navigation-ready-trace.dom.test.tsx
index df3c34988..f7e54e209 100644
--- a/src/web/src/lib/observability/navigation-ready-trace.dom.test.tsx
+++ b/src/web/src/lib/observability/navigation-ready-trace.dom.test.tsx
@@ -78,19 +78,19 @@ it("binds the initial navigation before ready and parents a real native HTTP spa
expect(navigationSpan).toHaveLength(1)
expect(navigationSpan[0]).toMatchObject({ name: "navigation", traceId: parent.traceId })
expect(Number(BigInt(String(navigationSpan[0]!.endTimeUnixNano)) - BigInt(String(navigationSpan[0]!.startTimeUnixNano))) / 1e6).toBeCloseTo(1250, 2)
- expect(spans.filter(span => span.parentSpanId === parent.spanId)).toMatchObject([{ name: "GET /api/agents", traceId: parent.traceId }])
+ expect(spans.filter(span => span.parentSpanId === parent.spanId && span.name === "GET /api/agents")).toMatchObject([{ name: "GET /api/agents", traceId: parent.traceId }])
const ready = events.filter(event => event.name === "navigation.ready")
expect(ready).toHaveLength(1)
expect(ready[0]?.attributes).toMatchObject({ navigation_kind: "document", start_ms: "0", duration_ms: "1250", trace_id: parent.traceId, span_id: parent.spanId, action_id: navigation.id })
- const http = spans.find(span => span.parentSpanId === parent.spanId)!
- expect(Number(http.startTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(900, 2)
- expect(Number(http.endTimeUnixNano) / 1e6 - performance.timeOrigin).toBeCloseTo(1012, 2)
+ const http = spans.find(span => span.parentSpanId === parent.spanId && span.name === "GET /api/agents")!
+ expect(Number(http.startTimeUnixNano) / 1e6 - navigation.origin).toBeCloseTo(900, 2)
+ expect(Number(http.endTimeUnixNano) / 1e6 - navigation.origin).toBeCloseTo(1012, 2)
const mirrors = events.filter(event => event.name === "faro.tracing.fetch")
expect(mirrors).toHaveLength(1)
expect(Number(mirrors[0]!.attributes.duration_ms)).toBeCloseTo(112, 2)
expect(JSON.stringify(sent)).not.toContain("alook.internal.http")
const requests = events.filter(event => event.name.startsWith("request."))
- expect(requests.map(event => event.name)).toEqual(["request.start", "request.headers", "request.finish"])
+ expect(requests.map(event => event.name)).toEqual(["request.start", "request.trace_bound", "request.headers", "request.finish"])
expect(requests[0]?.attributes).toMatchObject({ trace_id: parent.traceId, span_id: parent.spanId })
expect(requests[1]?.attributes).toMatchObject({ trace_id: parent.traceId, span_id: http.spanId, request_id: requests[0]!.attributes.request_id })
expect(requests[2]?.attributes).toMatchObject({ trace_id: parent.traceId, span_id: http.spanId, request_id: requests[0]!.attributes.request_id })
diff --git a/src/web/src/lib/observability/navigation-ready.dom.test.tsx b/src/web/src/lib/observability/navigation-ready.dom.test.tsx
index b3192e4a7..85074a83e 100644
--- a/src/web/src/lib/observability/navigation-ready.dom.test.tsx
+++ b/src/web/src/lib/observability/navigation-ready.dom.test.tsx
@@ -26,6 +26,8 @@ it("retains real ready time before a delayed SDK and records each later route on
vi.stubEnv("NEXT_PUBLIC_FARO_COLLECTOR_URL", "https://collector.example/collect/public")
vi.stubEnv("NEXT_PUBLIC_FARO_ENVIRONMENT", undefined); vi.stubEnv("NEXT_PUBLIC_FARO_RELEASE", undefined)
let now = 240
+ const wallStart = Date.now()
+ vi.spyOn(Date, "now").mockImplementation(() => wallStart + now - 240)
vi.spyOn(performance, "now").mockImplementation(() => now)
vi.spyOn(performance, "getEntriesByType").mockReturnValue([])
type Exported = { name: string; timestamp: string; attributes: Record<string, string> }
@@ -66,7 +68,7 @@ it("retains real ready time before a delayed SDK and records each later route on
expect(parent).toHaveLength(1)
expect(metrics()[0]?.attributes).toMatchObject({ trace_id: parent[0]!.traceId, span_id: parent[0]!.spanId })
expect(Number(BigInt(parent[0]!.endTimeUnixNano) - BigInt(parent[0]!.startTimeUnixNano)) / 1e6).toBeCloseTo(240, 2)
- expect(Number(BigInt(parent[0]!.startTimeUnixNano)) / 1e6).toBeCloseTo(performance.timeOrigin, 2)
+ expect(Number(BigInt(parent[0]!.startTimeUnixNano)) / 1e6).toBeCloseTo(wallStart - 240, 2)
expect(exported().filter(event => event.attributes.action_id === metrics()[0]!.attributes.action_id).every(event => event.attributes.trace_id === parent[0]!.traceId && event.attributes.span_id === parent[0]!.spanId)).toBe(true)
expect(exported().filter(event => event.name === "action.start" && event.attributes.action_name === "navigation")).toHaveLength(1)
await act(async () => {
diff --git a/src/web/src/lib/observability/navigation-rsc.dom.test.ts b/src/web/src/lib/observability/navigation-rsc.dom.test.ts
index 1ccf4b3a4..5dd0600d9 100644
--- a/src/web/src/lib/observability/navigation-rsc.dom.test.ts
+++ b/src/web/src/lib/observability/navigation-rsc.dom.test.ts
@@ -60,7 +60,7 @@ it("observes native RSC headers and streamed completion and links a click to its
}
visit(sent)
const requests = () => events.filter(event => event.attributes.action_id === prefetch.id && event.name.startsWith("request."))
- expect(requests().map(event => event.name)).toEqual(["request.start", "request.headers"])
+ expect(requests().map(event => event.name)).toEqual(["request.start", "request.trace_bound", "request.headers"])
const navigation = beginNavigation(href)!
expect(navigation.prefetch).toBe(prefetch)
expect(navigation.span!.spanContext().traceId).not.toBe(parent.traceId)
@@ -70,13 +70,13 @@ it("observes native RSC headers and streamed completion and links a click to its
finishAction(navigation, "success", { phase: "primary", region: "messages" })
await vi.advanceTimersByTimeAsync(5000)
events.length = 0; spans.length = 0; visit(sent)
- expect(requests().map(event => event.name)).toEqual(["request.start", "request.headers", "request.finish"])
+ expect(requests().map(event => event.name)).toEqual(["request.start", "request.trace_bound", "request.headers", "request.finish"])
expect(requests().at(-1)?.attributes).toMatchObject({ phase: "body", outcome: "observed", request_kind: "rsc" })
const http = spans.find(span => span.parentSpanId === parent.spanId)!
expect(http).toMatchObject({ traceId: parent.traceId })
expect(requests().at(-1)?.attributes.span_id).toBe(http.spanId)
expect(spans.find(span => span.spanId === navigation.span!.spanContext().spanId)?.links)
- .toEqual([{ traceId: parent.traceId, spanId: parent.spanId, attributes: [], droppedAttributesCount: 0 }])
+ .toEqual([{ traceId: parent.traceId, spanId: parent.spanId, attributes: [{ key: "relationship", value: { stringValue: "prefetch" } }], droppedAttributesCount: 0, flags: 257 }])
expect(JSON.stringify(sent)).not.toContain("PRIVATE")
expect(JSON.stringify(sent)).toContain("a".repeat(40))
expect(clone).toHaveBeenCalledOnce()
@@ -86,7 +86,7 @@ it("observes native RSC headers and streamed completion and links a click to its
await vi.advanceTimersByTimeAsync(5000)
events.length = 0; spans.length = 0; visit(sent)
const failedRequests = events.filter(event => event.attributes.action_id === failedAction.id && event.name.startsWith("request."))
- expect(failedRequests.map(event => event.name)).toEqual(["request.start", "request.finish"])
+ expect(failedRequests.map(event => event.name)).toEqual(["request.start", "request.trace_bound", "request.finish"])
expect(failedRequests.at(-1)?.attributes).toMatchObject({ phase: "headers", outcome: "error", request_kind: "rsc" })
expect(JSON.stringify(sent)).not.toContain("PRIVATE")
expect(clone).toHaveBeenCalledOnce()
diff --git a/src/web/src/lib/observability/page-visit.dom.test.ts b/src/web/src/lib/observability/page-visit.dom.test.ts
new file mode 100644
index 000000000..f05bc0a90
--- /dev/null
+++ b/src/web/src/lib/observability/page-visit.dom.test.ts
@@ -0,0 +1,183 @@
+import { ROOT_CONTEXT, SpanKind, context, trace } from "@opentelemetry/api"
+import { InMemorySpanExporter, SimpleSpanProcessor, WebTracerProvider } from "@opentelemetry/sdk-trace-web"
+import { afterEach, expect, it, vi } from "vitest"
+import { act } from "@/test/react-dom-harness"
+import { beginNavigation, clearActions, commitNavigation, currentPageObservation, finishAction, installActionSpans, startAction, startPageOperation, finishPageOperation, startRegionObservation, finishRegionObservation, runPageOperation } from "./context"
+import { configureTelemetry, retireTelemetry } from "./telemetry"
+import { startRequest, runObservedFetch } from "./requests"
+import { recordDocumentTiming } from "./document-timing"
+import { observationTime } from "./clock"
+import { observeRestoreRead, observeRestoreDecode, observeHydration } from "./restore"
+
+const nativeProviders: WebTracerProvider[] = []
+function nativeObservation() {
+ const exporter = new InMemorySpanExporter(), provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ nativeProviders.push(provider)
+ provider.register()
+ configureTelemetry({ session_id: "captured-owner" }, true)
+ installActionSpans((name, attributes, startTime, links, parent) => provider.getTracer("alook.frontend").startSpan(name, { attributes, startTime, links }, parent ? trace.setSpan(ROOT_CONTEXT, parent) : ROOT_CONTEXT))
+ return exporter
+}
+function committedVisit(href: string) {
+ window.history.replaceState(null, "", href)
+ const owner = beginNavigation(href, "document")!
+ commitNavigation(href)
+ finishAction(owner, "success", { phase: "primary", region: "page" })
+ return owner
+}
+
+afterEach(async () => { await act(async () => { retireTelemetry(); clearActions(); installActionSpans(undefined) }); await Promise.all(nativeProviders.splice(0).map(provider => provider.shutdown())); context.disable(); trace.disable(); vi.restoreAllMocks(); window.history.replaceState(null, "", "/") })
+
+it("runs business work on its captured page when operation tracing throws", () => {
+ nativeObservation()
+ const owner = committedVisit("/c/me/bots")
+ installActionSpans(() => { throw new Error("tracer unavailable") })
+ const operation = startPageOperation("cache.restore", { phase: "idb_read" }, owner)!
+ const execute = vi.fn(() => "restored")
+ expect(operation.span).toBeUndefined()
+ expect(operation.page).toBe(owner)
+ expect(runPageOperation(operation, execute)).toBe("restored")
+ finishPageOperation(operation, "hit")
+ expect(execute).toHaveBeenCalledOnce()
+ expect(operation.done).toBe(true)
+ expect(operation.outcome).toBe("hit")
+})
+
+it.each(["ws.connect", "cache.restore", "ui.interaction"] as const)("keeps a captured absent owner absent across a later visit for %s", async name => {
+ const exporter = nativeObservation()
+ const owner = currentPageObservation()
+ expect(owner).toBeUndefined()
+ await Promise.resolve()
+ committedVisit("/c/me/bots")
+ const operation = startPageOperation(name, {}, owner)
+ finishPageOperation(operation, "success")
+ expect(operation).toBeUndefined()
+ expect(exporter.getFinishedSpans().map(span => span.name)).toEqual(["navigation"])
+})
+
+it.each(["ws.connect", "cache.restore", "ui.interaction"] as const)("keeps the captured old owner for %s after a new page commits", async name => {
+ const exporter = nativeObservation()
+ const owner = committedVisit("/c/me/bots")
+ await Promise.resolve()
+ const newer = committedVisit("/c/me/machines")
+ const operation = startPageOperation(name, {}, owner)!
+ finishPageOperation(operation, "success")
+ const span = exporter.getFinishedSpans().find(span => span.name === name)!
+ expect(operation.page).toBe(owner)
+ expect(span.parentSpanContext).toEqual(owner.span!.spanContext())
+ expect(span.spanContext().traceId).not.toBe(newer.span!.spanContext().traceId)
+})
+
+it.each(["ws.connect", "cache.restore", "ui.interaction"] as const)("rejects a retired captured owner for %s instead of using the new session page", async name => {
+ const exporter = nativeObservation()
+ const owner = committedVisit("/c/me/bots")
+ retireTelemetry(); clearActions(); configureTelemetry({ session_id: "replacement-owner" }, true)
+ committedVisit("/c/me/machines")
+ const operation = startPageOperation(name, {}, owner)
+ finishPageOperation(operation, "success")
+ expect(operation).toBeUndefined()
+ expect(exporter.getFinishedSpans().map(span => span.name)).toEqual(["navigation", "navigation"])
+})
+
+it("keeps an ownerless restore read, decode and hydration ownerless after a page commits", async () => {
+ const exporter = nativeObservation()
+ const persister = {}
+ const snapshot = { timestamp: Date.now(), buster: "captured", clientState: { queries: [], mutations: [] } }
+ let complete!: (value: typeof snapshot) => void
+ const pending = observeRestoreRead(() => new Promise<typeof snapshot>(resolve => { complete = resolve }), persister)
+ committedVisit("/c/me/bots")
+ complete(snapshot)
+ expect(await pending).toBe(snapshot)
+ expect(observeRestoreDecode(persister, () => snapshot, "captured", 10_000)).toBe(snapshot)
+ observeHydration(persister)
+ expect(exporter.getFinishedSpans().map(span => span.name)).toEqual(["navigation"])
+})
+
+it("keeps post-ready commands and their requests on the visited page, captures old owners and replaces them only at a real visit commit", async () => {
+ const exporter = new InMemorySpanExporter(), provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ provider.register()
+ configureTelemetry({ session_id: "visit-session" }, true)
+ installActionSpans((name, attributes, startTime, links, parent) => provider.getTracer("alook.frontend").startSpan(name, { attributes, startTime, links }, parent ? trace.setSpan(ROOT_CONTEXT, parent) : ROOT_CONTEXT))
+ const a = "/c/me/bots", b = "/c/me/machines"
+ window.history.replaceState(null, "", a)
+ const pageA = beginNavigation(a, "document")!
+ finishAction(pageA, "success", { phase: "primary", region: "bots" })
+ const loadEnd = exporter.getFinishedSpans().find(s => s.name === "navigation")!.endTime
+ expect(currentPageObservation()).toBe(pageA)
+ const command = startAction("message.edit")!
+ const pending = startRequest("/api/agents", { observation: { action: command, reason: "command" } })!
+ const pageB = beginNavigation(b)!
+ expect(currentPageObservation()).toBe(pageA)
+ window.history.pushState(null, "", b)
+ expect(currentPageObservation()).toBeUndefined()
+ commitNavigation(b)
+ finishAction(pageB, "success", { phase: "primary", region: "machines" })
+ const http = runObservedFetch(pending, () => provider.getTracer("@opentelemetry/instrumentation-fetch").startSpan("GET", { kind: SpanKind.CLIENT }))
+ http.end(); finishAction(command, "success")
+ const ws = startPageOperation("ws.event_applied", { phase: "commit", source: "ws" }, currentPageObservation())!
+ finishPageOperation(ws, "success")
+ const spans = exporter.getFinishedSpans(), child = spans.find(s => s.spanContext().spanId === command.span!.spanContext().spanId)!
+ expect(child.parentSpanContext).toEqual(pageA.span!.spanContext())
+ expect(child.spanContext().traceId).toBe(pageA.span!.spanContext().traceId)
+ expect(spans.find(s => s.spanContext().spanId === http.spanContext().spanId)!.parentSpanContext).toEqual(command.span!.spanContext())
+ expect(pageB.span!.spanContext().traceId).not.toBe(pageA.span!.spanContext().traceId)
+ expect(spans.find(s => s.name === "ws.event_applied")!.parentSpanContext).toEqual(pageB.span!.spanContext())
+ expect(spans.find(s => s.spanContext().spanId === pageA.span!.spanContext().spanId)!.endTime).toEqual(loadEnd)
+ retireTelemetry(); clearActions(); configureTelemetry({ session_id: "new-session" }, true)
+ expect(currentPageObservation()).toBeUndefined()
+ expect(startPageOperation("ws.connect", {}, currentPageObservation())).toBeUndefined()
+ await provider.shutdown()
+})
+
+it("adds only actual original-document markers and leaves later DOM work outside its ready interval", () => {
+ vi.spyOn(performance, "getEntriesByType").mockReturnValue([{ domInteractive: 20, domContentLoadedEventStart: 21, domContentLoadedEventEnd: 22, domComplete: 70, loadEventStart: 75, loadEventEnd: 80, responseEnd: 18, serverTiming: [] } as unknown as PerformanceEntry])
+ const provider = new WebTracerProvider(), span = provider.getTracer("alook.frontend").startSpan("navigation")
+ const event = vi.spyOn(span, "addEvent"), attribute = vi.spyOn(span, "setAttribute")
+ recordDocumentTiming(span, 100_000, 50)
+ expect(event.mock.calls.map(([name]) => name)).toEqual(["responseEnd", "domInteractive", "domContentLoadedEventStart", "domContentLoadedEventEnd"])
+ expect(attribute).toHaveBeenCalledWith("document_timing", "partial")
+ expect(attribute).toHaveBeenCalledWith("server_identity", "unavailable")
+ span.end()
+})
+
+it("retains early component, cache and WS intervals through the original deferred set, and clears retired owners", async () => {
+ let now = 10
+ vi.spyOn(performance, "now").mockImplementation(() => now)
+ vi.spyOn(performance, "getEntriesByType").mockReturnValue([])
+ const exporter = new InMemorySpanExporter(), provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ configureTelemetry({ session_id: "early-visit" }, true)
+ window.history.replaceState(null, "", "/c/me/bots")
+ const page = beginNavigation(window.location.href, "document")!
+ const region = startRegionObservation(page, "bots")!
+ const restore = startPageOperation("cache.restore", { phase: "idb_read", cache_stage: "idb" }, currentPageObservation())!
+ now = 25
+ finishRegionObservation(region, page, "success")
+ finishPageOperation(restore, "hit")
+ finishAction(page, "success", { phase: "primary", region: "bots" })
+ now = 30
+ const ws = startPageOperation("ws.connect", { phase: "transport" }, currentPageObservation())!
+ now = 40
+ finishPageOperation(ws, "success")
+ const factory = vi.fn((...args: Parameters<NonNullable<Parameters<typeof installActionSpans>[0]>>) => {
+ const [name, attributes, startTime, links, parent] = args
+ return provider.getTracer("alook.frontend").startSpan(name, { attributes, startTime, links }, parent ? trace.setSpan(ROOT_CONTEXT, parent) : ROOT_CONTEXT)
+ })
+ installActionSpans(factory)
+ const spans = exporter.getFinishedSpans()
+ expect(spans.map(span => span.name)).toEqual(["navigation", "region.wait", "cache.restore", "ws.connect"])
+ for (const operation of [region, restore, ws]) {
+ const span = spans.find(span => span.spanContext().spanId === operation.span!.spanContext().spanId)!
+ expect(span.parentSpanContext).toEqual(page.span!.spanContext())
+ expect(span.startTime).toEqual(observationTime(operation.start, page.origin))
+ expect(span.endTime).toEqual(observationTime(operation.end!, page.origin))
+ }
+ expect(spans[0]!.endTime).toEqual(observationTime(25, page.origin))
+ installActionSpans(undefined)
+ const retired = startPageOperation("cache.restore", {}, currentPageObservation())!
+ retireTelemetry(); clearActions(); configureTelemetry({ session_id: "later-visit" }, true)
+ finishPageOperation(retired, "hit")
+ factory.mockClear(); installActionSpans(factory)
+ expect(factory).not.toHaveBeenCalled()
+ expect(retired.span).toBeUndefined()
+ await provider.shutdown()
+})
diff --git a/src/web/src/lib/observability/query-observer.ts b/src/web/src/lib/observability/query-observer.ts
index 646800c9a..05453f3a6 100644
--- a/src/web/src/lib/observability/query-observer.ts
+++ b/src/web/src/lib/observability/query-observer.ts
@@ -19,7 +19,7 @@ export function observeQueryClient(client: QueryClient) {
const admitted = queries.get(event.query) === telemetryGeneration()
if (event.action.type !== "fetch") queries.delete(event.query)
if (!isTelemetryEligible() || !admitted) return
- emitTelemetry("query.lifecycle", { phase: "background", cache_stage: "query", outcome: event.action.type === "fetch" ? "observed" : event.action.type })
+ emitTelemetry("query.lifecycle", { phase: "unknown", source: "unknown", cache_stage: "query", outcome: event.action.type === "fetch" ? "observed" : event.action.type })
})
const stopMutations = client.getMutationCache().subscribe(event => {
if (event.type !== "updated") return
diff --git a/src/web/src/lib/observability/region-span.dom.test.tsx b/src/web/src/lib/observability/region-span.dom.test.tsx
new file mode 100644
index 000000000..25cdaaa1a
--- /dev/null
+++ b/src/web/src/lib/observability/region-span.dom.test.tsx
@@ -0,0 +1,34 @@
+import { ROOT_CONTEXT, trace } from "@opentelemetry/api"
+import { InMemorySpanExporter, SimpleSpanProcessor, WebTracerProvider } from "@opentelemetry/sdk-trace-web"
+import { afterEach, expect, it, vi } from "vitest"
+import { act, render } from "@/test/react-dom-harness"
+import { beginNavigation, clearActions, installActionSpans } from "./context"
+import { configureTelemetry, retireTelemetry } from "./telemetry"
+import { useObservedRegion } from "./regions"
+import { observationTime } from "./clock"
+
+afterEach(async () => { await act(async () => { retireTelemetry(); clearActions(); installActionSpans(undefined) }); vi.restoreAllMocks(); window.history.replaceState(null, "", "/") })
+it("records only the visible component commit-to-ready wait as a native child without another action timer", async () => {
+ let now = 100
+ vi.spyOn(performance, "now").mockImplementation(() => now)
+ const exporter = new InMemorySpanExporter(), provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ configureTelemetry({ session_id: "chain-session" }, true)
+ installActionSpans((name, attributes, startTime, links, parent) => provider.getTracer("alook.frontend").startSpan(name, { attributes, startTime, links }, parent ? trace.setSpan(ROOT_CONTEXT, parent) : ROOT_CONTEXT))
+ const href = "/c/me/bots"
+ window.history.replaceState(null, "", href)
+ const action = beginNavigation(href)!
+ const timer = vi.spyOn(globalThis, "setTimeout")
+ function Component({ ready }: { ready: boolean }) { useObservedRegion("bots", ready, 1); return <p>{ready ? "ready" : "pending"}</p> }
+ const view = render(<Component ready={false} />)
+ expect(exporter.getFinishedSpans()).toEqual([])
+ expect(timer).not.toHaveBeenCalled()
+ now = 180
+ await act(async () => view.rerender(<Component ready />))
+ const child = exporter.getFinishedSpans().find(span => span.name === "region.wait")!
+ expect(child.parentSpanContext).toEqual(action.span!.spanContext())
+ expect(child.attributes).toMatchObject({ region: "bots", span_role: "region_readiness", phase: "commit", source: "unknown", outcome: "success" })
+ expect(child.startTime).toEqual(observationTime(100, action.origin))
+ expect(child.endTime).toEqual(observationTime(180, action.origin))
+ expect(action.done).toBe(true)
+ await provider.shutdown()
+})
diff --git a/src/web/src/lib/observability/regions.tsx b/src/web/src/lib/observability/regions.tsx
index fc6aa00fe..55cf8ba2e 100644
--- a/src/web/src/lib/observability/regions.tsx
+++ b/src/web/src/lib/observability/regions.tsx
@@ -2,7 +2,7 @@
import { createContext, useContext, type ReactNode, Suspense, useEffect, useRef, useSyncExternalStore } from "react"
import { usePathname, useSearchParams } from "next/navigation"
-import { commitNavigation, committedNavigationPathname, currentRoute, navigationForHref, finishAction, actionAttributes } from "./context"
+import { commitNavigation, committedNavigationPathname, currentRoute, navigationForHref, finishAction, actionAttributes, startRegionObservation, finishRegionObservation, type Action, type PageOperation } from "./context"
import { emitTelemetry, isTelemetryEligible, telemetryGeneration, subscribeObservation, observationSnapshot } from "./telemetry"
import type { Attributes } from "./schema"
@@ -17,6 +17,25 @@ export function useObservedRegion(region: Attributes["region"], ready: boolean,
useSyncExternalStore(subscribeObservation, observationSnapshot, () => 0)
const href = typeof window === "undefined" ? "/" : window.location.pathname + window.location.search
const pathname = committedNavigationPathname(), route = currentRoute(), navigation = navigationForHref(href), generation = telemetryGeneration(), eligible = isTelemetryEligible()
+ const waiting = useRef<{ span?: PageOperation; action: Action; region: Attributes["region"] } | undefined>(undefined)
+ useEffect(() => {
+ if (!visible || !eligible || generation !== telemetryGeneration() || !navigation || navigation.done) return
+ waiting.current = { span: startRegionObservation(navigation, region), action: navigation, region }
+ return () => {
+ if (waiting.current && waiting.current.action === navigation && waiting.current.region === region) {
+ finishRegionObservation(waiting.current.span, navigation, "cancelled")
+ waiting.current = undefined
+ }
+ }
+ }, [visible, eligible, generation, navigation, region])
+ useEffect(() => {
+ if (!ready || !visible || !eligible || generation !== telemetryGeneration() || href !== window.location.pathname + window.location.search) return
+ if (pathname !== undefined && pathname !== window.location.pathname) return
+ if (waiting.current && waiting.current.action === navigation && waiting.current.region === region) {
+ finishRegionObservation(waiting.current.span, navigation, count === 0 ? "empty" : "success")
+ waiting.current = undefined
+ }
+ }, [ready, visible, eligible, generation, href, pathname, navigation, region, count])
const emitted = useRef("")
useEffect(() => {
if (!visible || !ready || !eligible || !isTelemetryEligible() || generation !== telemetryGeneration() || href !== window.location.pathname + window.location.search) return
diff --git a/src/web/src/lib/observability/requests.ts b/src/web/src/lib/observability/requests.ts
index 05bd0af4a..f1fd51fb8 100644
--- a/src/web/src/lib/observability/requests.ts
+++ b/src/web/src/lib/observability/requests.ts
@@ -1,40 +1,49 @@
-import { actionAttributes, telemetryId, navigationForHref, prefetchForHref, type Action } from "./context"
+import { actionAttributes, telemetryId, navigationForHref, prefetchForHref, currentPageObservation, type Action } from "./context"
import { routeTemplate } from "./coverage"
import { emitTelemetry, isTelemetryEligible, telemetryGeneration } from "./telemetry"
import { cleanAttributes, type Attributes } from "./schema"
import { context, trace, createContextKey, type Span } from "@opentelemetry/api"
-import { finishTransportClock } from "./clock"
+import { finishTransportClock, observationOrigin, transportClockOrigin, observationOwnerGeneration, retireObservationSpan } from "./clock"
+import { observeResourceResponse } from "./resource"
+import { readTraceResponse } from "./trace-response"
-export type RequestObservation = { id: string; start: number; generation: number; fields: Attributes; done: boolean; action?: Action }
+export type RequestObservation = { id: string; start: number; origin: number; generation: number; fields: Attributes; done: boolean; action?: Action }
const responses = new WeakMap<Response, RequestObservation>()
const requestContext = createContextKey("alook.request")
const transportRequests = new WeakMap<Span, RequestObservation>()
-export function startRequest(path: string, options?: { method?: string; kind?: Attributes["request_kind"]; observation?: { action?: Action; reason?: Attributes["request_reason"] } }): RequestObservation | undefined {
+export function startRequest(path: string, options?: { method?: string; kind?: Attributes["request_kind"]; observation?: { action?: Action; page?: Action; reason?: Attributes["request_reason"] } }): RequestObservation | undefined {
if (!isTelemetryEligible()) return
const origin = typeof window === "undefined" ? "https://alook.ai" : window.location.origin
- const fields = { ...actionAttributes(options?.observation?.action), route_template: routeTemplate(path, origin), method: options?.method ?? "GET", request_reason: options?.observation?.reason ?? "unknown", request_kind: options?.kind ?? "api", eligibility: "unknown" }
- const request = { id: telemetryId(), start: performance.now(), generation: telemetryGeneration(), fields, done: false, action: options?.observation?.action }
+ const explicit = options?.observation
+ const candidate = explicit?.action ?? explicit?.page ?? (explicit === undefined ? currentPageObservation() : undefined)
+ const action = candidate?.generation === telemetryGeneration() && (!candidate.done || candidate.name === "navigation") ? candidate : undefined
+ const clock = action?.origin ?? observationOrigin()
+ const fields = { ...actionAttributes(action), route_template: routeTemplate(path, origin), method: options?.method ?? "GET", request_reason: options?.observation?.reason ?? "unknown", request_kind: options?.kind ?? "api", eligibility: "unknown", observation_origin_ms: clock, clock_source: "operation_monotonic", clock_domain: "browser", clock_alignment: "unverified" }
+ const request = { id: telemetryId(), start: performance.now(), origin: clock, generation: telemetryGeneration(), fields, done: false, action }
emitTelemetry("request.start", { ...fields, request_id: request.id, start_ms: request.start })
return request
}
export function runObservedFetch<T>(request: RequestObservation | undefined, execute: () => T): T {
const action = request?.action
if (!request || request.generation !== telemetryGeneration() || !isTelemetryEligible()) return execute()
- const original = context.active().setValue(requestContext, request)
+ const original = context.active().setValue(requestContext, request).setValue(observationOwnerGeneration, request.generation)
return context.with(action?.span && action.generation === request.generation ? trace.setSpan(original, action.span) : original, execute)
}
export function observeTransportSpan(span: Span) {
const request = context.active().getValue(requestContext) as RequestObservation | undefined
- if (!request || request.generation !== telemetryGeneration() || !isTelemetryEligible()) return
+ if (!request || request.generation !== telemetryGeneration() || !isTelemetryEligible()) { if (request) retireObservationSpan(span); return }
transportRequests.set(span, request)
const native = span.spanContext()
- request.fields = { ...request.fields, trace_id: native.traceId, span_id: native.spanId }
+ request.fields = { ...request.fields, trace_id: native.traceId, span_id: native.spanId, request_identity: "native_http" }
+ span.setAttribute(transportClockOrigin, request.origin)
for (const [key, value] of Object.entries(cleanAttributes({ ...request.fields, request_id: request.id }))) span.setAttribute(key, value)
+ emitTelemetry("request.trace_bound", { ...request.fields, request_id: request.id, phase: "transport" })
}
export function finishTransportSpan(span: Span, result: unknown) {
finishTransportClock(span)
+ if (result instanceof Response) observeResourceResponse(span, result.headers.get("server-timing") ?? "")
const request = transportRequests.get(span)
transportRequests.delete(span)
if (request?.fields.request_kind !== "rsc") return
@@ -63,12 +72,13 @@ export function installNavigationFetchContext() {
}
function fields(request?: RequestObservation): Attributes {
const current = request?.action?.generation === telemetryGeneration() ? actionAttributes(request.action) : {}
- return request ? { ...request.fields, trace_id: request.fields.trace_id ?? current.trace_id, span_id: request.fields.span_id ?? current.span_id, request_id: request.id, start_ms: request.start, duration_ms: performance.now() - request.start } : {}
+ return request ? { ...request.fields, trace_id: request.fields.trace_id ?? current.trace_id, span_id: request.fields.span_id ?? current.span_id, request_id: request.id, start_ms: request.start, duration_ms: performance.now() - request.start, clock_skew_ms: Math.abs(observationOrigin() - request.origin) } : {}
}
export function requestHeaders(request: RequestObservation | undefined, response: Response) {
if (!request || request.generation !== telemetryGeneration()) return
const ray = response.headers.get("cf-ray") ?? undefined
- request.fields = { ...request.fields, status: response.status, cf_ray: ray }
+ const relation = request.fields.request_identity === "native_http" ? readTraceResponse(response.headers.get("server-timing") ?? "", { traceId: String(request.fields.trace_id), spanId: String(request.fields.span_id) }) : undefined
+ request.fields = { ...request.fields, status: response.status, cf_ray: ray, server_sampling: relation?.sampling ?? "unavailable", server_identity: relation?.server ? "available" : "unavailable", server_trace_id: relation?.server?.traceId, server_span_id: relation?.server?.spanId }
responses.set(response, request)
emitTelemetry("request.headers", { ...fields(request), phase: "headers" })
}
diff --git a/src/web/src/lib/observability/resource.test.ts b/src/web/src/lib/observability/resource.test.ts
new file mode 100644
index 000000000..87bbe7d86
--- /dev/null
+++ b/src/web/src/lib/observability/resource.test.ts
@@ -0,0 +1,79 @@
+import { ROOT_CONTEXT, SpanKind, trace } from "@opentelemetry/api"
+import { InMemorySpanExporter, SimpleSpanProcessor, WebTracerProvider } from "@opentelemetry/sdk-trace-web"
+import { afterEach, expect, it, vi } from "vitest"
+import { ObservationClockProcessor } from "./clock-tracing"
+import { finishTransportClock, observationOrigin, observationTime } from "./clock"
+import { observeResourceResponse } from "./resource"
+import { traceResponse } from "./trace-response"
+
+afterEach(() => { vi.restoreAllMocks() })
+it.each([true, false])("links the exact response server identity without replacing the browser parent when sampled=%s", async sampled => {
+ const exporter = new InMemorySpanExporter()
+ const provider = new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+ const tracer = provider.getTracer("alook.frontend")
+ const root = tracer.startSpan("navigation")
+ const span = tracer.startSpan("GET", { kind: SpanKind.CLIENT }, trace.setSpan(ROOT_CONTEXT, root))
+ const client = span.spanContext()
+ const server = { traceId: "a".repeat(32), spanId: "b".repeat(16), traceFlags: sampled ? 1 : 0 }
+ const response = traceResponse(new Response(), new Request("https://alook.ai/api/agents", { headers: { traceparent: `00-${client.traceId}-${client.spanId}-01` } }), { isTraced: sampled, spanContext: () => server })
+ observeResourceResponse(span, response.headers.get("server-timing")!)
+ span.end()
+ const recorded = exporter.getFinishedSpans()[0]!
+ expect(recorded.attributes).toMatchObject({ server_identity: "available", server_sampling: sampled ? "selected" : "not_selected", server_trace_id: server.traceId, server_span_id: server.spanId })
+ expect(recorded.links).toEqual([{ context: server, attributes: { relationship: "server_response" } }])
+ expect(recorded.parentSpanContext).toEqual(root.spanContext())
+ root.end()
+ await provider.shutdown()
+})
+
+it("projects exact native resources for reversed same-URL requests and retains original parents, links and clocks", async () => {
+ vi.spyOn(Date, "now").mockReturnValue(100_000)
+ let now = 100
+ vi.spyOn(performance, "now").mockImplementation(() => now)
+ const origin = observationOrigin()
+ const entries: PerformanceEntry[] = []
+ vi.spyOn(performance, "getEntriesByType").mockImplementation(() => entries)
+ const exporter = new InMemorySpanExporter(), processor = new ObservationClockProcessor(new SimpleSpanProcessor(exporter))
+ const provider = new WebTracerProvider({ spanProcessors: [processor] })
+ const root = provider.getTracer("alook.frontend").startSpan("navigation")
+ const tracer = provider.getTracer("@opentelemetry/instrumentation-fetch", "0.222.0")
+ const make = () => tracer.startSpan("GET", { kind: SpanKind.CLIENT, links: [{ context: root.spanContext(), attributes: { relationship: "prefetch" } }] }, trace.setSpan(ROOT_CONTEXT, root))
+ const one = make(), two = make()
+ const record = (span: typeof one, responseEnd: number) => {
+ const id = span.spanContext()
+ const response = traceResponse(new Response(), new Request("https://alook.ai/api/agents", { headers: { traceparent: `00-${id.traceId}-${id.spanId}-01` } }), { isTraced: true })
+ observeResourceResponse(span, response.headers.get("server-timing")!)
+ entries.push({ name: "https://alook.ai/api/agents", entryType: "resource", serverTiming: [{ name: "alook_upstream", description: id.traceId + "-" + id.spanId }], fetchStart: 100, requestStart: 105, responseStart: responseEnd - 1, responseEnd, transferSize: 50, encodedBodySize: 30, decodedBodySize: 80, responseStatus: 200, nextHopProtocol: "h2", initiatorType: "fetch" } as unknown as PerformanceEntry)
+ }
+ record(two, 120); now = 120; finishTransportClock(two); two.end()
+ record(one, 180); now = 180; finishTransportClock(one); one.end()
+ const spans = exporter.getFinishedSpans()
+ expect(spans.map(s => s.spanContext().spanId)).toEqual([two.spanContext().spanId, one.spanContext().spanId])
+ for (const [span, end] of [[spans[0]!, 120], [spans[1]!, 180]] as const) {
+ expect(span.attributes).toMatchObject({ resource_status: "matched", cache_hit_status: "fullLoad", clock_domain: "browser", clock_alignment: "unverified" })
+ expect(span.events.find(e => e.name === "responseEnd")?.time).toEqual(observationTime(end, origin))
+ expect(span.parentSpanContext).toEqual(root.spanContext())
+ expect(span.links[0]?.attributes).toEqual({ relationship: "prefetch" })
+ }
+ root.end(); await provider.shutdown()
+})
+
+it("drops guessed network events when cache reuse gives duplicate or absent exact identities", async () => {
+ const entries: PerformanceEntry[] = []
+ vi.spyOn(performance, "getEntriesByType").mockImplementation(() => entries)
+ const exporter = new InMemorySpanExporter(), processor = new ObservationClockProcessor(new SimpleSpanProcessor(exporter))
+ const provider = new WebTracerProvider({ spanProcessors: [processor] }), tracer = provider.getTracer("@opentelemetry/instrumentation-fetch")
+ const first = tracer.startSpan("GET", { kind: SpanKind.CLIENT }), fresh = tracer.startSpan("GET", { kind: SpanKind.CLIENT })
+ const id = first.spanContext(), marker = `alook_upstream;desc="${id.traceId}-${id.spanId}", alook_sampling;desc="selected"`
+ observeResourceResponse(first, marker)
+ entries.push(...[1, 2].map(() => ({ entryType: "resource", serverTiming: [{ name: "alook_upstream", description: id.traceId + "-" + id.spanId }] } as unknown as PerformanceEntry)))
+ first.addEvent("responseEnd"); finishTransportClock(first); first.end()
+ const next = fresh.spanContext()
+ observeResourceResponse(fresh, marker.replace(id.traceId, next.traceId).replace(id.spanId, next.spanId))
+ fresh.addEvent("responseEnd"); finishTransportClock(fresh); fresh.end()
+ const spans = exporter.getFinishedSpans()
+ expect(spans.map(s => s.attributes.resource_status)).toEqual(["ambiguous", "missing"])
+ expect(spans.map(s => s.events)).toEqual([[], []])
+ expect(spans.map(s => s.droppedEventsCount)).toEqual([1, 1])
+ await provider.shutdown()
+})
diff --git a/src/web/src/lib/observability/resource.ts b/src/web/src/lib/observability/resource.ts
new file mode 100644
index 000000000..57908b559
--- /dev/null
+++ b/src/web/src/lib/observability/resource.ts
@@ -0,0 +1,53 @@
+import type { Span } from "@opentelemetry/api"
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-web"
+import { observationTime } from "./clock"
+import { readTraceResponse } from "./trace-response"
+
+const responseMatched = "alook.internal.resource.response_matched"
+export const networkEventNames = ["fetchStart", "domainLookupStart", "domainLookupEnd", "connectStart", "secureConnectionStart", "connectEnd", "requestStart", "responseStart", "responseEnd"] as const
+const networkNames = new Set<string>(networkEventNames)
+const protocols = new Set(["http/1.0", "http/1.1", "h2", "h3"])
+
+export function observeResourceResponse(span: Span, header: string) {
+ const response = readTraceResponse(header, span.spanContext())
+ span.setAttribute(responseMatched, response.matched)
+ span.setAttribute("server_sampling", response.sampling)
+ span.setAttribute("server_identity", response.server ? "available" : "unavailable")
+ if (response.server) {
+ span.setAttribute("server_trace_id", response.server.traceId)
+ span.setAttribute("server_span_id", response.server.spanId)
+ span.addLink({ context: response.server, attributes: { relationship: "server_response" } })
+ }
+}
+
+export function projectResource(span: ReadableSpan, origin: number) {
+ const unrelated = span.events.filter(event => !networkNames.has(event.name))
+ const discarded = span.events.length - unrelated.length
+ const unavailable = (resource_status: string) => ({ events: unrelated, attributes: { ...span.attributes, resource_status }, discarded })
+ if (span.attributes[responseMatched] !== true) return unavailable("unavailable")
+ if (typeof performance.getEntriesByType !== "function") return unavailable("unsupported")
+ const context = span.spanContext()
+ const identity = context.traceId + "-" + context.spanId
+ const resources = performance.getEntriesByType("resource").filter((entry): entry is PerformanceResourceTiming => "serverTiming" in entry)
+ .filter(entry => {
+ const markers = Array.from(entry.serverTiming ?? []).filter(metric => metric.name === "alook_upstream")
+ return markers.length === 1 && markers[0]?.description === identity
+ })
+ if (resources.length !== 1) return unavailable(resources.length ? "ambiguous" : "missing")
+ const resource = resources[0]!
+ const finite = (value: number) => Number.isFinite(value) && value >= 0
+ const events = networkEventNames.flatMap(name => finite(resource[name]) && resource[name] > 0
+ ? [{ name, time: observationTime(resource[name], origin), attributes: {} }] : [])
+ const cache = resource.transferSize === 0 && resource.decodedBodySize > 0 ? "cache"
+ : resource.responseStatus === 304 ? "conditionalFetch" : "fullLoad"
+ const attributes = {
+ ...span.attributes,
+ resource_status: "matched", network_event_source: "resource_identity", cache_hit_status: cache,
+ ...(protocols.has(resource.nextHopProtocol) ? { network_protocol: resource.nextHopProtocol } : {}),
+ ...(["fetch", "xmlhttprequest"].includes(resource.initiatorType) ? { initiator_type: resource.initiatorType } : {}),
+ }
+ for (const [key, value] of Object.entries({ transfer_bytes: resource.transferSize, encoded_bytes: resource.encodedBodySize, decoded_bytes: resource.decodedBodySize })) {
+ if (finite(value)) Object.assign(attributes, { [key]: value })
+ }
+ return { events: [...unrelated, ...events], attributes, discarded: 0 }
+}
diff --git a/src/web/src/lib/observability/restore.ts b/src/web/src/lib/observability/restore.ts
index 572128524..30ef290ab 100644
--- a/src/web/src/lib/observability/restore.ts
+++ b/src/web/src/lib/observability/restore.ts
@@ -1,44 +1,48 @@
import type { PersistedClient } from "@tanstack/react-query-persist-client"
import { emitTelemetry, isTelemetryEligible, telemetryGeneration } from "./telemetry"
-import { telemetryId } from "./context"
+import { telemetryId, currentPageObservation, startPageOperation, finishPageOperation, pageOperationAttributes, type PageOperation, type Action } from "./context"
-const restored = new WeakMap<object, { count: number; start: number; id: string; generation: number }>()
-const reads = new WeakMap<object, Array<{ generation: number; eligible: boolean }>>()
-export async function observeRestoreRead<T>(operation: () => Promise<T>, persister?: object): Promise<T> {
+const restored = new WeakMap<object, { count: number; start: number; id: string; generation: number; operation?: PageOperation }>()
+const reads = new WeakMap<object, Array<{ generation: number; eligible: boolean; page?: Action }>>()
+export async function observeRestoreRead<T>(read: () => Promise<T>, persister?: object): Promise<T> {
const generation = telemetryGeneration(), eligible = isTelemetryEligible()
- const start = performance.now(), id = telemetryId()
- if (eligible) emitTelemetry("cache.restore.start", { request_id: id, start_ms: start, phase: "idb_read", cache_stage: "idb" })
+ const start = performance.now(), id = telemetryId(), operation = startPageOperation("cache.restore", { phase: "idb_read", cache_stage: "idb" }, currentPageObservation())
+ if (eligible) emitTelemetry("cache.restore.start", { ...pageOperationAttributes(operation), request_id: id, start_ms: start, phase: "idb_read", cache_stage: "idb" })
try {
- const result = await operation()
+ const result = await read()
if (persister && result != null) {
const pending = reads.get(persister) ?? []
- pending.push({ generation, eligible })
+ pending.push({ generation, eligible, page: operation?.page })
if (pending.length > 4) for (const receipt of pending) { receipt.eligible = false; receipt.generation = -1 }
reads.set(persister, pending.slice(-4))
}
- if (eligible && generation === telemetryGeneration()) emitTelemetry("cache.restore.finish", { request_id: id, phase: "idb_read", outcome: result == null ? "miss" : "hit", duration_ms: performance.now() - start })
+ finishPageOperation(operation, result == null ? "miss" : "hit")
+ if (eligible && generation === telemetryGeneration()) emitTelemetry("cache.restore.finish", { ...pageOperationAttributes(operation), request_id: id, phase: "idb_read", outcome: result == null ? "miss" : "hit", duration_ms: performance.now() - start })
return result
} catch (error) {
- if (eligible && generation === telemetryGeneration()) emitTelemetry("cache.restore.finish", { request_id: id, phase: "idb_read", outcome: "error", duration_ms: performance.now() - start })
+ finishPageOperation(operation, "error")
+ if (eligible && generation === telemetryGeneration()) emitTelemetry("cache.restore.finish", { ...pageOperationAttributes(operation), request_id: id, phase: "idb_read", outcome: "error", duration_ms: performance.now() - start })
throw error
}
}
-export function observeRestoreDecode(persister: object, operation: () => PersistedClient, expectedBuster: string, maxAge: number): PersistedClient {
+export function observeRestoreDecode(persister: object, decode: () => PersistedClient, expectedBuster: string, maxAge: number): PersistedClient {
const admission = reads.get(persister)?.shift()
const generation = admission?.generation ?? telemetryGeneration()
const eligible = (reads.has(persister) ? admission?.eligible === true : isTelemetryEligible()) && generation === telemetryGeneration() && isTelemetryEligible()
- const start = performance.now(), id = telemetryId()
- if (eligible) emitTelemetry("cache.restore.start", { request_id: id, phase: "deserialize", start_ms: start })
+ const start = performance.now(), id = telemetryId(), operation = eligible ? startPageOperation("cache.restore", { phase: "deserialize", cache_stage: "idb" }, admission?.page) : undefined
+ if (eligible) emitTelemetry("cache.restore.start", { ...pageOperationAttributes(operation), request_id: id, phase: "deserialize", start_ms: start })
try {
- const snapshot = operation()
+ const snapshot = decode()
const outcome = snapshot.buster !== expectedBuster ? "buster" : Date.now() - snapshot.timestamp > maxAge || !snapshot.timestamp ? "expired" : "hit"
+ finishPageOperation(operation, outcome)
if (eligible && generation === telemetryGeneration()) {
- emitTelemetry("cache.restore.finish", { request_id: id, phase: "deserialize", outcome, duration_ms: performance.now() - start, count: snapshot.clientState.queries.length })
- if (outcome === "hit") restored.set(persister, { count: snapshot.clientState.queries.length, start: performance.now(), id: telemetryId(), generation })
+ emitTelemetry("cache.restore.finish", { ...pageOperationAttributes(operation), request_id: id, phase: "deserialize", outcome, duration_ms: performance.now() - start, count: snapshot.clientState.queries.length })
+ if (outcome === "hit") restored.set(persister, { count: snapshot.clientState.queries.length, start: performance.now(), id: telemetryId(), generation, operation: startPageOperation("cache.restore", { phase: "hydrate", cache_stage: "query" }, operation?.page) })
}
return snapshot
} catch (error) {
- if (eligible && generation === telemetryGeneration()) emitTelemetry("cache.restore.finish", { request_id: id, phase: "deserialize", outcome: "error", duration_ms: performance.now() - start })
+ finishPageOperation(operation, "error")
+ if (eligible && generation === telemetryGeneration()) emitTelemetry("cache.restore.finish", { ...pageOperationAttributes(operation), request_id: id, phase: "deserialize", outcome: "error", duration_ms: performance.now() - start })
throw error
}
}
@@ -46,7 +50,8 @@ export function observeHydration(persister: object) {
const evidence = restored.get(persister)
restored.delete(persister)
if (!evidence || !isTelemetryEligible() || evidence.generation !== telemetryGeneration()) return
- emitTelemetry("cache.restore.start", { request_id: evidence.id, start_ms: evidence.start, phase: "hydrate" })
- emitTelemetry("cache.restore.finish", { request_id: evidence.id, phase: "hydrate", outcome: "success", count: evidence.count, duration_ms: performance.now() - evidence.start })
+ finishPageOperation(evidence.operation, "success")
+ emitTelemetry("cache.restore.start", { ...pageOperationAttributes(evidence.operation), request_id: evidence.id, start_ms: evidence.start, phase: "hydrate" })
+ emitTelemetry("cache.restore.finish", { ...pageOperationAttributes(evidence.operation), request_id: evidence.id, phase: "hydrate", outcome: "success", count: evidence.count, duration_ms: performance.now() - evidence.start })
}
export function discardHydration(persister: object) { restored.delete(persister); reads.delete(persister) }
diff --git a/src/web/src/lib/observability/sanitize.test.ts b/src/web/src/lib/observability/sanitize.test.ts
index 0c7f9d259..3c6f1509d 100644
--- a/src/web/src/lib/observability/sanitize.test.ts
+++ b/src/web/src/lib/observability/sanitize.test.ts
@@ -8,6 +8,23 @@ import { resolveFrontendIdentity } from "./runtime"
const origin = "https://alook.ai", session = "safe-session"
const meta = { sdk: { name: "faro-web", version: "2.12.1", integrations: [{ name: "SECRET", version: "SECRET" }] }, session: { id: session }, page: { url: origin + "/c/invite/SECRET?token=SECRET#SECRET" }, user: { email: "[email protected]", fullName: "SECRET" } }
describe("outbound whitelist", () => {
+ it("retains exact resource events and safe link relationships with honest native and filtered dropped counts", () => {
+ const fields = { "session.id": session, resource_status: "matched", network_event_source: "resource_identity", cache_hit_status: "cache", network_protocol: "h2" }
+ const span = { traceId: "a".repeat(32), spanId: "b".repeat(16), name: "GET", kind: 3, startTimeUnixNano: "1000000000", endTimeUnixNano: "2000000000", droppedAttributesCount: 2, droppedEventsCount: 3, droppedLinksCount: 4,
+ attributes: Object.entries(fields).map(([key, value]) => ({ key, value: { stringValue: value } })),
+ events: [{ name: "requestStart", timeUnixNano: "1100000000", attributes: [{ key: "private", value: { stringValue: "SECRET" } }] }, { name: "SECRET", timeUnixNano: "1200000000" }],
+ links: [{ traceId: "c".repeat(32), spanId: "d".repeat(16), attributes: [{ key: "relationship", value: { stringValue: "server_response" } }], droppedAttributesCount: 1 }], status: { code: 1, message: "SECRET" } }
+ const clean = sanitizeTrace({ resourceSpans: [{ scopeSpans: [{ scope: { name: "@opentelemetry/instrumentation-fetch", version: "0.222.0" }, spans: [span] }] }] }, session, origin)!
+ const scope = clean.resourceSpans[0]!.scopeSpans[0]!, result = scope.spans[0]!
+ expect(scope.scope).toEqual({ name: "@opentelemetry/instrumentation-fetch", version: "0.222.0" })
+ expect(result.events).toEqual([{ name: "requestStart", timeUnixNano: "1100000000", attributes: [], droppedAttributesCount: 1 }])
+ expect(result.droppedEventsCount).toBe(4)
+ expect(result.droppedLinksCount).toBe(4)
+ expect(result.links[0]?.attributes).toEqual([{ key: "relationship", value: { stringValue: "server_response" } }])
+ expect(result.status).toEqual({ code: 1 })
+ expect(JSON.stringify(clean)).not.toContain("SECRET")
+ })
+
it("templates IDs, never exposes query or external arbitrary URLs", () => {
for (const path of ["/w/private/agents/a/chat/b?token=SECRET", "/w", "/workspaces", "/studio/new?token=SECRET", "/invite/SECRET"]) {
expect(routeTemplate(path, origin)).toBe("/unmapped")
@@ -63,7 +80,7 @@ describe("outbound whitelist", () => {
{ traceId: "c".repeat(32), spanId: "0".repeat(16) },
] }
const clean = sanitizeTrace({ resourceSpans: [{ scopeSpans: [{ spans: [span] }] }] }, session, origin)!
- expect(clean.resourceSpans[0]!.scopeSpans[0]!.spans[0]!.links).toEqual([{ traceId: "c".repeat(32), spanId: "d".repeat(16), attributes: [], droppedAttributesCount: 0 }])
+ expect(clean.resourceSpans[0]!.scopeSpans[0]!.spans[0]!.links).toEqual([{ traceId: "c".repeat(32), spanId: "d".repeat(16), attributes: [], droppedAttributesCount: 1 }])
expect(JSON.stringify(clean)).not.toContain("SECRET")
})
it("omits unknown HTTP methods without changing internal or real HTTP span identity", () => {
diff --git a/src/web/src/lib/observability/sanitize.ts b/src/web/src/lib/observability/sanitize.ts
index bfc30909e..664d76494 100644
--- a/src/web/src/lib/observability/sanitize.ts
+++ b/src/web/src/lib/observability/sanitize.ts
@@ -3,6 +3,9 @@ import { actionNames, routeTemplate } from "./coverage"
import { cleanAttributes, eventNames } from "./schema"
import type { FrontendIdentity } from "./runtime"
import { resolveObservationBuild } from "./build"
+import { documentEventNames } from "./document-timing"
+import { transportClockStart, transportClockEnd, retiredObservationSpan } from "./clock"
+import { networkEventNames } from "./resource"
const actions = new Set<string>(actionNames)
const events = new Set<string>([...eventNames, "session_start", "session_resume", "session_extend", "faro.user.action", "faro.tracing.fetch", "faro.tracing.xml-http-request", "faro.performance.resource", "faro.performance.navigation"])
@@ -12,8 +15,15 @@ const record = (value: unknown): Record<string, unknown> => value && typeof valu
const array = (value: unknown): unknown[] => Array.isArray(value) ? value : []
const hex = (value: unknown, size: number) => typeof value === "string" && new RegExp("^[0-9a-f]{" + size + "}$").test(value) && !/^0+$/.test(value) ? value : undefined
const nano = (value: unknown) => typeof value === "string" && /^\d{1,22}$/.test(value) ? value : undefined
+const count = (value: unknown) => Number.isInteger(Number(value)) && Number(value) >= 0 && Number(value) <= 0xffffffff ? Number(value) : 0
+const networkEvents = new Set<string>(networkEventNames)
+const documentEvents = new Set<string>([...networkEventNames, ...documentEventNames])
-export function sanitizeTrace(input: unknown, sessionId: string, origin: string, identity?: Partial<FrontendIdentity> & { release?: string; environment?: string }, since = 0) {
+function qualifiedMonotonic(fields: Record<string, unknown>, since?: number) {
+ const start = Number(fields[transportClockStart]), end = Number(fields[transportClockEnd])
+ return since !== undefined && Number.isFinite(since) && numeric(start) && numeric(end) && end >= start && start >= since
+}
+export function sanitizeTrace(input: unknown, sessionId: string, origin: string, identity?: Partial<FrontendIdentity> & { release?: string; environment?: string }, since = 0, monotonicSince?: number) {
const canonical = { ...(identity ? { frontend_surface: identity.frontend_surface, client_platform: identity.client_platform, app_version: identity.app_version } : {}),
...resolveObservationBuild({ NEXT_PUBLIC_FARO_RELEASE: identity?.release, NEXT_PUBLIC_FARO_ENVIRONMENT: identity?.environment }) }
const context = cleanAttributes(canonical)
@@ -24,8 +34,9 @@ export function sanitizeTrace(input: unknown, sessionId: string, origin: string,
const fields = Object.fromEntries(array(span.attributes).map(rawAttribute => {
const attribute = record(rawAttribute)
const value = record(attribute.value)
- return [String(attribute.key), value.stringValue ?? value.intValue ?? value.doubleValue]
+ return [String(attribute.key), value.stringValue ?? value.intValue ?? value.doubleValue ?? value.boolValue]
}))
+ if (fields[retiredObservationSpan] === true || fields[retiredObservationSpan] === "true") return []
if (fields["session.id"] !== sessionId) return []
const url = String(fields["url.full"] ?? fields["http.url"] ?? "")
const rawMethod = fields["http.request.method"] ?? fields["http.method"]
@@ -40,24 +51,49 @@ export function sanitizeTrace(input: unknown, sessionId: string, origin: string,
const traceId = hex(span.traceId, 32), spanId = hex(span.spanId, 16)
const startTimeUnixNano = nano(span.startTimeUnixNano), endTimeUnixNano = nano(span.endTimeUnixNano)
if (!traceId || !spanId || !startTimeUnixNano || !endTimeUnixNano) return []
+ const pageOperation = ["ws.connect", "ws.event_applied", "cache.restore", "ui.interaction"].includes(String(span.name)) && attributes.span_role === "page_operation" && attributes.page_id !== undefined
+ const regionSpan = span.name === "region.wait" && attributes.span_role === "region_readiness" && attributes.region !== undefined
const businessAction = actions.has(String(span.name)) && fields.action_name === span.name && typeof fields.action_id === "string" && /^[a-zA-Z0-9_-]{1,80}$/.test(fields.action_id)
- if (!businessAction && Number(startTimeUnixNano) / 1e6 < since) return []
+ if (!businessAction && !regionSpan && !pageOperation && !qualifiedMonotonic(fields, monotonicSince) && Number(startTimeUnixNano) / 1e6 < since) return []
+ const rawEvents = array(span.events)
+ const safeEvents = rawEvents.flatMap(raw => {
+ const event = record(raw), timeUnixNano = nano(event.timeUnixNano)
+ const qualifiedResource = fields.resource_status === "matched" && fields.network_event_source === "resource_identity" && networkEvents.has(String(event.name))
+ const qualifiedDocument = fields.navigation_kind === "document" && fields.network_event_source === "document_navigation" && ["matched", "partial"].includes(String(fields.document_timing)) && documentEvents.has(String(event.name))
+ return (qualifiedResource || qualifiedDocument) && timeUnixNano
+ ? [{ name: String(event.name), timeUnixNano, attributes: [], droppedAttributesCount: count(event.droppedAttributesCount) + array(event.attributes).length }] : []
+ })
+ const rawLinks = array(span.links)
+ const safeLinks = rawLinks.flatMap(raw => {
+ const link = record(raw), traceId = hex(link.traceId, 32), spanId = hex(link.spanId, 16)
+ if (!traceId || !spanId) return []
+ const linkAttributes = array(link.attributes).flatMap(raw => {
+ const attribute = record(raw), value = record(attribute.value).stringValue
+ return attribute.key === "relationship" && ["prefetch", "server_response", "document_response"].includes(String(value))
+ ? [{ key: "relationship", value: { stringValue: String(value) } }] : []
+ })
+ return [{ traceId, spanId, ...(link.flags !== undefined ? { flags: count(link.flags) } : {}), attributes: linkAttributes, droppedAttributesCount: count(link.droppedAttributesCount) + array(link.attributes).length - linkAttributes.length }]
+ })
+ const removedAttributes = array(span.attributes).filter(raw => !Object.hasOwn(attributes, String(record(raw).key))).length
return [{
traceId, spanId, parentSpanId: hex(span.parentSpanId, 16),
- name: actions.has(String(span.name)) ? String(span.name) : (method ? method + " " : "") + String(template),
+ name: pageOperation ? String(span.name) : regionSpan ? "region.wait" : actions.has(String(span.name)) ? String(span.name) : (method ? method + " " : "") + String(template),
kind: (Number(span.kind) >= 0 && Number(span.kind) <= 5 ? Number(span.kind) : 0) as 0 | 1 | 2 | 3 | 4 | 5,
startTimeUnixNano,
endTimeUnixNano,
attributes: Object.entries(attributes).map(([key,value]) => ({ key, value: { stringValue: value } })),
- status: { code: (Number(record(span.status).code) === 2 ? 2 : 0) as 0 | 2 },
- droppedAttributesCount: 0, droppedEventsCount: 0, droppedLinksCount: 0,
- events: [], links: array(span.links).flatMap(raw => {
- const link = record(raw), traceId = hex(link.traceId, 32), spanId = hex(link.spanId, 16)
- return traceId && spanId ? [{ traceId, spanId, attributes: [], droppedAttributesCount: 0 }] : []
- }),
+ status: { code: (Number(record(span.status).code) === 1 ? 1 : Number(record(span.status).code) === 2 ? 2 : 0) as 0 | 1 | 2 },
+ ...(span.flags !== undefined ? { flags: count(span.flags) } : {}),
+ droppedAttributesCount: count(span.droppedAttributesCount) + removedAttributes,
+ droppedEventsCount: count(span.droppedEventsCount) + rawEvents.length - safeEvents.length,
+ droppedLinksCount: count(span.droppedLinksCount) + rawLinks.length - safeLinks.length,
+ events: safeEvents, links: safeLinks,
}]
})
- return spans.length ? [{ scope: { name: "alook.frontend" }, spans }] : []
+ const nativeScope = record(record(scope).scope)
+ const scopeName = ["alook.frontend", "@opentelemetry/instrumentation-fetch", "@opentelemetry/instrumentation-xml-http-request"].includes(String(nativeScope.name)) ? String(nativeScope.name) : "alook.frontend"
+ const version = typeof nativeScope.version === "string" && /^\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(nativeScope.version) ? nativeScope.version : undefined
+ return spans.length ? [{ scope: { name: scopeName, ...(version ? { version } : {}) }, spans }] : []
})
const attributes = { "service.name": "alook-web", ...(context.app_version ? { "service.version": context.app_version } : {}), ...context }
return scopes.length ? [{ resource: { attributes: Object.entries(attributes).map(([key, value]) => ({ key, value: { stringValue: value } })), droppedAttributesCount: 0 }, scopeSpans: scopes }] : []
@@ -65,7 +101,7 @@ export function sanitizeTrace(input: unknown, sessionId: string, origin: string,
return resources.length ? { resourceSpans: resources } : null
}
-export function sanitizeItem(item: TransportItem, sessionId: string, origin: string, identity?: Partial<FrontendIdentity>, since = 0, documentVitalsEligible = true, spanSince = since): TransportItem | null {
+export function sanitizeItem(item: TransportItem, sessionId: string, origin: string, identity?: Partial<FrontendIdentity>, since = 0, documentVitalsEligible = true, spanSince = since, monotonicSince?: number): TransportItem | null {
if (item.meta.session?.id !== sessionId) return null
const sdk = item.meta.sdk
if (sdk?.name !== "faro-web" || !/^\d{1,3}\.\d{1,3}\.\d{1,3}(?:-[a-zA-Z0-9.-]{1,32})?$/.test(sdk.version ?? "")) return null
@@ -92,6 +128,8 @@ export function sanitizeItem(item: TransportItem, sessionId: string, origin: str
const template = routeTemplate(fields.name ?? "", origin)
attrs.name = template
Object.assign(attrs, cleanAttributes({ route_template: template, request_kind: payload.name === "faro.performance.navigation" ? "document" : "resource" }))
+ Object.assign(attrs, cleanAttributes({ faroResourceId: fields.faroResourceId, faroNavigationId: fields.faroNavigationId,
+ cache_hit_status: fields.cacheHitStatus, network_protocol: fields.protocol, initiator_type: fields.initiatorType, resource_status: "unavailable", cache_stage: "http" }))
for (const key of ["duration", "tcpHandshakeTime", "dnsLookupTime", "tlsNegotiationTime", "redirectTime", "requestTime", "responseTime", "fetchTime", "serviceWorkerTime", "decodedBodySize", "encodedBodySize", "ttfb", "transferSize", "pageLoadTime", "documentParsingTime", "domProcessingTime", "domContentLoadHandlerTime", "onLoadTime"]) {
const value = fields[key]
if (typeof value === "string" && value.trim() !== "" && numeric(Number(value))) attrs[key] = String(Number(value))
@@ -100,7 +138,8 @@ export function sanitizeItem(item: TransportItem, sessionId: string, origin: str
}
if (payload.name.startsWith("faro.tracing.")) {
const fields = payload.attributes ?? {}
- if (!(Date.parse(payload.timestamp) - Number(fields.duration_ns) / 1e6 >= spanSince)) return null
+ if (fields[retiredObservationSpan] === "true") return null
+ if (!qualifiedMonotonic(fields, monotonicSince) && !(Date.parse(payload.timestamp) - Number(fields.duration_ns) / 1e6 >= spanSince)) return null
const url = String(fields["url.full"] ?? fields["http.url"] ?? "")
let kind = "unknown"
try { const parsed = new URL(url, origin); kind = parsed.origin !== origin ? "external" : parsed.searchParams.has("_rsc") ? "rsc" : parsed.pathname.startsWith("/api/") ? "api" : "resource" } catch {}
@@ -137,7 +176,7 @@ export function sanitizeItem(item: TransportItem, sessionId: string, origin: str
return Object.keys(values).length ? { ...item, meta: documentMeta, payload: { type: payload.type, timestamp: payload.timestamp, values } } : null
}
if (item.type === "trace") {
- const payload = sanitizeTrace(item.payload, sessionId, origin, { ...identity, release: item.meta.app?.release, environment: item.meta.app?.environment }, spanSince)
+ const payload = sanitizeTrace(item.payload, sessionId, origin, { ...identity, release: item.meta.app?.release, environment: item.meta.app?.environment }, spanSince, monotonicSince)
return payload ? { ...item, meta, payload: payload as TraceEvent } : null
}
return null
diff --git a/src/web/src/lib/observability/schema.ts b/src/web/src/lib/observability/schema.ts
index 9501c5c0f..13b3719be 100644
--- a/src/web/src/lib/observability/schema.ts
+++ b/src/web/src/lib/observability/schema.ts
@@ -3,7 +3,7 @@ import { actionNames, apiRoutes, pageRoutes } from "./coverage"
export const eventNames = [
"action.start", "action.finish", "navigation.intent", "navigation.commit", "navigation.ready",
"cache.restore.start", "cache.restore.finish", "query.lifecycle",
- "region.ready_commit", "request.start", "request.headers",
+ "region.ready_commit", "request.start", "request.trace_bound", "request.headers",
"request.body_parsed", "request.finish", "data.publish", "data.response_rejected",
"ws.connect", "ws.ready", "ws.close", "ws.reconnect", "ws.event_applied",
"main_thread.longtask", "telemetry.coverage", "telemetry.drop", "business.result", "message.milestone",
@@ -19,12 +19,25 @@ const enumValues: Record<string, ReadonlySet<string>> = Object.fromEntries(Objec
release_status: ["present", "missing"],
environment_status: ["present", "missing"],
trace_context: ["received", "missing"],
+ request_identity: ["native_http"],
+ server_sampling: ["selected", "not_selected", "unavailable"],
+ server_identity: ["available", "unavailable"],
+ span_role: ["region_readiness", "page_operation"],
+ document_timing: ["matched", "partial", "missing", "ambiguous", "unavailable"],
+ resource_status: ["matched", "missing", "ambiguous", "unavailable", "unsupported"],
+ network_event_source: ["resource_identity", "document_navigation"],
+ cache_hit_status: ["cache", "conditionalFetch", "fullLoad"],
+ network_protocol: ["http/1.0", "http/1.1", "h2", "h3"],
+ initiator_type: ["fetch", "xmlhttprequest", "script", "css", "img", "link", "iframe", "navigation", "other", "beacon"],
+ clock_source: ["operation_monotonic"],
+ clock_domain: ["browser", "worker"],
+ clock_alignment: ["unverified"],
auth_instance: ["created", "reused", "request_local"],
auth_reuse_reason: ["cold", "version_changed", "configuration_changed", "version_missing", "match"],
frontend_surface: ["web", "blog", "webview"],
client_platform: ["browser", "desktop", "mobile"],
navigation_kind: ["document", "route"],
- phase: ["intent", "headers", "body", "read", "primary", "background", "hydrate", "idb_read", "deserialize", "commit", "frame", "interaction", "optimistic", "ack", "upload", "transport", "auth", "token", "validation"],
+ phase: ["unknown", "intent", "headers", "body", "read", "primary", "background", "hydrate", "idb_read", "deserialize", "commit", "frame", "interaction", "optimistic", "ack", "upload", "transport", "auth", "token", "validation"],
outcome: ["success", "error", "cancelled", "superseded", "timeout", "noop", "observed", "unknown", "empty", "miss", "hit", "expired", "buster", "rejected", "disabled", "unavailable", "partial"],
source: ["restored_idb", "network", "ws", "local_mutation", "mixed", "unknown"],
eligibility: ["eligible", "rejected", "unknown", "denied"],
@@ -37,8 +50,8 @@ const enumValues: Record<string, ReadonlySet<string>> = Object.fromEntries(Objec
drop_reason: ["early_queue_full", "transport_failure", "withdrawal", "account_switch", "stale_session", "sdk_load", "invalid_config", "unload_unknown"],
cache_stage: ["idb", "query", "router", "http", "canonical"],
}).map(([key, values]) => [key, new Set(values)]))
-const numberFields = new Set(["start_ms", "duration_ms", "count", "row_count", "changed_count", "removed_count", "status", "schema_version", "revision", "attempt", "collection_rate", "drop_count", "transfer_bytes", "encoded_bytes", "decoded_bytes"])
-const idFields = new Set(["ws_event_id", "session_id", "page_instance_id", "action_id", "navigation_id", "request_id", "prefetch_action_id", "worker_version", "user_key"])
+const numberFields = new Set(["start_ms", "duration_ms", "clock_skew_ms", "count", "row_count", "changed_count", "removed_count", "status", "schema_version", "revision", "attempt", "collection_rate", "drop_count", "transfer_bytes", "encoded_bytes", "decoded_bytes"])
+const idFields = new Set(["ws_event_id", "session_id", "page_instance_id", "page_id", "action_id", "navigation_id", "request_id", "prefetch_action_id", "worker_version", "user_key", "faroResourceId", "faroNavigationId"])
export function cleanAttributes(input: Record<string, unknown>): Record<string, string> {
const result: Record<string, string> = {}
@@ -53,8 +66,8 @@ export function cleanAttributes(input: Record<string, unknown>): Record<string,
else if (key === "route_template" && routes.has(text)) result[key] = text
else if (key === "action_name" && names.has(text)) result[key] = text
else if (key === "cf_ray" && /^[0-9a-f]{16}-[A-Z]{3}$/.test(text)) result[key] = text
- else if ((key === "trace_id" || key === "upstream_trace_id") && /^[0-9a-f]{32}$/.test(text)) result[key] = text
- else if ((key === "span_id" || key === "upstream_span_id") && /^[0-9a-f]{16}$/.test(text)) result[key] = text
+ else if ((key === "trace_id" || key === "upstream_trace_id" || key === "server_trace_id") && /^[0-9a-f]{32}$/.test(text) && !/^0+$/.test(text)) result[key] = text
+ else if ((key === "span_id" || key === "upstream_span_id" || key === "server_span_id") && /^[0-9a-f]{16}$/.test(text) && !/^0+$/.test(text)) result[key] = text
else if (key === "event_type" && /^(community:|connection\.|auth\.)[a-z_.]{1,50}$/.test(text)) result[key] = text
}
return result
diff --git a/src/web/src/lib/observability/telemetry.ts b/src/web/src/lib/observability/telemetry.ts
index e4c4c893d..e98126284 100644
--- a/src/web/src/lib/observability/telemetry.ts
+++ b/src/web/src/lib/observability/telemetry.ts
@@ -55,7 +55,8 @@ export function retireTelemetry(reason: "boundary" | "native_session" = "boundar
export function isNativeSessionContinuation(original: number) { return eligible && nativeContinuationFrom === original }
export function emitTelemetry(name: TelemetryEvent, attributes: Attributes = {}) {
if (!eligible) return
- const event = { name, attributes: cleanAttributes({ ...base, ...attributes, schema_version: 1 }), timestamp: observationEpoch() }
+ const origin = typeof attributes.observation_origin_ms === "number" && Number.isFinite(attributes.observation_origin_ms) ? attributes.observation_origin_ms : undefined
+ const event = { name, attributes: cleanAttributes({ ...base, ...attributes, schema_version: 1 }), timestamp: observationEpoch(performance.now(), origin) }
if (sink) { try { sink(event) } catch { dropped++ } }
else if (queue.length < LIMIT) queue.push(event)
else dropped++
diff --git a/src/web/src/lib/observability/trace-response.test.ts b/src/web/src/lib/observability/trace-response.test.ts
new file mode 100644
index 000000000..db36e231d
--- /dev/null
+++ b/src/web/src/lib/observability/trace-response.test.ts
@@ -0,0 +1,42 @@
+import { expect, it } from "vitest"
+import { readTraceResponse, responseTraceContext, traceResponse } from "./trace-response"
+
+const client = { traceId: "a".repeat(32), spanId: "b".repeat(16), traceFlags: 1 }
+const server = { traceId: "c".repeat(32), spanId: "d".repeat(16), traceFlags: 1 }
+const request = () => new Request("https://alook.ai/api/agents", { headers: { traceparent: `00-${client.traceId}-${client.spanId}-01`, authorization: "private-token" } })
+
+it("preserves the original stream, status and cache headers and uses only actual native server identity", async () => {
+ const stream = new ReadableStream({ start(controller) { controller.enqueue(new TextEncoder().encode("body")); controller.close() } })
+ const original = new Response(stream, { status: 202, headers: { "cache-control": "no-store", "server-timing": 'db;dur=2;desc="a,b"' } })
+ const response = traceResponse(original, request(), { isTraced: true, spanContext: () => server })
+ expect(response.body).toBe(original.body)
+ expect(response.status).toBe(202)
+ expect(response.headers.get("cache-control")).toBe("no-store")
+ const header = response.headers.get("server-timing")!
+ expect(header).toContain('db;dur=2;desc="a,b"')
+ expect(header).not.toContain("private-token")
+ expect(header).not.toContain("/api/agents")
+ expect(readTraceResponse(header, client)).toEqual({ matched: true, server, sampling: "selected" })
+ expect(await response.text()).toBe("body")
+})
+
+it("separates sampler selection from getter availability and never substitutes upstream identity", () => {
+ for (const isTraced of [true, false]) {
+ const response = traceResponse(new Response(), request(), { isTraced })
+ expect(readTraceResponse(response.headers.get("server-timing")!, client)).toEqual({ matched: true, server: undefined, sampling: isTraced ? "selected" : "not_selected" })
+ expect(response.headers.get("server-timing")).not.toContain("traceparent;")
+ }
+ for (const getter of [() => ({ ...server, traceId: "0".repeat(32) }), () => { throw new Error("missing runtime capability") }]) {
+ const response = traceResponse(new Response(), request(), { isTraced: true, spanContext: getter })
+ expect(readTraceResponse(response.headers.get("server-timing")!, client).server).toBeUndefined()
+ }
+ expect(traceResponse(Response.error(), request()).status).toBe(0)
+})
+
+it("rejects zero, malformed, missing, repeated and stale response identities", () => {
+ const header = traceResponse(new Response(), request(), { isTraced: true, spanContext: () => server }).headers.get("server-timing")!
+ for (const value of ["", header + `, alook_upstream;desc="${client.traceId}-${client.spanId}"`, header.replace(client.spanId, "e".repeat(16))]) {
+ expect(readTraceResponse(value, client)).toEqual({ matched: false, server: undefined, sampling: "unavailable" })
+ }
+ for (const value of [null, "00-" + "0".repeat(32) + "-" + client.spanId + "-01", "ff-" + client.traceId + "-" + client.spanId + "-01"]) expect(responseTraceContext(value)).toBeUndefined()
+})
diff --git a/src/web/src/lib/observability/trace-response.ts b/src/web/src/lib/observability/trace-response.ts
new file mode 100644
index 000000000..0111cebcc
--- /dev/null
+++ b/src/web/src/lib/observability/trace-response.ts
@@ -0,0 +1,74 @@
+import type { SpanContext } from "@opentelemetry/api"
+
+type NativeSpan = NonNullable<ReturnType<ExecutionContext["tracing"]["getActiveSpan"]>>
+type NativeTrace = Partial<Pick<NativeSpan, "isTraced">> & { spanContext?: () => SpanContext }
+type Sampling = "selected" | "not_selected" | "unavailable"
+const owned = new Set(["alook_upstream", "alook_server", "alook_sampling"])
+const identifier = (value: unknown, size: number) => typeof value === "string" && new RegExp("^[0-9a-f]{" + size + "}$").test(value) && !/^0+$/.test(value)
+
+function metrics(header: string): string[] {
+ const result: string[] = []
+ let start = 0, quoted = false, escaped = false
+ for (let i = 0; i < header.length; i++) {
+ const char = header[i]
+ if (escaped) { escaped = false; continue }
+ if (quoted && char === "\\") { escaped = true; continue }
+ if (char === '"') quoted = !quoted
+ else if (char === "," && !quoted) { result.push(header.slice(start, i).trim()); start = i + 1 }
+ }
+ result.push(header.slice(start).trim())
+ return result.filter(Boolean)
+}
+
+function description(header: string, name: string) {
+ if (header.length > 4096) return
+ const matches = metrics(header).filter(metric => metric.split(";", 1)[0]?.trim() === name)
+ if (matches.length !== 1) return
+ return new RegExp("^" + name + ';\\s*desc="([a-z0-9_-]+)"$').exec(matches[0]!)?.[1]
+}
+
+export function responseTraceContext(value: string | null | undefined): SpanContext | undefined {
+ const match = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(value ?? "")
+ return match && identifier(match[1], 32) && identifier(match[2], 16)
+ ? { traceId: match[1]!, spanId: match[2]!, traceFlags: parseInt(match[3]!, 16) }
+ : undefined
+}
+
+function nativeContext(span?: NativeTrace) {
+ try {
+ const value = typeof span?.spanContext === "function" ? span.spanContext() : undefined
+ return value && identifier(value.traceId, 32) && identifier(value.spanId, 16)
+ && Number.isInteger(value.traceFlags) && value.traceFlags >= 0 && value.traceFlags <= 255
+ ? value : undefined
+ } catch { return undefined }
+}
+
+export function traceResponse(response: Response, request: Request, span?: NativeTrace) {
+ if (response.status === 101 || response.status === 0) return response
+ const upstream = responseTraceContext(request.headers.get("traceparent"))
+ const server = nativeContext(span)
+ const sampling: Sampling = typeof span?.isTraced === "boolean" ? span.isTraced ? "selected" : "not_selected" : "unavailable"
+ const headers = new Headers(response.headers)
+ const existing = metrics(headers.get("server-timing") ?? "").filter(metric => !owned.has(metric.split(";", 1)[0]?.trim() ?? ""))
+ if (upstream) existing.push('alook_upstream;desc="' + upstream.traceId + "-" + upstream.spanId + '"')
+ existing.push('alook_sampling;desc="' + sampling + '"')
+ if (server) {
+ const parent = "00-" + server.traceId + "-" + server.spanId + "-" + server.traceFlags.toString(16).padStart(2, "0")
+ existing.push('alook_server;desc="' + parent + '"')
+ if (!existing.some(metric => metric.split(";", 1)[0]?.trim() === "traceparent")) existing.push('traceparent;desc="' + parent + '"')
+ }
+ headers.set("server-timing", existing.join(", "))
+ return new Response(response.body, { status: response.status, statusText: response.statusText, headers })
+}
+
+export function readTraceResponse(header: string, client: Pick<SpanContext, "traceId" | "spanId">) {
+ const upstream = description(header, "alook_upstream")
+ const matched = identifier(client.traceId, 32) && identifier(client.spanId, 16) && upstream === client.traceId + "-" + client.spanId
+ const sampling = description(header, "alook_sampling")
+ const server = matched ? responseTraceContext(description(header, "alook_server")) : undefined
+ return {
+ matched,
+ server,
+ sampling: matched && (sampling === "selected" || sampling === "not_selected") ? sampling : "unavailable" as Sampling,
+ }
+}
diff --git a/src/web/src/lib/observability/worker.test.ts b/src/web/src/lib/observability/worker.test.ts
index fe53384f9..634f2d117 100644
--- a/src/web/src/lib/observability/worker.test.ts
+++ b/src/web/src/lib/observability/worker.test.ts
@@ -42,7 +42,8 @@ it("uses explicit missing build provenance when the caller supplies no profile",
const handler = createWebWorkerHandler({ fetch })
const returned = await handler.fetch!(new Request("https://fixture.test/c/me"), {} as CloudflareEnv,
{ tracing: { enterSpan } } as unknown as ExecutionContext)
- expect(returned).toBe(response)
+ expect(returned.body).toBe(response.body)
+ expect(returned.headers.get("server-timing")).toBe('alook_sampling;desc="unavailable"')
expect(await returned.text()).toBe("same-body")
expect(fetch).toHaveBeenCalledOnce()
expect(Object.fromEntries(setAttribute.mock.calls)).toMatchObject({ release_status: "missing", environment_status: "missing", worker_version_status: "missing" })
diff --git a/src/web/src/lib/use-user-ws.ts b/src/web/src/lib/use-user-ws.ts
index aca4b55fa..241280eb3 100644
--- a/src/web/src/lib/use-user-ws.ts
+++ b/src/web/src/lib/use-user-ws.ts
@@ -1,4 +1,5 @@
"use client"
+import { currentPageObservation, startPageOperation, finishPageOperation, pageOperationAttributes, runPageOperation, type PageOperation } from "@/lib/observability/context"
import { emitTelemetry, isTelemetryEligible, telemetryGeneration } from "@/lib/observability/telemetry"
import { useEffect, useRef, useCallback } from "react"
import {
@@ -56,6 +57,7 @@ type PendingTokenAttempt = {
startedAt: number
reported: boolean
observationGeneration: number
+ operation?: PageOperation
}
type CredentialRetry = {
@@ -280,14 +282,17 @@ export function useUserWs(
requestDaemonStatusOnAuthRef.current = options?.requestDaemonStatusOnAuth ?? true
}, [options?.requestDaemonStatusOnAuth])
- const observedSockets = useRef(new WeakMap<WebSocket, { generation: number; start: number }>())
+ const observedSockets = useRef(new WeakMap<WebSocket, { generation: number; start: number; operation?: PageOperation }>())
const connectRef = useRef<(() => Promise<void>) | null>(null)
const publishConnectionPhase = useCallback((phase: UserWsConnectionPhase) => {
if (lastConnectionPhaseRef.current === phase) return
lastConnectionPhaseRef.current = phase
const observed = wsRef.current ? observedSockets.current.get(wsRef.current) : undefined
- if (phase === "authenticated" && observed?.generation === telemetryGeneration()) emitTelemetry("ws.ready", { phase: "auth", outcome: "success", duration_ms: performance.now() - observed.start })
+ if (phase === "authenticated" && observed?.generation === telemetryGeneration()) {
+ finishPageOperation(observed.operation, "success")
+ emitTelemetry("ws.ready", { ...pageOperationAttributes(observed.operation), phase: "auth", outcome: "success", duration_ms: performance.now() - observed.start })
+ }
runLifecycleCallback("connection-state", () =>
onConnectionStateChangeRef.current?.(phase))
}, [])
@@ -324,7 +329,8 @@ export function useUserWs(
) => {
if (attempt.reported) return
attempt.reported = true
- if (attempt.observationGeneration === telemetryGeneration()) emitTelemetry("ws.connect", { phase: "token", outcome: result === "success" ? "success" : result === "aborted" ? "cancelled" : result === "timeout" ? "timeout" : "error", duration_ms: boundedDurationMs(attempt.startedAt) })
+ finishPageOperation(attempt.operation, result === "success" ? "success" : result === "aborted" ? "cancelled" : result === "timeout" ? "timeout" : "error")
+ if (attempt.observationGeneration === telemetryGeneration()) emitTelemetry("ws.connect", { ...pageOperationAttributes(attempt.operation), phase: "token", outcome: result === "success" ? "success" : result === "aborted" ? "cancelled" : result === "timeout" ? "timeout" : "error", duration_ms: attempt.operation ? performance.now() - attempt.operation.start : boundedDurationMs(attempt.startedAt) })
trackCommunityWsLifecycleStage({
stage: "token",
result,
@@ -370,7 +376,8 @@ export function useUserWs(
if (!reportedCloseSocketsRef.current.has(ws)) {
reportedCloseSocketsRef.current.add(ws)
const observed = observedSockets.current.get(ws)
- if (observed?.generation === telemetryGeneration()) emitTelemetry("ws.close", { phase: "transport", outcome: "observed", duration_ms: performance.now() - observed.start, status: code })
+ finishPageOperation(observed?.operation, localInitiator ? "cancelled" : "error")
+ if (observed?.generation === telemetryGeneration()) emitTelemetry("ws.close", { ...pageOperationAttributes(observed.operation), phase: "transport", outcome: "observed", duration_ms: performance.now() - observed.start, status: code })
trackCommunityWsLifecycleClose({
initiator,
code,
@@ -427,7 +434,7 @@ export function useUserWs(
}
stopHeartbeat()
if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }
- if (ws) closeSocket(ws, initiator)
+ if (ws) { finishPageOperation(observedSockets.current.get(ws)?.operation, "cancelled"); closeSocket(ws, initiator) }
}, [clearConnectionValidation, closeSocket, stopHeartbeat])
const stopCredentialRetry = useCallback(() => {
@@ -558,7 +565,7 @@ export function useUserWs(
clearTimeout(reconnectTimerRef.current)
reconnectTimerRef.current = null
}
- const observationGeneration = telemetryGeneration()
+ const observationGeneration = telemetryGeneration(), observationPage = currentPageObservation()
const currentSession = currentSdkWsSession(viewerUserId)
const sdkSession = hasAuthenticatedBeforeRef.current
&& currentSession?.session.id !== credentialRetryRef.current.rejectedSessionId
@@ -577,8 +584,9 @@ export function useUserWs(
startedAt: Date.now(),
reported: false,
observationGeneration,
+ operation: startPageOperation("ws.connect", { phase: "token" }, observationPage),
}
- if (isTelemetryEligible()) emitTelemetry("ws.connect", { phase: "token", start_ms: performance.now(), outcome: "observed" })
+ if (isTelemetryEligible()) emitTelemetry("ws.connect", { ...pageOperationAttributes(tokenAttempt.operation), phase: "token", start_ms: performance.now(), outcome: "observed" })
pendingTokenRef.current = tokenAttempt
let tokenTimedOut = false
tokenTimeoutRef.current = setTimeout(() => {
@@ -596,7 +604,7 @@ export function useUserWs(
if (refresh) retry.refreshUsed = true
let tokenResponseReceived = false
try {
- const res = await fetch(refresh ? "/api/ws/token?refresh=1" : "/api/ws/token", { signal: tokenController.signal })
+ const res = await runPageOperation(tokenAttempt.operation, () => fetch(refresh ? "/api/ws/token?refresh=1" : "/api/ws/token", { signal: tokenController.signal }))
tokenResponseReceived = true
if (
pendingTokenRef.current !== tokenAttempt
@@ -698,20 +706,23 @@ export function useUserWs(
let communityAdmission = Promise.resolve()
let pendingAdmissions = 0
let ws: WebSocket
+ let socketObservation: PageOperation | undefined
try {
if (generation !== connectionGenerationRef.current || isOffline() || !isCurrentWsAccount(viewerUserId)) return
retireSocket(true, "local-retire")
if (generation !== connectionGenerationRef.current || isOffline() || !isCurrentWsAccount(viewerUserId)) return
+ socketObservation = startPageOperation("ws.connect", { phase: "transport" }, observationPage)
ws = new WebSocket(url)
} catch (err) {
+ finishPageOperation(socketObservation, "error")
if (generation !== connectionGenerationRef.current) return
reportOpenStage("failure")
console.warn("[ws] WebSocket creation failed:", err)
scheduleReconnect(generation)
return
}
- observedSockets.current.set(ws, { generation: observationGeneration, start: performance.now() })
- if (observationGeneration === telemetryGeneration()) emitTelemetry("ws.connect", { phase: "transport", outcome: "observed" })
+ observedSockets.current.set(ws, { generation: observationGeneration, start: performance.now(), operation: socketObservation })
+ if (observationGeneration === telemetryGeneration()) emitTelemetry("ws.connect", { ...pageOperationAttributes(socketObservation), phase: "transport", outcome: "observed" })
wsRef.current = ws
connectStartedAtRef.current = Date.now()
connectTimeoutRef.current = setTimeout(() => {
diff --git a/src/web/src/lib/worker-runtime.ts b/src/web/src/lib/worker-runtime.ts
index 9aa9a3125..ae0e89143 100644
--- a/src/web/src/lib/worker-runtime.ts
+++ b/src/web/src/lib/worker-runtime.ts
@@ -2,6 +2,7 @@ import { cleanAttributes, type Attributes } from "./observability/schema"
import { routeTemplate } from "./observability/coverage"
import { resolveObservationBuild } from "./observability/build"
import { finalizePublicWorkerResponse } from "./public-worker-response"
+import { traceResponse, responseTraceContext } from "./observability/trace-response"
const PUBLIC_DOCUMENTS = new Set(["/", "/pricing", "/privacy", "/templates"])
@@ -16,6 +17,7 @@ export function createWebWorkerHandler(
return {
async fetch(request, env, ctx) {
const url = new URL(request.url)
+ const invocation = ctx.tracing?.getActiveSpan?.()
const isWsUpgrade = request.headers.get("Upgrade")?.toLowerCase() === "websocket"
const isWsPath = url.pathname === "/api/ws" || url.pathname.startsWith("/api/ws/")
@@ -23,24 +25,23 @@ export function createWebWorkerHandler(
return env.WS_DO_WORKER.fetch(request)
}
- const execute = async () => {
+ const execute = async (span?: Parameters<typeof traceResponse>[2]) => {
const response = await openNextHandler.fetch!(request, env, ctx)
- return finalizePublicWorkerResponse(response, isPublicRoute(url.pathname), request)
+ return traceResponse(finalizePublicWorkerResponse(response, isPublicRoute(url.pathname), request), request, invocation ?? span)
}
return ctx.tracing ? ctx.tracing.enterSpan("web.request", span => {
const fields = cleanAttributes({ ...workerRequestAttributes(request, env, build), route_template: routeTemplate(request.url, url.origin), request_kind: url.searchParams.has("_rsc") ? "rsc" : url.pathname.startsWith("/api/") ? "api" : "document" })
for (const [key, value] of Object.entries(fields)) span.setAttribute(key, value)
- return execute()
+ return execute(span)
}) : execute()
},
}
}
export function workerRequestAttributes(request: Request, env: Pick<Env, "CF_VERSION_METADATA">, build: ReturnType<typeof resolveObservationBuild>): Attributes {
- const parent = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(request.headers.get("traceparent") ?? "")
- const valid = parent && !/^0+$/.test(parent[1]!) && !/^0+$/.test(parent[2]!)
- return { ...build,
+ const parent = responseTraceContext(request.headers.get("traceparent"))
+ return { ...build, clock_domain: "worker", clock_alignment: "unverified",
worker_version: env.CF_VERSION_METADATA?.id, worker_version_status: env.CF_VERSION_METADATA?.id ? "present" : "missing",
- upstream_trace_id: valid ? parent[1] : undefined, upstream_span_id: valid ? parent[2] : undefined,
- trace_context: valid ? "received" : "missing" }
+ upstream_trace_id: parent?.traceId, upstream_span_id: parent?.spanId,
+ trace_context: parent ? "received" : "missing" }
}