feat(browser): Emit web vitals as streamed spans#19827
feat(browser): Emit web vitals as streamed spans#19827
Conversation
size-limit report 📦
|
8bf8eaf to
c966a4a
Compare
1a5cfb3 to
28c0d45
Compare
Semver Impact of This PR🟡 Minor (new features) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨Core
Deps
Other
Bug Fixes 🐛Core
Other
Internal Changes 🔧Core
Deps
Other
🤖 This preview updates automatically when you update the PR. |
c966a4a to
5963170
Compare
28c0d45 to
af2969e
Compare
There was a problem hiding this comment.
Pull request overview
Adds support for emitting certain Web Vitals as streamed (v2 pipeline) spans when traceLifecycle: 'stream' / span streaming is enabled, while keeping existing pageload measurements in place.
Changes:
- Gate standalone CLS/LCP spans off when span streaming is enabled, and wire up streamed LCP/CLS/INP emission from the browser tracing integration.
- Introduce
webVitalSpans.tshelpers + unit tests for emitting streamed Web Vital spans. - Add Playwright integration tests for streamed LCP and CLS spans; export
INP_ENTRY_MAP; add (currently-unused) FCP metric instrumentation.
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/browser/src/tracing/browserTracingIntegration.ts | Enables streamed Web Vital span tracking when span streaming is enabled; disables standalone CLS/LCP in that mode |
| packages/browser-utils/src/metrics/webVitalSpans.ts | Implements streamed span emitters for LCP/CLS/INP |
| packages/browser-utils/test/metrics/webVitalSpans.test.ts | Unit tests for streamed web vital span emission helpers |
| packages/browser-utils/src/metrics/instrument.ts | Adds FCP metric instrumentation plumbing (fcp observer + handler) |
| packages/browser-utils/src/metrics/inp.ts | Exports INP_ENTRY_MAP for reuse by streamed INP span logic |
| packages/browser-utils/src/index.ts | Re-exports streamed web vital span trackers from browser-utils |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-lcp-streamed-spans/test.ts | Playwright test validating streamed LCP span + attributes |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-lcp-streamed-spans/template.html | Test page for streamed LCP |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-lcp-streamed-spans/init.js | Initializes SDK with span streaming enabled for LCP test |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-lcp-streamed-spans/assets/sentry-logo-600x179.png | Asset used to trigger LCP |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-cls-streamed-spans/test.ts | Playwright test validating streamed CLS span + attributes |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-cls-streamed-spans/template.html | Test page for streamed CLS |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-cls-streamed-spans/subject.js | Simulates CLS for the CLS streamed span test |
| dev-packages/browser-integration-tests/suites/tracing/metrics/web-vitals-cls-streamed-spans/init.js | Initializes SDK with span streaming enabled for CLS test |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
d764f2e to
b80ddd4
Compare
a74fec7 to
7206304
Compare
...kages/browser-integration-tests/suites/tracing/metrics/web-vitals-cls-streamed-spans/test.ts
Show resolved
Hide resolved
86d1929 to
4bf129b
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
There are 2 total unresolved issues (including 1 from previous review).
Autofix Details
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: Redundant CLS/LCP tracking when streaming is enabled
- Added recordClsOnPageloadSpan and recordLcpOnPageloadSpan parameters to startTrackingWebVitals to prevent redundant handler registration when span streaming is enabled, eliminating the double-handler issue where one handler did throwaway work.
Or push these changes by commenting:
@cursor push d3ccbaa211
Preview (d3ccbaa211)
diff --git a/packages/browser-utils/src/metrics/browserMetrics.ts b/packages/browser-utils/src/metrics/browserMetrics.ts
--- a/packages/browser-utils/src/metrics/browserMetrics.ts
+++ b/packages/browser-utils/src/metrics/browserMetrics.ts
@@ -77,6 +77,8 @@
interface StartTrackingWebVitalsOptions {
recordClsStandaloneSpans: boolean;
recordLcpStandaloneSpans: boolean;
+ recordClsOnPageloadSpan?: boolean;
+ recordLcpOnPageloadSpan?: boolean;
client: Client;
}
@@ -89,6 +91,8 @@
export function startTrackingWebVitals({
recordClsStandaloneSpans,
recordLcpStandaloneSpans,
+ recordClsOnPageloadSpan = true,
+ recordLcpOnPageloadSpan = true,
client,
}: StartTrackingWebVitalsOptions): () => void {
const performance = getBrowserPerformanceAPI();
@@ -97,10 +101,22 @@
if (performance.mark) {
WINDOW.performance.mark('sentry-tracing-init');
}
- const lcpCleanupCallback = recordLcpStandaloneSpans ? trackLcpAsStandaloneSpan(client) : _trackLCP();
+ let lcpCleanupCallback: (() => void) | undefined;
+ if (recordLcpStandaloneSpans) {
+ trackLcpAsStandaloneSpan(client);
+ } else if (recordLcpOnPageloadSpan) {
+ lcpCleanupCallback = _trackLCP();
+ }
+
const ttfbCleanupCallback = _trackTtfb();
- const clsCleanupCallback = recordClsStandaloneSpans ? trackClsAsStandaloneSpan(client) : _trackCLS();
+ let clsCleanupCallback: (() => void) | undefined;
+ if (recordClsStandaloneSpans) {
+ trackClsAsStandaloneSpan(client);
+ } else if (recordClsOnPageloadSpan) {
+ clsCleanupCallback = _trackCLS();
+ }
+
return (): void => {
lcpCleanupCallback?.();
ttfbCleanupCallback();
diff --git a/packages/browser/src/tracing/browserTracingIntegration.ts b/packages/browser/src/tracing/browserTracingIntegration.ts
--- a/packages/browser/src/tracing/browserTracingIntegration.ts
+++ b/packages/browser/src/tracing/browserTracingIntegration.ts
@@ -519,6 +519,8 @@
_collectWebVitals = startTrackingWebVitals({
recordClsStandaloneSpans: !spanStreamingEnabled && (enableStandaloneClsSpans || false),
recordLcpStandaloneSpans: !spanStreamingEnabled && (enableStandaloneLcpSpans || false),
+ recordClsOnPageloadSpan: !spanStreamingEnabled,
+ recordLcpOnPageloadSpan: !spanStreamingEnabled,
client,
});This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
This PR adds span JSON conversion and serialization helpers for span streaming: * `spanToStreamedSpanJSON`: Converts a `Span` instance to a JSON object used as intermediate representation as outlined in #19100 * Adds `SentrySpan::getStreamedSpanJSON` method to convert our own spans * Directly converts any OTel spans * This is analogous to how `spanToJSON` works today. * `spanJsonToSerializedSpan`: Converts a `StreamedSpanJSON` into the final `SerializedSpan` to be sent to Sentry. This PR also adds unit tests for both helpers. ref #17836 --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Jan Peer Stöcklmair <jan.peer@sentry.io>
This PR adds the `captureSpan` pipeline, which takes a `Span` instance, processes it and ultimately returns a `SerializedStreamedSpan` which can then be enqueued into the span buffer. ref #17836
This PR adds a simple span buffer implementation to be used for buffering streamed spans. Behaviour: - buckets incoming spans by `traceId`, as we must not mix up spans of different traces in one envelope - flushes the entire buffer every 5s by default - flushes the specific trace bucket if the max span limit (1000) is reached. Relay accepts at max. 1000 spans per envelope - computes the DSC when flushing the first span of a trace. This is the latest time we can do it as once we flushed we have to freeze the DSC for Dynamic Sampling consistency - debounces the flush interval whenever we flush - flushes the entire buffer if `Sentry.flush()` is called - shuts down the interval-based flushing when `Sentry.close()` is called - [implicit] Client report generation for dropped envelopes is handled in the transport Methods: - `add` accepts a new span to be enqueued into the buffer - `drain` flushes the entire buffer - `flush(traceId)` flushes a specific traceId bucket. This can be used by e.g. the browser span streaming implementation to flush out the trace of a segment span directly once it ends. Options: - `maxSpanLimit` - allows to configure a 0 < maxSpanLimit < 1000 custom span limit. Useful for testing but we could also expose this to users if we see a need - `flushInterval`- allows to configure a >0 flush interval Limitations/edge cases: - No maximum limit of concurrently buffered traces. I'd tend to accept this for now and see where this leads us in terms of memory pressure but at the end of the day, the interval based flushing, in combination with our promise buffer _should_ avoid an ever-growing map of trace buckets. Happy to change this if reviewers have strong opinions or I'm missing something important! - There's no priority based scheduling relative to other telemetry items. Just like with our other log and metric buffers. - since `Map` is [insertion order preserving](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#description), we apply a FIFO strategy when`drain`ing the trace buckets. This is in line with our [develop spec](https://develop.sentry.dev/sdk/telemetry/telemetry-processor/backend-telemetry-processor/#:~:text=The%20span%20buffer,in%20the%20buffer.) for the telemetry processor but might lead to cases where new traces are dropped by the promise buffer if a lof of concurrently running traces are flushed. I think that's a fine trade off. ref #19119
This PR adds the final big building block for span streaming functionality in the browser SDK: `spanStreamingIntegation`. This integration: - enables `traceLifecycle: 'stream'` if not already set by users. This allows us to avoid the double-opt-in problem we usually have in browser SDKs because we want to keep integration tree-shakeable but also support the runtime-agnostic `traceLifecycle` option. - to do this properly, I decided to introduce a new integration hook: `beforeSetup`. This is allows us to safely modify client options before other integrations read it. We'll need this because `browserTracingIntegration` needs to check for span streaming later on. Let me know what you think! - validates that `beforeSendSpan` is compatible with span streaming. If not, it falls back to static tracing (transactions). - listens to a new `afterSpanEnd` hook. Once called, it will capture the span and hand it off to the span buffer. - listens to a new `afterSegmentSpanEnd` hook. Once called it will flush the trace from the buffer to ensure we flush out the trace as soon as possible. In browser, it's more likely that users refresh or close the tab/window before our buffer's internal flush interval triggers. We don't _have_ to do this but I figured it would be a good trigger point. While "final building block" sounds nice, there's still a lot of stuff to take care of in the browser. But with this in place we can also start integration-testing the browser SDKs. ref #17836 --------- Co-authored-by: Jan Peer Stöcklmair <jan.peer@sentry.io>
Adds weight-based flushing and span size estimation to the span buffer. Behaviour: - tracks weight independently per trace - weight estimation follows the same strategy we use for logs and metrics. I optimized the calculation, adding fixed sizes for as many fields as possible. Only span name, attributes and links are computed dynamically, with the same assumptions and considerations as in logs and metrics. - My tests show that the size estimation roughly compares to factor 0.8 to 1.2 to the real sizes, depending on data on spans (no, few, many, primitive, array attributes and links, etc.) - For now, the limit is set to 5MB which is half of the 10MB Relay accepts for span envelopes.
This PR adds browser integration to test testing span streaming: - Added test helpers: - `waitForStreamedSpan`: Returns a promise of a single matching span - `waitForStreamedSpans`: Returns a promise of all spans in an array whenever the callback returns true - `waitForStreamedSpanEnvelope`: Returns an entire streamed span (v2) envelope (including headers) - `observeStreamedSpan`: Can be used to observe sent span envelopes without blocking the test if no envelopes are sent (good for testing that spans are _not_ sent) - `getSpanOp`: Small helper to easily get the op of a span which we almost always need for the `waitFor*` function callbacks Added 50+ tests, mostly converted from transaction integration tests around spans from `browserTracingIntegration`: - tests asserting the entire span v2 envelope payloads of manually started, pageload and navigation span trees - tests for trace linking and trace lifetime - tests for spans coming from browserTracingIntegration (fetch, xhr, long animation frame, long tasks) Also, this PR fixes two bugs discovered through tests: - negatively sampled spans were still sent (because non-recording spans go through the same span life cycle) - cancelled spans received status `error` instead of `ok`. We want them to have status `ok` but an attribute detailing the cancellation reason. Lastly, I discovered a problem with timing data on fetch and XHR spans. Will try to fix as a follow-up. Tracked in #19613 ref #17836
…spans (#19643) This PR fixes a temporary bug in span streaming where we didn't add Http timing attributes (see #19613). We can fix this by following OTels approach: - delay the ending of `http.client` spans until either 300ms pass by or we receive the PerformanceResourceTiming entry with the respective timing information. Of course we end the span with the original timestamp then. - Unfortunately, we can only do this for streamed span because transaction-based spans cannot stay open longer than their parent (e.g. a pageload or navigation). Otherwise they'd get dropped. So we have to differentiate between the two modes here (RIP bundle size 😢) - To ensure we don't flush unnecessarily often, we also now delay flushing the span buffer for 500ms after a segment span ends. This slightly changed test semantics in a few integration tests because manually consecutively segments are now also sent in one envelope. This is completely fine (actually preferred) because we flush less often (i.e. fewer requests). closes #19613
…19741) This PR adds a server-side span streaming implementation, for now scoped to POtel SDKs. However we can reuse some stuff from this PR to very easily enable span streaming on Cloudflare, Vercel Edge and other OTel-less platforms. Main changes: - added `spanStreamingIntegration` to `@sentry/core`: This orchestrates the span streaming life cycle via the client and the span buffer. It's very similar to the already existing `spanStreamingIntegration` in browser but doesn't expose some of the behaviour that we need only in browser. - adjusted `SentrySpanProcessor` to emit the right client hooks instead of passing the span to the `SpanExporter`. - adjusted the SDKs' default integrations to include `spanStreamingIntegration` when users set `traceLifecycle: 'stream'` in their SDK init. Rest are tests and small refactors. I'll follow up with Node integration tests once this is merged to avoid bloating this PR further. ref #17836
Extends our Node (core) integration test runner API to expect `span` envelopes with both an API to test against span envelope headers as well as the container. In addition, this adds a couple of integration tests testing manually started spans, span name updates and span relationships. Luckily, all of the span relationship logic is independent from span streaming so the tests all pass. I still believe it's valuable to have a `span` version of them.
This PR Implements applying the `ignoreSpans` option to streamed spans (previously this option had no effect). It covers both, our core/browser- as well as the OTel/Node-based implementation. See PR for details
8613474 to
e360c3b
Compare
…NTRY_MAP Add `addFcpInstrumentationHandler` using the existing `onFCP` web-vitals library integration, following the same pattern as the other metric handlers. Export `INP_ENTRY_MAP` from inp.ts for reuse in the new web vital spans module. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…is enabled Add non-standalone web vital spans that flow through the v2 span streaming pipeline (afterSpanEnd -> captureSpan -> SpanBuffer). Each web vital gets `browser.web_vital.<metric>.value` attributes and span events for measurement extraction. Spans have meaningful durations showing time from navigation start to the web vital event (except CLS which is a score, not a duration). New tracking functions: trackLcpAsSpan, trackClsAsSpan, trackInpAsSpan, trackTtfbAsSpan, trackFcpAsSpan, trackFpAsSpan — wired up in browserTracingIntegration.setup() when hasSpanStreamingEnabled(client). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add Playwright integration tests verifying CLS, LCP, FCP, FP, and TTFB are emitted as streamed spans with correct attributes, value attributes, and meaningful durations when span streaming is enabled. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…dalone spans when streaming TTFB, FCP, and FP should remain as attributes on the pageload span rather than separate streamed spans. Also ensures standalone CLS/LCP spans are disabled when span streaming is enabled to prevent duplicate spans. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…an path The standalone INP handler filters out unrealistically long INP values (>60s) but the streamed span path was missing this sanity check. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Gate standalone INP (`startTrackingINP`) behind `!spanStreamingEnabled` and gate streamed INP (`trackInpAsSpan`) behind `enableInp` so both paths respect the user's preference and don't produce duplicate data. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove `addFcpInstrumentationHandler`, `instrumentFcp`, and `_previousFcp` which were added to support FCP streamed spans but are no longer called after FCP spans were removed from the implementation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…_sendInpSpan Use `|| 0` fallback instead of `as number` cast, consistent with the LCP and CLS span handlers that already guard against undefined. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…cpSpan Avoid calling browserPerformanceTimeOrigin() twice by caching the result in a local variable. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…nabled The streamed INP path does not use INTERACTIONS_SPAN_MAP or ELEMENT_NAME_TIMESTAMP_MAP, so registering the listeners is unnecessary overhead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When span streaming is enabled, CLS and LCP are emitted as streamed spans. Previously they were also recorded as measurements on the pageload span because the flags only checked enableStandaloneClsSpans and enableStandaloneLcpSpans, which default to undefined. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
… handlers Export the constant from inp.ts and import it in webVitalSpans.ts to avoid the two definitions drifting apart. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…Setup spanStreamingEnabled was declared in setup() but referenced in afterAllSetup(), a separate scope. Replace with inline hasSpanStreamingEnabled(client) call. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…enabled When span streaming handles CLS/LCP, `startTrackingWebVitals` no longer registers throwaway `_trackCLS()`/`_trackLCP()` handlers. Instead of adding a separate skip flag, the existing `recordClsStandaloneSpans` and `recordLcpStandaloneSpans` options now accept `undefined` to mean "skip entirely" — three states via two flags instead of three flags. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1417584 to
b94c3b3
Compare
Lms24
left a comment
There was a problem hiding this comment.
Still had some final questions but most of it LGTM!
| span.addEvent(metricName, { | ||
| [SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_UNIT]: unit, | ||
| [SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_VALUE]: value, | ||
| }); | ||
|
|
There was a problem hiding this comment.
l: This code path is only used for v2 spans, correct? In this case, we can remove the addEvent call (it no-ops for v2 spans)
| span.addEvent(metricName, { | |
| [SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_UNIT]: unit, | |
| [SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_VALUE]: value, | |
| }); |
| [`browser.web_vital.${metricName}.value`]: value, | ||
| transaction: routeName, |
There was a problem hiding this comment.
(Still need to double-check with Michi): I tested this and we still need to send the short lcp attributes so that the web vital pills and and lines show up. Let me check if we actually do this or if we don't on purpose and let the data browsing team fix the pipeline
| [`browser.web_vital.${metricName}.value`]: value, | |
| transaction: routeName, | |
| [`browser.web_vital.${metricName}.value`]: value, | |
| [metricName]: value, | |
| transaction: routeName, |
| sentryTest('captures CLS as a streamed span with source attributes', async ({ getLocalTestUrl, page }) => { | ||
| const url = await getLocalTestUrl({ testDir: __dirname }); | ||
|
|
||
| const clsSpanPromise = waitForStreamedSpan(page, span => getSpanOp(span) === 'ui.webvital.cls'); |
There was a problem hiding this comment.
l: can we also wait on the pageload span and assert that both have the same traceId? same for the LCP test
| /** | ||
| * Tracks INP as a streamed span. | ||
| */ | ||
| export function trackInpAsSpan(_client: Client): void { |
There was a problem hiding this comment.
m: I might be missing something but it seems like the INP logic isn't the same as the _onInp callback for v1 standalone INP spans
e360c3b to
595985b
Compare

Summary
Closes #17931
When span streaming is enabled (
traceLifecycle: 'stream'), emit web vital values as non-standalone spans that flow through the v2 pipeline (afterSpanEnd→captureSpan()→SpanBuffer).Only LCP, CLS, and INP are emitted as streamed spans — TTFB, FCP, and FP remain as attributes on the pageload span. When span streaming is enabled, standalone v1 CLS/LCP spans are automatically disabled to prevent duplicates.
Each web vital span carries
browser.web_vital.*attributes per sentry-conventions PRs 229, 233-235:browser.web_vital.lcp.{value,element,id,url,size,load_time,render_time}browser.web_vital.cls.{value,source.<N>}browser.web_vital.inp.value(with MAX_PLAUSIBLE_INP_DURATION sanity check)Spans have meaningful durations (navigation start → event time) instead of being point-in-time, except CLS which is a score.
Changes
hasSpanStreamingEnabled(client)is true!spanStreamingEnabled && enableStandaloneClsSpans)MAX_PLAUSIBLE_INP_DURATION(60s) sanity check to streamed INP path, matching the existing standalone handler🤖 Generated with Claude Code