Web vitals & tracing

Core Web Vitals ($web_vitals) and distributed spans — options, APIs, and Insights surfaces.

Web vitals

Options

Option	Default	Meaning
`enableWebVitals`	`true`	Collect FCP, LCP, CLS, INP, TTFB via the web-vitals library path in the SDK

HumanBehaviorTracker.init(apiKey, {
  enableWebVitals: true,
});

Event shape

Each metric is emitted as a custom event named $web_vitals with properties such as:

Property	Example / meaning
`$web_vitals_metric`	`FCP` \| `LCP` \| `CLS` \| `INP` \| `TTFB`
`$web_vitals_value`	Numeric metric value
`$web_vitals_<METRIC>_value`	Per-metric alias (e.g. `$web_vitals_LCP_value`)
`$web_vitals_rating`	`good` \| `needs-improvement` \| `poor`
`$web_vitals_id`	Metric id from the library
`$web_vitals_navigation_type`	Navigation type
`$web_vitals_pageload_id`	Correlates metrics for one page load

Some metrics settle at page-hide; short sessions still respect the minimum-duration gate unless configured otherwise.

Product surface

Insights → Web Vitals

Tracing / spans

Options

Option	Default	Meaning
`enableTracing`	`true`	Page-load transaction, Navigation Timing phases, Resource Timing children, custom spans

Transport: POST /api/ingestion/spans/batch (beacon on unload when needed).

Automatic spans

When enabled, the SDK opens a root pageload trace and attaches:

Navigation phases (request / response / DOM)
Resource children (resource.script, resource.css, resource.img, http.client, …)
Shared W3C-style traceId; children reference parentSpanId
Outgoing same-origin requests may receive traceparent / sentry-trace headers for backend continuation

SDK-owned ingestion URLs are skipped via the same skip list as network tracking.

Custom spans

// Time a sync/async callback (no-op wrapper if tracing disabled)
const result = tracker.startSpan(
  { name: "checkout.compute", op: "function", attributes: { step: "tax" } },
  () => computeTax(),
);

// Manual span
const span = tracker.startInactiveSpan({ name: "checkout.pay", op: "ui.action" });
span.setAttribute("method", "card");
try {
  await pay();
  span.setStatus("ok");
} catch (e) {
  span.setStatus("error");
  throw e;
} finally {
  span.end();
}

API	Behavior
`startSpan({ name, op?, attributes? }, callback)`	Runs callback; returns its value; ends span automatically
`startInactiveSpan({ name, op?, attributes? })`	Returns `{ setAttribute, setStatus, end }`; no-op object if tracing off

Span status values: 'ok' | 'error' | 'cancelled'.

Product surface

Insights → Traces

Verify

Load pages under production-like conditions with vitals/tracing left on.
Open Insights → Web Vitals / Traces with a date range that includes traffic.
Network tab: confirm /api/ingestion/spans/batch and $web_vitals custom-event traffic.
Empty windows usually mean no traffic, capture disabled, or filters excluding the environment.

Web vitals & tracing

On this page