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..af40515ecfd60 --- /dev/null +++ b/docs/platforms/javascript/common/configuration/integrations/elementtiming.mdx @@ -0,0 +1,101 @@ +--- +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 to be available in your Sentry organization. + +```javascript +Sentry.init({ + integrations: [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` | 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. | +| `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) | | | | | ✓ |