@sentry-internal/browser-utils - npm Package Compare versions

Comparing version 8.25.0 to 8.26.0

build/cjs/metrics/browserMetrics.js

@@ -7,2 +7,3 @@ Object.defineProperty(exports, '__esModule', { value: true });
 const types = require('../types.js');
+const cls = require('./cls.js');
 const instrument = require('./instrument.js');
@@ -29,3 +30,3 @@ const utils = require('./utils.js');
  */
-function startTrackingWebVitals() {
+function startTrackingWebVitals({ recordClsStandaloneSpans }) {
   const performance = utils.getBrowserPerformanceAPI();
@@ -37,12 +38,12 @@ if (performance && utils$1.browserPerformanceTimeOrigin) {
     }
-    const fidCallback = _trackFID();
-    const clsCallback = _trackCLS();
-    const lcpCallback = _trackLCP();
-    const ttfbCallback = _trackTtfb();
+    const fidCleanupCallback = _trackFID();
+    const lcpCleanupCallback = _trackLCP();
+    const ttfbCleanupCallback = _trackTtfb();
+    const clsCleanupCallback = recordClsStandaloneSpans ? cls.trackClsAsStandaloneSpan() : _trackCLS();
 
     return () => {
-      fidCallback();
-      clsCallback();
-      lcpCallback();
-      ttfbCallback();
+      fidCleanupCallback();
+      lcpCleanupCallback();
+      ttfbCleanupCallback();
+      clsCleanupCallback && clsCleanupCallback();
     };
@@ -169,13 +170,15 @@ }
 
-/** Starts tracking the Cumulative Layout Shift on the current page. */
+/**
+ * Starts tracking the Cumulative Layout Shift on the current page and collects the value and last entry
+ * to the `_measurements` object which ultimately is applied to the pageload span's measurements.
+ */
 function _trackCLS() {
   return instrument.addClsInstrumentationHandler(({ metric }) => {
-    const entry = metric.entries[metric.entries.length - 1];
+    const entry = metric.entries[metric.entries.length - 1] ;
     if (!entry) {
       return;
     }
-
-    debugBuild.DEBUG_BUILD && utils$1.logger.log('[Measurements] Adding CLS');
+    debugBuild.DEBUG_BUILD && utils$1.logger.log(`[Measurements] Adding CLS ${metric.value}`);
     _measurements['cls'] = { value: metric.value, unit: '' };
-    _clsEntry = entry ;
+    _clsEntry = entry;
   }, true);
@@ -227,3 +230,3 @@ }
 /** Add performance related spans to a transaction */
-function addPerformanceEntries(span) {
+function addPerformanceEntries(span, options) {
   const performance = utils.getBrowserPerformanceAPI();
@@ -246,3 +249,3 @@ if (!performance || !types.WINDOW.performance.getEntries || !utils$1.browserPerformanceTimeOrigin) {
     const duration = utils.msToSec(
-      // Inexplicibly, Chrome sometimes emits a negative duration. We need to work around this.
+      // Inexplicably, Chrome sometimes emits a negative duration. We need to work around this.
       // There is a SO post attempting to explain this, but it leaves one with open questions: https://stackoverflow.com/questions/23191918/peformance-getentries-and-negative-duration-display
@@ -335,3 +338,4 @@ // The way we clamp the value is probably not accurate, since we have observed this happen for things that may take a while to load, like for example the replay worker.
     // according to the new definition of CLS.
-    if (!('fcp' in _measurements)) {
+    // TODO: Check if the first condition is still necessary: `onCLS` already only fires once `onFCP` was called.
+    if (!('fcp' in _measurements) || !options.recordClsOnPageloadSpan) {
       delete _measurements.cls;
@@ -338,0 +342,0 @@ }

build/cjs/metrics/inp.js

@@ -0,1 +1,5 @@
+var {
+  _optionalChain
+} = require('@sentry/utils');
+
 Object.defineProperty(exports, '__esModule', { value: true });
@@ -5,3 +9,2 @@
 const utils$1 = require('@sentry/utils');
-const types = require('../types.js');
 const instrument = require('./instrument.js');
@@ -61,4 +64,3 @@ const utils = require('./utils.js');
   return instrument.addInpInstrumentationHandler(({ metric }) => {
-    const client = core.getClient();
-    if (!client || metric.value == undefined) {
+    if (metric.value == undefined) {
       return;
@@ -76,7 +78,5 @@ }
 
-    const options = client.getOptions();
     /** Build the INP span, create an envelope from the span, and then send the envelope */
     const startTime = utils.msToSec((utils$1.browserPerformanceTimeOrigin ) + entry.startTime);
     const duration = utils.msToSec(metric.value);
-    const scope = core.getCurrentScope();
     const activeSpan = core.getActiveSpan();
@@ -93,52 +93,24 @@ const rootSpan = activeSpan ? core.getRootSpan(activeSpan) : undefined;
     // Finally, we fall back to look at the transactionName on the scope
-    const routeName = spanToUse ? core.spanToJSON(spanToUse).description : scope.getScopeData().transactionName;
+    const routeName = spanToUse ? core.spanToJSON(spanToUse).description : core.getCurrentScope().getScopeData().transactionName;
 
-    const user = scope.getUser();
-
-    // We need to get the replay, user, and activeTransaction from the current scope
-    // so that we can associate replay id, profile id, and a user display to the span
-    const replay = client.getIntegrationByName('Replay');
-
-    const replayId = replay && replay.getReplayId();
-
-    const userDisplay = user !== undefined ? user.email || user.id || user.ip_address : undefined;
-    let profileId = undefined;
-    try {
-      // @ts-expect-error skip optional chaining to save bundle size with try catch
-      profileId = scope.getScopeData().contexts.profile.profile_id;
-    } catch (e) {
-      // do nothing
-    }
-
     const name = utils$1.htmlTreeAsString(entry.target);
     const attributes = utils$1.dropUndefinedKeys({
-      release: options.release,
-      environment: options.environment,
-      transaction: routeName,
-      [core.SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: metric.value,
       [core.SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.http.browser.inp',
-      user: userDisplay || undefined,
-      profile_id: profileId || undefined,
-      replay_id: replayId || undefined,
-      // INP score calculation in the sentry backend relies on the user agent
-      // to account for different INP values being reported from different browsers
-      'user_agent.original': types.WINDOW.navigator && types.WINDOW.navigator.userAgent,
+      [core.SEMANTIC_ATTRIBUTE_SENTRY_OP]: `ui.interaction.${interactionType}`,
+      [core.SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: entry.duration,
     });
 
-    const span = core.startInactiveSpan({
+    const span = utils.startStandaloneWebVitalSpan({
       name,
-      op: `ui.interaction.${interactionType}`,
+      transaction: routeName,
       attributes,
-      startTime: startTime,
-      experimental: {
-        standalone: true,
-      },
+      startTime,
     });
 
-    span.addEvent('inp', {
+    _optionalChain([span, 'optionalAccess', _ => _.addEvent, 'call', _2 => _2('inp', {
       [core.SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_UNIT]: 'millisecond',
       [core.SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_VALUE]: metric.value,
-    });
+    })]);
 
-    span.end(startTime + duration);
+    _optionalChain([span, 'optionalAccess', _3 => _3.end, 'call', _4 => _4(startTime + duration)]);
   });
@@ -145,0 +117,0 @@ }

build/cjs/metrics/utils.js

@@ -47,2 +47,73 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
+/**
+ * Starts an inactive, standalone span used to send web vital values to Sentry.
+ * DO NOT use this for arbitrary spans, as these spans require special handling
+ * during ingestion to extract metrics.
+ *
+ * This function adds a bunch of attributes and data to the span that's shared
+ * by all web vital standalone spans. However, you need to take care of adding
+ * the actual web vital value as an event to the span. Also, you need to assign
+ * a transaction name and some other values that are specific to the web vital.
+ *
+ * Ultimately, you also need to take care of ending the span to send it off.
+ *
+ * @param options
+ *
+ * @returns an inactive, standalone and NOT YET ended span
+ */
+function startStandaloneWebVitalSpan(options) {
+  const client = core.getClient();
+  if (!client) {
+    return;
+  }
+
+  const { name, transaction, attributes: passedAttributes, startTime } = options;
+
+  const { release, environment } = client.getOptions();
+  // We need to get the replay, user, and activeTransaction from the current scope
+  // so that we can associate replay id, profile id, and a user display to the span
+  const replay = client.getIntegrationByName('Replay');
+  const replayId = replay && replay.getReplayId();
+
+  const scope = core.getCurrentScope();
+
+  const user = scope.getUser();
+  const userDisplay = user !== undefined ? user.email || user.id || user.ip_address : undefined;
+
+  let profileId = undefined;
+  try {
+    // @ts-expect-error skip optional chaining to save bundle size with try catch
+    profileId = scope.getScopeData().contexts.profile.profile_id;
+  } catch (e) {
+    // do nothing
+  }
+
+  const attributes = {
+    release,
+    environment,
+
+    user: userDisplay || undefined,
+    profile_id: profileId || undefined,
+    replay_id: replayId || undefined,
+
+    transaction,
+
+    // Web vital score calculation relies on the user agent to account for different
+    // browsers setting different thresholds for what is considered a good/meh/bad value.
+    // For example: Chrome vs. Chrome Mobile
+    'user_agent.original': types.WINDOW.navigator && types.WINDOW.navigator.userAgent,
+
+    ...passedAttributes,
+  };
+
+  return core.startInactiveSpan({
+    name,
+    attributes,
+    startTime,
+    experimental: {
+      standalone: true,
+    },
+  });
+}
+
 /** Get the browser performance API. */
@@ -66,2 +137,3 @@ function getBrowserPerformanceAPI() {
 exports.startAndEndSpan = startAndEndSpan;
+exports.startStandaloneWebVitalSpan = startStandaloneWebVitalSpan;
 //# sourceMappingURL=utils.js.map

build/esm/metrics/browserMetrics.js

@@ -5,2 +5,3 @@ import { getActiveSpan, startInactiveSpan, spanToJSON, setMeasurement, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import { WINDOW } from '../types.js';
+import { trackClsAsStandaloneSpan } from './cls.js';
 import { addPerformanceInstrumentationHandler, addClsInstrumentationHandler, addLcpInstrumentationHandler, addFidInstrumentationHandler, addTtfbInstrumentationHandler } from './instrument.js';
@@ -27,3 +28,3 @@ import { getBrowserPerformanceAPI, msToSec, startAndEndSpan, isMeasurementValue } from './utils.js';
  */
-function startTrackingWebVitals() {
+function startTrackingWebVitals({ recordClsStandaloneSpans }) {
   const performance = getBrowserPerformanceAPI();
@@ -35,12 +36,12 @@ if (performance && browserPerformanceTimeOrigin) {
     }
-    const fidCallback = _trackFID();
-    const clsCallback = _trackCLS();
-    const lcpCallback = _trackLCP();
-    const ttfbCallback = _trackTtfb();
+    const fidCleanupCallback = _trackFID();
+    const lcpCleanupCallback = _trackLCP();
+    const ttfbCleanupCallback = _trackTtfb();
+    const clsCleanupCallback = recordClsStandaloneSpans ? trackClsAsStandaloneSpan() : _trackCLS();
 
     return () => {
-      fidCallback();
-      clsCallback();
-      lcpCallback();
-      ttfbCallback();
+      fidCleanupCallback();
+      lcpCleanupCallback();
+      ttfbCleanupCallback();
+      clsCleanupCallback && clsCleanupCallback();
     };
@@ -167,13 +168,15 @@ }
 
-/** Starts tracking the Cumulative Layout Shift on the current page. */
+/**
+ * Starts tracking the Cumulative Layout Shift on the current page and collects the value and last entry
+ * to the `_measurements` object which ultimately is applied to the pageload span's measurements.
+ */
 function _trackCLS() {
   return addClsInstrumentationHandler(({ metric }) => {
-    const entry = metric.entries[metric.entries.length - 1];
+    const entry = metric.entries[metric.entries.length - 1] ;
     if (!entry) {
       return;
     }
-
-    DEBUG_BUILD && logger.log('[Measurements] Adding CLS');
+    DEBUG_BUILD && logger.log(`[Measurements] Adding CLS ${metric.value}`);
     _measurements['cls'] = { value: metric.value, unit: '' };
-    _clsEntry = entry ;
+    _clsEntry = entry;
   }, true);
@@ -225,3 +228,3 @@ }
 /** Add performance related spans to a transaction */
-function addPerformanceEntries(span) {
+function addPerformanceEntries(span, options) {
   const performance = getBrowserPerformanceAPI();
@@ -244,3 +247,3 @@ if (!performance || !WINDOW.performance.getEntries || !browserPerformanceTimeOrigin) {
     const duration = msToSec(
-      // Inexplicibly, Chrome sometimes emits a negative duration. We need to work around this.
+      // Inexplicably, Chrome sometimes emits a negative duration. We need to work around this.
       // There is a SO post attempting to explain this, but it leaves one with open questions: https://stackoverflow.com/questions/23191918/peformance-getentries-and-negative-duration-display
@@ -333,3 +336,4 @@ // The way we clamp the value is probably not accurate, since we have observed this happen for things that may take a while to load, like for example the replay worker.
     // according to the new definition of CLS.
-    if (!('fcp' in _measurements)) {
+    // TODO: Check if the first condition is still necessary: `onCLS` already only fires once `onFCP` was called.
+    if (!('fcp' in _measurements) || !options.recordClsOnPageloadSpan) {
       delete _measurements.cls;
@@ -336,0 +340,0 @@ }

build/esm/metrics/inp.js

@@ -1,6 +0,6 @@
-import { getClient, getCurrentScope, getActiveSpan, getRootSpan, spanToJSON, SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startInactiveSpan, SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_UNIT, SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_VALUE } from '@sentry/core';
+import { _optionalChain } from '@sentry/utils';
+import { getActiveSpan, getRootSpan, spanToJSON, getCurrentScope, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME, SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_UNIT, SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_VALUE } from '@sentry/core';
 import { browserPerformanceTimeOrigin, htmlTreeAsString, dropUndefinedKeys } from '@sentry/utils';
-import { WINDOW } from '../types.js';
 import { addInpInstrumentationHandler, addPerformanceInstrumentationHandler, isPerformanceEventTiming } from './instrument.js';
-import { getBrowserPerformanceAPI, msToSec } from './utils.js';
+import { getBrowserPerformanceAPI, msToSec, startStandaloneWebVitalSpan } from './utils.js';
 
@@ -58,4 +58,3 @@ const LAST_INTERACTIONS = [];
   return addInpInstrumentationHandler(({ metric }) => {
-    const client = getClient();
-    if (!client || metric.value == undefined) {
+    if (metric.value == undefined) {
       return;
@@ -73,7 +72,5 @@ }
 
-    const options = client.getOptions();
     /** Build the INP span, create an envelope from the span, and then send the envelope */
     const startTime = msToSec((browserPerformanceTimeOrigin ) + entry.startTime);
     const duration = msToSec(metric.value);
-    const scope = getCurrentScope();
     const activeSpan = getActiveSpan();
@@ -90,52 +87,24 @@ const rootSpan = activeSpan ? getRootSpan(activeSpan) : undefined;
     // Finally, we fall back to look at the transactionName on the scope
-    const routeName = spanToUse ? spanToJSON(spanToUse).description : scope.getScopeData().transactionName;
+    const routeName = spanToUse ? spanToJSON(spanToUse).description : getCurrentScope().getScopeData().transactionName;
 
-    const user = scope.getUser();
-
-    // We need to get the replay, user, and activeTransaction from the current scope
-    // so that we can associate replay id, profile id, and a user display to the span
-    const replay = client.getIntegrationByName('Replay');
-
-    const replayId = replay && replay.getReplayId();
-
-    const userDisplay = user !== undefined ? user.email || user.id || user.ip_address : undefined;
-    let profileId = undefined;
-    try {
-      // @ts-expect-error skip optional chaining to save bundle size with try catch
-      profileId = scope.getScopeData().contexts.profile.profile_id;
-    } catch (e) {
-      // do nothing
-    }
-
     const name = htmlTreeAsString(entry.target);
     const attributes = dropUndefinedKeys({
-      release: options.release,
-      environment: options.environment,
-      transaction: routeName,
-      [SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: metric.value,
       [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.http.browser.inp',
-      user: userDisplay || undefined,
-      profile_id: profileId || undefined,
-      replay_id: replayId || undefined,
-      // INP score calculation in the sentry backend relies on the user agent
-      // to account for different INP values being reported from different browsers
-      'user_agent.original': WINDOW.navigator && WINDOW.navigator.userAgent,
+      [SEMANTIC_ATTRIBUTE_SENTRY_OP]: `ui.interaction.${interactionType}`,
+      [SEMANTIC_ATTRIBUTE_EXCLUSIVE_TIME]: entry.duration,
     });
 
-    const span = startInactiveSpan({
+    const span = startStandaloneWebVitalSpan({
       name,
-      op: `ui.interaction.${interactionType}`,
+      transaction: routeName,
       attributes,
-      startTime: startTime,
-      experimental: {
-        standalone: true,
-      },
+      startTime,
     });
 
-    span.addEvent('inp', {
+    _optionalChain([span, 'optionalAccess', _ => _.addEvent, 'call', _2 => _2('inp', {
       [SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_UNIT]: 'millisecond',
       [SEMANTIC_ATTRIBUTE_SENTRY_MEASUREMENT_VALUE]: metric.value,
-    });
+    })]);
 
-    span.end(startTime + duration);
+    _optionalChain([span, 'optionalAccess', _3 => _3.end, 'call', _4 => _4(startTime + duration)]);
   });
@@ -142,0 +111,0 @@ }

build/esm/metrics/utils.js

@@ -1,2 +0,2 @@
-import { spanToJSON, withActiveSpan, startInactiveSpan } from '@sentry/core';
+import { spanToJSON, withActiveSpan, startInactiveSpan, getClient, getCurrentScope } from '@sentry/core';
 import { WINDOW } from '../types.js';
@@ -45,2 +45,73 @@
 
+/**
+ * Starts an inactive, standalone span used to send web vital values to Sentry.
+ * DO NOT use this for arbitrary spans, as these spans require special handling
+ * during ingestion to extract metrics.
+ *
+ * This function adds a bunch of attributes and data to the span that's shared
+ * by all web vital standalone spans. However, you need to take care of adding
+ * the actual web vital value as an event to the span. Also, you need to assign
+ * a transaction name and some other values that are specific to the web vital.
+ *
+ * Ultimately, you also need to take care of ending the span to send it off.
+ *
+ * @param options
+ *
+ * @returns an inactive, standalone and NOT YET ended span
+ */
+function startStandaloneWebVitalSpan(options) {
+  const client = getClient();
+  if (!client) {
+    return;
+  }
+
+  const { name, transaction, attributes: passedAttributes, startTime } = options;
+
+  const { release, environment } = client.getOptions();
+  // We need to get the replay, user, and activeTransaction from the current scope
+  // so that we can associate replay id, profile id, and a user display to the span
+  const replay = client.getIntegrationByName('Replay');
+  const replayId = replay && replay.getReplayId();
+
+  const scope = getCurrentScope();
+
+  const user = scope.getUser();
+  const userDisplay = user !== undefined ? user.email || user.id || user.ip_address : undefined;
+
+  let profileId = undefined;
+  try {
+    // @ts-expect-error skip optional chaining to save bundle size with try catch
+    profileId = scope.getScopeData().contexts.profile.profile_id;
+  } catch (e) {
+    // do nothing
+  }
+
+  const attributes = {
+    release,
+    environment,
+
+    user: userDisplay || undefined,
+    profile_id: profileId || undefined,
+    replay_id: replayId || undefined,
+
+    transaction,
+
+    // Web vital score calculation relies on the user agent to account for different
+    // browsers setting different thresholds for what is considered a good/meh/bad value.
+    // For example: Chrome vs. Chrome Mobile
+    'user_agent.original': WINDOW.navigator && WINDOW.navigator.userAgent,
+
+    ...passedAttributes,
+  };
+
+  return startInactiveSpan({
+    name,
+    attributes,
+    startTime,
+    experimental: {
+      standalone: true,
+    },
+  });
+}
+
 /** Get the browser performance API. */
@@ -60,3 +131,3 @@ function getBrowserPerformanceAPI() {
 
-export { getBrowserPerformanceAPI, isMeasurementValue, msToSec, startAndEndSpan };
+export { getBrowserPerformanceAPI, isMeasurementValue, msToSec, startAndEndSpan, startStandaloneWebVitalSpan };
 //# sourceMappingURL=utils.js.map

build/types-ts3.8/metrics/browserMetrics.d.ts

 import { Span } from '@sentry/types';
+interface StartTrackingWebVitalsOptions {
+    recordClsStandaloneSpans: boolean;
+}
 /**
@@ -8,3 +11,3 @@ * Start tracking web vitals.
  */
-export declare function startTrackingWebVitals(): () => void;
+export declare function startTrackingWebVitals({ recordClsStandaloneSpans }: StartTrackingWebVitalsOptions): () => void;
 /**
@@ -23,4 +26,11 @@ * Start tracking long tasks.
 export { startTrackingINP, registerInpInteractionListener } from './inp';
+interface AddPerformanceEntriesOptions {
+    /**
+     * Flag to determine if CLS should be recorded as a measurement on the span or
+     * sent as a standalone span instead.
+     */
+    recordClsOnPageloadSpan: boolean;
+}
 /** Add performance related spans to a transaction */
-export declare function addPerformanceEntries(span: Span): void;
+export declare function addPerformanceEntries(span: Span, options: AddPerformanceEntriesOptions): void;
 /** Create measure related spans */
@@ -27,0 +37,0 @@ export declare function _addMeasureSpans(span: Span, entry: Record<string, any>, startTime: number, duration: number, timeOrigin: number): number;

build/types-ts3.8/metrics/utils.d.ts

@@ -1,2 +0,2 @@
-import { Span, SpanTimeInput, StartSpanOptions } from '@sentry/types';
+import { Span, SpanAttributes, SpanTimeInput, StartSpanOptions } from '@sentry/types';
 /**
@@ -12,2 +12,25 @@ * Checks if a given value is a valid measurement value.
 export declare function startAndEndSpan(parentSpan: Span, startTimeInSeconds: number, endTime: SpanTimeInput, { ...ctx }: StartSpanOptions): Span | undefined;
+interface StandaloneWebVitalSpanOptions {
+    name: string;
+    transaction?: string;
+    attributes: SpanAttributes;
+    startTime: number;
+}
+/**
+ * Starts an inactive, standalone span used to send web vital values to Sentry.
+ * DO NOT use this for arbitrary spans, as these spans require special handling
+ * during ingestion to extract metrics.
+ *
+ * This function adds a bunch of attributes and data to the span that's shared
+ * by all web vital standalone spans. However, you need to take care of adding
+ * the actual web vital value as an event to the span. Also, you need to assign
+ * a transaction name and some other values that are specific to the web vital.
+ *
+ * Ultimately, you also need to take care of ending the span to send it off.
+ *
+ * @param options
+ *
+ * @returns an inactive, standalone and NOT YET ended span
+ */
+export declare function startStandaloneWebVitalSpan(options: StandaloneWebVitalSpanOptions): Span | undefined;
 /** Get the browser performance API. */
@@ -20,2 +43,3 @@ export declare function getBrowserPerformanceAPI(): Performance | undefined;
 export declare function msToSec(time: number): number;
+export {};
 //# sourceMappingURL=utils.d.ts.map

build/types/metrics/browserMetrics.d.ts

 import type { Span } from '@sentry/types';
+interface StartTrackingWebVitalsOptions {
+    recordClsStandaloneSpans: boolean;
+}
 /**
@@ -8,3 +11,3 @@ * Start tracking web vitals.
  */
-export declare function startTrackingWebVitals(): () => void;
+export declare function startTrackingWebVitals({ recordClsStandaloneSpans }: StartTrackingWebVitalsOptions): () => void;
 /**
@@ -23,4 +26,11 @@ * Start tracking long tasks.
 export { startTrackingINP, registerInpInteractionListener } from './inp';
+interface AddPerformanceEntriesOptions {
+    /**
+     * Flag to determine if CLS should be recorded as a measurement on the span or
+     * sent as a standalone span instead.
+     */
+    recordClsOnPageloadSpan: boolean;
+}
 /** Add performance related spans to a transaction */
-export declare function addPerformanceEntries(span: Span): void;
+export declare function addPerformanceEntries(span: Span, options: AddPerformanceEntriesOptions): void;
 /** Create measure related spans */
@@ -27,0 +37,0 @@ export declare function _addMeasureSpans(span: Span, entry: Record<string, any>, startTime: number, duration: number, timeOrigin: number): number;

build/types/metrics/utils.d.ts

@@ -1,2 +0,2 @@
-import type { Span, SpanTimeInput, StartSpanOptions } from '@sentry/types';
+import type { Span, SpanAttributes, SpanTimeInput, StartSpanOptions } from '@sentry/types';
 /**
@@ -12,2 +12,25 @@ * Checks if a given value is a valid measurement value.
 export declare function startAndEndSpan(parentSpan: Span, startTimeInSeconds: number, endTime: SpanTimeInput, { ...ctx }: StartSpanOptions): Span | undefined;
+interface StandaloneWebVitalSpanOptions {
+    name: string;
+    transaction?: string;
+    attributes: SpanAttributes;
+    startTime: number;
+}
+/**
+ * Starts an inactive, standalone span used to send web vital values to Sentry.
+ * DO NOT use this for arbitrary spans, as these spans require special handling
+ * during ingestion to extract metrics.
+ *
+ * This function adds a bunch of attributes and data to the span that's shared
+ * by all web vital standalone spans. However, you need to take care of adding
+ * the actual web vital value as an event to the span. Also, you need to assign
+ * a transaction name and some other values that are specific to the web vital.
+ *
+ * Ultimately, you also need to take care of ending the span to send it off.
+ *
+ * @param options
+ *
+ * @returns an inactive, standalone and NOT YET ended span
+ */
+export declare function startStandaloneWebVitalSpan(options: StandaloneWebVitalSpanOptions): Span | undefined;
 /** Get the browser performance API. */
@@ -20,2 +43,3 @@ export declare function getBrowserPerformanceAPI(): Performance | undefined;
 export declare function msToSec(time: number): number;
+export {};
 //# sourceMappingURL=utils.d.ts.map

package.json

 {
   "name": "@sentry-internal/browser-utils",
-  "version": "8.25.0",
+  "version": "8.26.0",
   "description": "Browser Utilities for all Sentry JavaScript SDKs",
@@ -42,5 +42,5 @@ "repository": "git://github.com/getsentry/sentry-javascript.git",
   "dependencies": {
-    "@sentry/core": "8.25.0",
-    "@sentry/types": "8.25.0",
-    "@sentry/utils": "8.25.0"
+    "@sentry/core": "8.26.0",
+    "@sentry/types": "8.26.0",
+    "@sentry/utils": "8.26.0"
   },
@@ -47,0 +47,0 @@ "scripts": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

743749

increased by12.27%

Number of package files

234

increased by3.08%

Lines of code

7441

increased by5.14%

Dependency changes

• + Added@sentry/core@8.26.0(transitive)

• + Added@sentry/types@8.26.0(transitive)

• + Added@sentry/utils@8.26.0(transitive)

• - Removed@sentry/core@8.25.0(transitive)

• - Removed@sentry/types@8.25.0(transitive)

• - Removed@sentry/utils@8.25.0(transitive)

• Updated@sentry/core@8.26.0

• Updated@sentry/types@8.26.0

• Updated@sentry/utils@8.26.0