From 8f6d73f6f41c720e0c16c7fc54c964aa102c1f41 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Fri, 27 Mar 2026 16:32:39 -0400 Subject: [PATCH 1/2] docs(js): Add elementTimingIntegration documentation Document the new standalone elementTimingIntegration that collects Element Timing API data as Sentry distribution metrics. This replaces the deprecated enableElementTiming option on browserTracingIntegration. Refs getsentry/sentry-javascript#19869 Co-Authored-By: Claude --- .../integrations/elementtiming.mdx | 104 ++++++++++++++++++ .../javascript/common/metrics/index.mdx | 8 ++ .../configuration/integrations/javascript.mdx | 3 +- 3 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx diff --git a/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx b/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx new file mode 100644 index 0000000000000..403aeb977360d --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx @@ -0,0 +1,104 @@ +--- +title: ElementTiming +description: "Collect Element Timing API data as Sentry metrics." +beta: true +notSupported: + - javascript.cordova + - javascript.capacitor + - javascript.node + - javascript.aws-lambda + - javascript.azure-functions + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.gcp-functions + - javascript.hapi + - javascript.hono + - javascript.koa + - javascript.nestjs + - javascript.deno + - javascript.cloudflare + - javascript.bun +--- + + + +This integration only works inside a browser environment. Requires SDK version `10.47.0` or higher. + + + +_Import name: `Sentry.elementTimingIntegration`_ + +The `elementTimingIntegration` collects render and load timing data from the browser's [Element Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceElementTiming) and emits it as [Sentry distribution metrics](/product/explore/metrics/). This lets you track how long key elements (hero images, text blocks, etc.) take to appear on screen. + + + +The Element Timing API is only supported in Chromium-based browsers (Chrome, Edge 77+). Firefox and Safari do not support it. The integration will silently do nothing in unsupported browsers. + + + +This integration requires [Sentry Metrics](./../../../metrics/) to be available in your Sentry organization. + +```javascript +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.elementTimingIntegration(), + ], +}); +``` + +## Marking Elements for Tracking + +Add the `elementtiming` HTML attribute to any element you want to track. The attribute value is used as the element's identifier in the emitted metrics. + +```html + +

Welcome to our site!

+``` + +Only elements with a non-empty `elementtiming` attribute will be tracked. + +## Emitted Metrics + +The integration emits two distribution metrics (in milliseconds): + +| Metric | Description | +| ------------------------ | ------------------------------------------------------------------------------ | +| `ui.element.render_time` | Time until the element was rendered. Emitted for both text and image elements. | +| `ui.element.load_time` | Time until the element's resource was loaded. Only emitted for image elements. | + +Both metrics include the following attributes: + +| Attribute | Description | +| ----------------------- | ------------------------------------------------ | +| `ui.element.identifier` | The value of the `elementtiming` HTML attribute. | +| `ui.element.paint_type` | `image-paint` or `text-paint`. | +| `ui.element.id` | The DOM element's `id` attribute, if set. | +| `ui.element.type` | The tag name (e.g., `img`, `p`). | +| `ui.element.url` | The image resource URL, if available. | +| `ui.element.width` | Natural width of the image, if available. | +| `ui.element.height` | Natural height of the image, if available. | + +## Migration from `enableElementTiming` + +The `enableElementTiming` option on `browserTracingIntegration` is deprecated and no longer has any effect. If you were using it, remove it and add the standalone `elementTimingIntegration` instead: + +```javascript +// Before +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration({ + enableElementTiming: true, // deprecated, no longer works + }), + ], +}); + +// After +Sentry.init({ + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.elementTimingIntegration(), + ], +}); +``` diff --git a/docs/platforms/javascript/common/metrics/index.mdx b/docs/platforms/javascript/common/metrics/index.mdx index 5b168996c19f3..b4862247849c8 100644 --- a/docs/platforms/javascript/common/metrics/index.mdx +++ b/docs/platforms/javascript/common/metrics/index.mdx @@ -39,6 +39,14 @@ With [Sentry Metrics](/product/explore/metrics/), you can send counters, gauges, +## Integrations + + + +- `elementTimingIntegration` — Automatically collect render and load timing distribution metrics for key UI elements using the browser's Element Timing API. + + + ## Related Features - Tracing — Drill down from metrics diff --git a/platform-includes/configuration/integrations/javascript.mdx b/platform-includes/configuration/integrations/javascript.mdx index 5540efe05a414..684bbcfc9e96d 100644 --- a/platform-includes/configuration/integrations/javascript.mdx +++ b/platform-includes/configuration/integrations/javascript.mdx @@ -1,7 +1,7 @@ ### Integrations | | **Auto Enabled** | **Errors** | **Tracing** | **Replay** | **Additional Context** | -|-------------------------------------------------------|:----------------:|:----------:|:-----------:|:----------:|:----------------------:| +| ----------------------------------------------------- | :--------------: | :--------: | :---------: | :--------: | :--------------------: | | [`breadcrumbsIntegration`](./breadcrumbs) | ✓ | | | | ✓ | | [`browserApiErrorsIntegration`](./browserapierrors) | ✓ | ✓ | | | | | [`browserSessionIntegration`](./browsersession) | ✓ | | | | ✓ | @@ -14,6 +14,7 @@ | [`anthropicAIIntegration`](./anthropic) | | | ✓ | | ✓ | | [`browserProfilingIntegration`](./browserprofiling) | | | ✓ | | | | [`browserTracingIntegration`](./browsertracing) | | | ✓ | | ✓ | +| [`elementTimingIntegration`](./elementtiming) | | | | | | | [`captureConsoleIntegration`](./captureconsole) | | ✓ | | | ✓ | | [`contextLinesIntegration`](./contextlines) | | ✓ | | | | | [`extraErrorDataIntegration`](./extraerrordata) | | | | | ✓ | From 0e49616e9fb1b89506388f2f123c5d96cc45378f Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Wed, 1 Apr 2026 09:20:27 -0400 Subject: [PATCH 2/2] docs(js): Address review feedback for elementTimingIntegration - Use PlatformLink for metrics link - Add description for paint_type attribute - Remove browserTracingIntegration from setup snippet (not required) Co-Authored-By: Claude Opus 4.6 (1M context) --- .../common/configuration/integrations/elementtiming.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx b/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx index 403aeb977360d..af40515ecfd60 100644 --- a/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx @@ -37,14 +37,11 @@ The Element Timing API is only supported in Chromium-based browsers (Chrome, Edg -This integration requires [Sentry Metrics](./../../../metrics/) to be available in your Sentry organization. +This integration requires Sentry Metrics to be available in your Sentry organization. ```javascript Sentry.init({ - integrations: [ - Sentry.browserTracingIntegration(), - Sentry.elementTimingIntegration(), - ], + integrations: [Sentry.elementTimingIntegration()], }); ``` @@ -73,7 +70,7 @@ Both metrics include the following attributes: | Attribute | Description | | ----------------------- | ------------------------------------------------ | | `ui.element.identifier` | The value of the `elementtiming` HTML attribute. | -| `ui.element.paint_type` | `image-paint` or `text-paint`. | +| `ui.element.paint_type` | The type of paint event: `image-paint` or `text-paint`. | | `ui.element.id` | The DOM element's `id` attribute, if set. | | `ui.element.type` | The tag name (e.g., `img`, `p`). | | `ui.element.url` | The image resource URL, if available. |