diff --git a/doc/browser-performance-tracing.md b/doc/browser-performance-tracing.md index e82eab2efc1..e3b5ea04d45 100644 --- a/doc/browser-performance-tracing.md +++ b/doc/browser-performance-tracing.md @@ -63,7 +63,10 @@ for `0.25`), so Honeycomb's `COUNT` and percentiles are weighted correctly. Volume per sampled session: one `page.load` span per navigation, up to three `web_vital.*` spans per page lifetime, and one span per same-origin `/api/` -request made during a measured navigation or after the SDK loads. +request that starts while a navigation is being measured (see +[Live API spans](#live-api-spans)). Requests made while no navigation is being +measured, such as background polling in an idle tab, send nothing, and request +spans carry no span events. ## Load-speed cost @@ -193,9 +196,37 @@ URLs, server addresses, status messages, and event attributes, is dropped. | --- | --- | | `page.load` | One per hard load or client navigation. | | `web_vital.lcp`, `web_vital.inp`, `web_vital.cls` | Core Web Vitals, from Google's `web-vitals`, usually reported as the tab hides. Zero duration; the value is an attribute. | -| `GET`, `POST`, … | A `fetch` to this origin's `/api/`. Its `traceparent` header joins the server's request span to the same trace. While a `page.load` span is open it is the parent, so one trace shows the navigation, its API calls, and (when server tracing is on) their server spans. | +| `GET`, `POST`, … | A `fetch` to this origin's `/api/` that starts while a `page.load` span is open, as its child. Its `traceparent` header joins the server's request span to the same trace, so one trace shows the navigation, its API calls, and (when server tracing is on) their server spans. See below. | | `HTTP` | A request to this origin's `/api/` made before the SDK loaded, during a measured navigation (in practice the hard load), rebuilt from Resource Timing. See below. | +### Live API spans + +The rule: **a `fetch` to this origin's `/api/` is recorded only when it starts +while a `page.load` measurement is open.** It is a child of that `page.load` +and sends a `traceparent`, even if it finishes after the navigation ends. + +A request that starts while no measurement is open (background polling, a +refetch after a live update, a mutation in a page that already loaded) gets no +span and no `traceparent`. The fetch instrumentation receives a non-recording +span with an invalid trace context for it, so nothing is exported and the +standard trace context propagator sends no header +(`measuredRequestsOnly` in `ui/src/lib/browser-tracing/sdk.ts`). The server +traces such a request on its own, exactly as it does for a tab that is not +sampled. There is therefore no browser span without a `page.load` parent and +no server span that points at a browser span that was never sent. + +Failed idle requests are not kept either: the server's own request span +already records a server error, and keeping them would mean recording every +idle request and sending its `traceparent` before its status is known. + +Request spans carry **no span events**. The fetch instrumentation runs with +`ignoreNetworkEvents: true`, so the per-request Resource Timing events +(`fetchStart`, `domainLookupStart`, `domainLookupEnd`, `connectStart`, +`secureConnectionStart`, `connectEnd`, `requestStart`, `responseStart`, +`responseEnd`) are not sent. Honeycomb stores each span event as its own +event, so they multiplied request volume by about 10, and the span's own +duration already covers the request. + ### Backfilled API spans The hard load's API requests happen before the SDK exists. When the SDK loads, @@ -250,7 +281,8 @@ not sent here because Sentry already reports them ([observability.md](observability.md#sentry-error-monitoring)). Trace headers go only to this origin (`propagateTraceHeaderCorsUrls` is empty), -so no third party receives a `traceparent`. Same-origin requests need no CORS +and only on requests that start during a measured navigation, so no third +party receives a `traceparent`. Same-origin requests need no CORS change. The server's OpenTelemetry HTTP instrumentation continues the trace when server tracing is enabled ([observability.md](observability.md#enabling-tracing)). diff --git a/ui/src/lib/browser-tracing/sdk.test.ts b/ui/src/lib/browser-tracing/sdk.test.ts index a826417016b..082e1d6621d 100644 --- a/ui/src/lib/browser-tracing/sdk.test.ts +++ b/ui/src/lib/browser-tracing/sdk.test.ts @@ -124,6 +124,74 @@ describe("startTracingSdk", () => { const traceparent = headersOf(fetchMock.mock.calls[0]!).get("traceparent")!; expect(traceparent.split("-")[1]).toBe(pageSpan!.spanContext().traceId); }); + + it("records no span and sends no traceparent for an API request made while no page load is measured", async () => { + const recorder = idleRecorder(); + const flush = (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames; + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: performance.now() }); + flush(); + handle = startTracingSdk(config, recorder, { exporter }); + + // Background polling with no navigation open. + await fetch(`${window.location.origin}/api/companies/abc/live-runs`); + await fetch(`${window.location.origin}/api/issues`, { method: "POST" }); + // The next navigation's requests are recorded again. + recorder.begin({ routeTemplate: "/:companyPrefix/issues/:issueId", loadType: "client", startTime: performance.now() }); + await fetch(`${window.location.origin}/api/issues/PAP-77`); + + const headersOf = (call: unknown[]) => new Headers((call[1] as RequestInit | undefined)?.headers); + expect(headersOf(fetchMock.mock.calls[0]!).get("traceparent")).toBeNull(); + expect(headersOf(fetchMock.mock.calls[1]!).get("traceparent")).toBeNull(); + expect(headersOf(fetchMock.mock.calls[2]!).get("traceparent")).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/); + + flush(); + await new Promise((resolve) => setTimeout(resolve, 400)); + await handle.forceFlush(); + const spans = exporter.getFinishedSpans(); + const requests = spans.filter((span) => span.name !== "page.load"); + expect(requests.map((span) => span.attributes["paperclip.api.area"])).toEqual(["issues"]); + const issuePage = spans.find((span) => span.name === "page.load" && span.attributes["paperclip.page.route"] === "/:companyPrefix/issues/:issueId")!; + expect(requests[0]!.parentSpanContext?.spanId).toBe(issuePage.spanContext().spanId); + // Every exported span is a page load, a vital, or a child of a page load. + const pageSpanIds = new Set(spans.filter((span) => span.name === "page.load").map((span) => span.spanContext().spanId)); + for (const span of requests) expect(pageSpanIds.has(span.parentSpanContext!.spanId)).toBe(true); + }); + + it("sends request spans without per-request network timing events", async () => { + const recorder = idleRecorder(); + recorder.begin({ routeTemplate: "/:companyPrefix/issues", loadType: "client", startTime: performance.now() }); + handle = startTracingSdk(config, recorder, { exporter }); + const url = `${window.location.origin}/api/issues`; + // The browser's Resource Timing entry for the request, which the fetch + // instrumentation turns into `fetchStart`, `responseEnd`, … events. + let timing: PerformanceResourceTiming | null = null; + fetchMock.mockImplementationOnce(async () => { + const start = performance.now(); + timing = { + name: url, entryType: "resource", initiatorType: "fetch", startTime: start, + fetchStart: start, domainLookupStart: start, domainLookupEnd: start, connectStart: start, + secureConnectionStart: start, connectEnd: start, requestStart: start, responseStart: start + 0.1, + responseEnd: start + 0.2, encodedBodySize: 2, decodedBodySize: 2, + } as unknown as PerformanceResourceTiming; + return new Response("{}", { status: 200 }); + }); + const realGetEntriesByType = performance.getEntriesByType.bind(performance); + const getEntries = vi.spyOn(performance, "getEntriesByType").mockImplementation(((type: string) => + type === "resource" && timing ? [timing] : realGetEntriesByType(type)) as typeof performance.getEntriesByType); + try { + await fetch(url); + (recorder as PageLoadRecorder & { flushFrames(): void }).flushFrames(); + await new Promise((resolve) => setTimeout(resolve, 400)); + await handle.forceFlush(); + // The instrumentation found the entry, so timing events could be added. + expect(getEntries).toHaveBeenCalledWith("resource"); + } finally { + getEntries.mockRestore(); + } + const [request] = exporter.getFinishedSpans().filter((span) => span.name === "GET"); + expect(request).toBeDefined(); + expect(request!.events.map((event) => event.name)).toEqual([]); + }); }); describe("hard-load API spans from Resource Timing", () => { diff --git a/ui/src/lib/browser-tracing/sdk.ts b/ui/src/lib/browser-tracing/sdk.ts index 2a76c92f36a..aaddd955d4b 100644 --- a/ui/src/lib/browser-tracing/sdk.ts +++ b/ui/src/lib/browser-tracing/sdk.ts @@ -11,13 +11,27 @@ // Emitted spans (see doc/browser-performance-tracing.md): // page.load one per hard load or client-side navigation // web_vital.lcp|inp|cls Core Web Vitals -// GET|POST|… same-origin `/api/` fetches, with W3C trace context -// so the server's request span joins the trace +// GET|POST|… same-origin `/api/` fetches that start while a +// page.load is open, as its children, with W3C trace +// context so the server's request span joins the +// trace; no network timing events // HTTP same-origin `/api/` requests made before this chunk // loaded, rebuilt from Resource Timing under the // page.load they belong to (no method, no server join) -import { context, propagation, trace, ROOT_CONTEXT, SpanKind, type Attributes, type Context, type Span } from "@opentelemetry/api"; +import { + context, + propagation, + trace, + INVALID_SPAN_CONTEXT, + ROOT_CONTEXT, + SpanKind, + type Attributes, + type Context, + type Span, + type Tracer, + type TracerProvider, +} from "@opentelemetry/api"; import { AlwaysOnSampler, BatchSpanProcessor, @@ -55,6 +69,34 @@ class PageLoadContextManager extends StackContextManager { } } +/** + * The tracer provider given to the fetch instrumentation. A request that + * starts while no page load is being measured (background polling, a refetch + * in an idle tab) gets a non-recording span with an invalid context: nothing + * is recorded or exported, and the trace context propagator sends no + * `traceparent` for an invalid context, so the server traces that request on + * its own exactly as for an unsampled tab. A request that starts while a page + * load is open is a normal child of it. + */ +export function measuredRequestsOnly(provider: TracerProvider, isMeasuring: () => boolean): TracerProvider { + return { + getTracer(name, version, options) { + const tracer = provider.getTracer(name, version, options); + const unrecorded = () => trace.wrapSpanContext(INVALID_SPAN_CONTEXT); + const gated: Tracer = { + startSpan: (spanName, spanOptions, spanContext) => + isMeasuring() ? tracer.startSpan(spanName, spanOptions, spanContext) : unrecorded(), + startActiveSpan: ((...args: unknown[]) => { + if (isMeasuring()) return (tracer.startActiveSpan as (...a: unknown[]) => unknown)(...args); + const fn = args[args.length - 1] as (span: Span) => unknown; + return fn(unrecorded()); + }) as Tracer["startActiveSpan"], + }; + return gated; + }, + }; +} + /** Escapes a string for use inside a regular expression. */ function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); @@ -198,9 +240,13 @@ export function startTracingSdk( ignoreUrls: [nonApiUrlPattern(window.location.origin)], propagateTraceHeaderCorsUrls: [], clearTimingResources: false, + // The nine per-request timing events (fetchStart, responseEnd, …) are + // each stored as a separate event by Honeycomb, about 10x the volume of + // the request span, and its duration already covers them. + ignoreNetworkEvents: true, enabled: false, }); - fetchInstrumentation.setTracerProvider(provider); + fetchInstrumentation.setTracerProvider(measuredRequestsOnly(provider, () => openPageSpan !== null)); // Requests from here on get live fetch spans; earlier ones are backfilled. const liveFetchSince = performance.now(); fetchInstrumentation.enable(); diff --git a/ui/src/lib/browser-tracing/span-sanitizer.ts b/ui/src/lib/browser-tracing/span-sanitizer.ts index c8f00ec7d6b..b93247eb3c0 100644 --- a/ui/src/lib/browser-tracing/span-sanitizer.ts +++ b/ui/src/lib/browser-tracing/span-sanitizer.ts @@ -99,7 +99,8 @@ export function sanitizeSpan(span: ReadableSpan): ReadableSpan { status: { code: span.status.code }, attributes, links: [], - // Network timing events keep their names and times, never attributes. + // Any span event keeps its name and time, never its attributes. The fetch + // instrumentation runs with `ignoreNetworkEvents`, so request spans have none. events: span.events.map((event) => ({ name: event.name, time: event.time, droppedAttributesCount: 0 })), duration: span.duration, ended: span.ended,