Browser telemetry in forge frontends — the HyperDX SDK forge scaffolds and initialises (otel_gen.ts, SERVICE_NAME), the same-origin /_otel route and who forwards it, the env knobs, the cookieless analytics tiers (off < aggregate < identified < full; identified by default: nothing stored on the device, the signed-in user's opaque id on events; full only with mode full + grantAnalyticsConsent; optOutOfAnalytics; GPC/DNT caps at aggregate), automatic page views with referrer/utm/click_id, flag e...
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Telemetry?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/reliant-labs-telemetry-forge)
---
name: frontend-runtime/telemetry
description: Browser telemetry in forge frontends — the HyperDX SDK forge scaffolds and initialises (otel_gen.ts, SERVICE_NAME), the same-origin /_otel route and who forwards it, the env knobs, the cookieless analytics tiers (off < aggregate < identified < full; identified by default: nothing stored on the device, the signed-in user's opaque id on events; full only with mode full + grantAnalyticsConsent; optOutOfAnalytics; GPC/DNT caps at aggregate), automatic page views with referrer/utm/click_id, flag exposures, source maps extracted to a registry sidecar and never served, new-project replay on and always masked, reportException for caught errors, and interaction() spans timing a user operation from click to usable.
---
# Browser telemetry (HyperDX SDK)
Forge scaffolds, injects and initialises the **HyperDX browser SDK** in Next.js
and Vite frontends: `@hyperdx/otel-web`, which `@reliantlabs/forge-web-runtime`
carries as its own dependency and drives itself, with session replay recorded
by the runtime's own rrweb recorder. The app declares neither. It captures
uncaught errors and unhandled rejections, `console.*`, fetch/XHR spans, document
load, long tasks and web vitals, and ships them as OTLP to ClickStack. There is
no Sentry SDK and no Sentry-protocol adapter. React Native frontends get
nothing yet: there is no DOM to instrument and the browser SDK does not resolve
there.
You write none of the wiring. `src/lib/otel_gen.ts` (regenerated every
`forge generate`; do not edit) reads the env and calls
`initBrowserTelemetry` from `@reliantlabs/forge-web-runtime/telemetry`, and
`providers.tsx` (Next.js) / `main.tsx` (Vite) call its `initTelemetry()` once.
It is idempotent, a no-op without a DOM or while telemetry is off, and never
throws.
The frontend reports `service.name` `<project>-<frontend>` (e.g. `shop-web`),
exported from the same file as `SERVICE_NAME`. The generated frontend dashboard
and frontend alert defaults filter on exactly that value. Code that starts the
SDK itself instead of calling `initTelemetry()` must pass `SERVICE_NAME` as
`serviceName`: any other name is invisible to the generated observability. The SDK is the page's **only** tracer provider: it replaces the old
OTel web wiring rather than joining it, because two providers cannot both
register globally.
## Same-origin `/_otel`, and no secret in the bundle
The browser POSTs OTLP/HTTP to `<basePath>/_otel/v1/{traces,logs}` on its **own
origin**. Something in front of the page forwards that to a collector's OTLP/HTTP
port, and that hop owns any credential. The SDK insists on an `apiKey`, so it is
sent the public placeholder `forge-browser-public`; a collector that enforces
ingestion auth (ClickStack `collectorAuthenticationEnforced`) must have the proxy
strip that header or replace it with the real key. Same-origin also means a CSP
of `connect-src 'self'`, no CORS preflight, and no third-party host for an
ad-blocker to list.
| Where | Who routes `/_otel` | Upstream |
|---|---|---|
| `next dev` | a dev-only `rewrites()` in `next.config.ts` to the runtime's loopback relay (`startOtelRelay`) | `OTEL_EXPORTER_OTLP_ENDPOINT`, default `http://127.0.0.1:4318` |
| `vite` | the runtime's `forgeOtelProxy()` plugin in `vite.config.ts` | same; the `/_otel` prefix is stripped |
| deployed | **the ingress** | a collector's OTLP/HTTP port |
Both dev proxies come from `@reliantlabs/forge-web-runtime` and forward only a
same-origin page's `POST /v1/{traces,logs,metrics}` up to 8 MiB (403 for a
foreign or missing `Origin`, 405 for another method, 404 for another path, 413
above the cap, none of them sent upstream), with only its `content-type` and
`content-encoding`: never its cookies or `authorization`.
A Next.js frontend builds as a **static export** (`output: static`), which has no
server, so `rewrites` do not exist in the built site; a built Vite SPA is plain
files. In a deployed environment the ingress must route `<basePath>/_otel/*` to
the collector. Until it does, leave the frontend's `otel_endpoint` unset and the
production bundle sends nothing, rather than POSTing to a 404.
## Turning it on, and the knobs
A value that differs per environment is read from the runtime config document
(`config.js`): a build variable is inlined at build time and follows that bundle
into every environment it is promoted to.
| Knob | Runtime key (`config.js`) | Declared by | Default |
|---|---|---|---|
| ingest path (`off` or empty disables) | `OTEL_ENDPOINT` | KCL `config.otel_endpoint` or `runtime_config` | `/_otel` in dev and on `forge.OnHosted`, **empty elsewhere** |
| `deployment.environment` | `ENVIRONMENT` | KCL `config.environment` or `runtime_config` | the forge env name |
| product analytics mode, the tier ceiling (`off` / `aggregate` / `identified` / `full`) | `ANALYTICS_MODE` | KCL `telemetry = forge.BrowserTelemetry {analytics = forge.Analytics {mode = "full"}}` (per frontend, per env), or `runtime_config`; forced to `off` when the env switches browser telemetry off | `identified`: cookieless, a signed-in user's events carry their opaque id (rendered only when it differs; see `observability/product-events`) |
| session replay (masked; `full` tier only) | `OTEL_REPLAY = "true"` | KCL `telemetry = forge.BrowserTelemetry {replay = True}` (per frontend, per env), or `runtime_config` | **on in new projects**, off in existing implicit-off envs |
| console capture | `CONSOLE_CAPTURE = "false"` | KCL `telemetry.console_capture = False` | **on** |
| replay sample rate | `REPLAY_SAMPLE_RATE` | KCL `telemetry.replay_sample_rate` | every session |
| `page_viewed {route}` and `page_engaged {route, view_id, engaged_ms, scroll_pct}` product events | `PAGE_VIEWS = "false"` | KCL `telemetry.page_views = False` | **on** |
| signed-in user id on every event | `IDENTIFY_USER = "false"` | KCL `telemetry.identify_user = False` | **on** with native sign-in |
| redacted request shape on a failed RPC's span (`forge.forensics`; see `frontend-runtime/transport`) | `RPC_FORENSICS = "false"` | KCL `telemetry.rpc_forensics = False` | **on** |
| `service.version` | — (a build fact: `NEXT_PUBLIC_APP_VERSION` / `VITE_APP_VERSION`) | the deploy | the **build id** a deploy injects (12-hex hash of the frontend source and build env), unless you set it |
For a deployed environment, declare `otel_endpoint = "/_otel"` in the
frontend's KCL `config` block. Every web frontend's `config.js` names its
environment, so `ENVIRONMENT` needs no declaration. A literal
`{NEXT_PUBLIC_,VITE_}OTEL_ENDPOINT` / `ENVIRONMENT` / `OTEL_REPLAY` in the
frontend's `env_vars` is carried into the runtime config as well, so older
declarations keep working (on `forge.OnHosted`, only the ingest path: the
control plane writes that document's `ENVIRONMENT`). A build variable only exported in the shell at
`npm run build` is a **deprecated** fallback: used when `config.js` lacks the
key, with one `console.warn` per page load naming the KCL field to move it to;
it is removed in the next major.
The API origin (`API_URL`) feeds `tracePropagationTargets`, resolved as
`connect.ts` resolves it, so a cross-origin API still gets a `traceparent`.
`environment` is emitted as both `deployment.environment.name` and the legacy
`deployment.environment` that HyperDX's default sources key on.
## Analytics tiers: cookieless by default
Product analytics run in a **tier**, ordered `off` < `aggregate` <
`identified` < `full`: the lowest of the app's `analytics` mode
(`ANALYTICS_MODE` from the runtime config in a generated frontend; absent
means `identified`), the consent the app has signalled, and the browser's
GPC / DNT:
- **`identified`** (the default): product events and page views flow with
**no persistent id, and nothing is stored on the device** — no cookie, no
localStorage, no sessionStorage — and a signed-in user's events carry their
opaque id. The HyperDX SDK's `__rum_sid` session cookie is answered from
memory (`installRumSessionStore`), so spans still group into one session
while the page is open. Visitors are counted by the platform's ingest edge
with a daily-salted hash it forgets; the page sends no fingerprinting input.
- **`aggregate`** (mode `aggregate`, and always under GPC / DNT): as
identified, but strictly anonymous: no user id on browser events, even when
signed in.
- **`full`**: `analytics: "full"` **and** `grantAnalyticsConsent()`. The
session cookie, a persistent `visitor.id`, stored campaign attribution
(`user_identified`, `withAttribution`) and session replay.
- **`off`**: `analytics: "off"` or `optOutOfAnalytics()` (remembered in
`forge.analytics_opt_out`, the one thing stored below `full`). No product
events and no user id; errors and traces still flow.
```ts
import { grantAnalyticsConsent, revokeAnalyticsConsent, optOutOfAnalytics } from "@reliantlabs/forge-web-runtime";
```
Call `grantAnalyticsConsent()` on every page load once your consent manager
says yes (the runtime does not remember consent); `revokeAnalyticsConsent()`
erases what `full` stored and keeps the running session in memory;
`optOutOfAnalytics()` is the person's objection to analytics at all. A start
in a mode that can never reach `full` erases ids an earlier page load stored.
Under GPC / DNT the browser's events carry **no user id** (not even from
`setTelemetryUser`), and no auth event is sent. `attribution` /
`enableAttribution()` are deprecated spellings of mode `full` + consent and
keep working. The contract, and what each tier sends:
`observability/product-events`.
**Where a visit came from.** In `full`, the stored attribution keeps
`rid`, `utm_*`, `ref` (the host of the page that sent the visitor, never a URL)
and `lp` (the entry page's path). The first page load that names neither takes
them from itself. `withAttribution(url)` passes all of them on, and the first
sign-in's `user_identified` carries `referrer_host` and `landing_path`. Below
`full`, `withAttribution` passes on only this page load's `utm_*` and the
referrer's host: no id, nothing is stored, and only to a link on the page's own
host or on a site the call names — `withAttribution(url, { sites:
["example.com"] })` admits `example.com` and its subdomains. A link anywhere
else is returned unchanged, so wrapping every outbound link never hands a
campaign or a referrer to a third party.
**The org.** `setTelemetryOrg(orgId | null)` names the org later events are
about (the `orgId` attribute, stored in `product_events.OrgId`). It follows the
user id's rule: only in `identified` and `full`, never under GPC / DNT, never an
email.
## Page views and the signed-in user, automatically
The generated `otel_gen.ts` turns on two runtime options (both **off** when you
call `initBrowserTelemetry` yourself):
- `pageViews` — one `page_viewed {route}` product event per route the user
lands on (Navigation API where the browser has it, else wrapped
`history.pushState`/`replaceState` plus `popstate`). `route` is the pathname
only: no query or fragment, the basePath stripped, and every segment that
is not a plain route word (lowercase letters joined by `-`/`_`, or `v2`) as
`:id`, so no id format leaves the browser; consecutive repeats are one view.
`normalizeRoute(pathname, basePath)` from the barrel names your own events'
routes the same way. `pageViews: { routeName }` replaces the naming (for an
all-letters value like `/users/jane`); its result is scrubbed the same way,
with `:param` / `[param]` placeholders allowed. The first view of a page
load carries `entry: "true"` and its external referrer (`referrer_host`,
scrubbed `referrer_path`; `pageViews: { siteHosts }` names hosts that are
this site); any view whose URL carries them adds `utm_*`, `ref` and
`click_id` — the ad network's name, never the click id.
Each view also ends in one `page_engaged {route, view_id, engaged_ms, scroll_pct}`
(`pageViews: { engagement: false }` turns that alone off): the time the
page was visible, focused and in use (a 30 s idle cutoff, capped at 30
minutes) and the deepest scroll, reported at the next route change, hide or
unload, then exported at once with `fetch` keepalive. Details:
`observability/product-events`, "Engaged time".
- `identify: { sessionUrl }` — for a frontend with native sign-in
(`src/lib/auth/native-login.ts` and `src/lib/api-base.ts`), the runtime asks
the same `/auth/session` `fetchIdentity` asks, resolved through `apiBase` as
sign-in resolves it (dev proxy and runtime config included), with the
cookie, and passes its `subject` — never `email` or `name`, and never an
`@`-shaped subject — to `setTelemetryUser`, so browser events carry the
backend's `user.id`. A frontend without `api-base.ts` gets no `identify`:
there is no shared resolution, and guessing the origin can miss the cookie. It asks again on a move into or out of `/auth/*` and
when the tab becomes visible, never per navigation. Signed out (a 401/403
included) or an answer naming nobody (404, error, foreign body) clears the
user it set, so no event is tied to the wrong account; before it has set
one, such answers change nothing. Mock mode never asks. An app with its own IdP calls
`setTelemetryUser` and turns this off (`identify_user = False`).
Both start only once the SDK runs and stop on `disableTelemetry()`. The events
land in `product_events` like any `track()` call (`observability/product-events`).
`trackExposure(flag, variant)` and the OpenFeature hook `forgeExposureHook`
(`OpenFeature.addHooks(forgeExposureHook)`) record `flag_evaluated` once per
person, flag and variant per day.
## Source maps are extracted, never served
A deploy builds with `FORGE_SOURCEMAPS=1` (the scaffolded `vite.config.ts` /
`next.config.ts` emit maps only then), then the static stage moves every map out
of the tree it publishes into `<staging>.sourcemaps/` (same relative paths, plus
`manifest.json` naming the project, frontend and build id) and strips the
`sourceMappingURL` trailers. The release digest excludes them, and a guard fails
a deploy whose served tree still holds one. Firebase asset retention never
carries a `.map` forward.
The sidecar is filed in the platform registry
(`<org>/<project>/<frontend>-sourcemaps:<build id>`), where the issues worker
symbolicates errors from. `telemetry = forge.BrowserTelemetry {sourcemaps =
"public"}` is the escape hatch for an app that wants its maps served: the tree
keeps its maps and trailers, and the maps are still copied to the sidecar and
filed, so its errors symbolicate too. `"off"` keeps maps nowhere, and its errors
stay minified.
## Session replay
New app and site envs record masked replay (`_session_replay = True` in
`deploy/kcl/<env>/main.k`), only in the `full` analytics tier, honouring
GPC/DNT. The runtime records it itself, rrweb in a lazy chunk, encoding off the
main thread. Switches, consent, the recorder (`replayStart`,
`replayFlushIntervalMs`) and upgrading from `@hyperdx/browser`: load
`frontend-runtime/telemetry/replay`.
## Reporting a caught error
Uncaught errors, rejections and `console.error` are recorded for you. React
error boundaries and Next's `error.tsx` swallow errors before `window.onerror`
sees them, so they call `reportException(error, attrs)` from the barrel (the
scaffolded `error.tsx`, `global-error.tsx` and `RuntimeErrorBoundary` already
do). It returns `false` when no SDK is running so the caller can fall back to
`console.error`, and it skips an error the SDK has already recorded — one failure
is one record. Use it in your own catch blocks the same way.
```ts
import { reportException } from "@reliantlabs/forge-web-runtime";
try {
await checkout();
} catch (err) {
if (!reportException(err, { "checkout.step": "payment" })) console.error(err);
throw err;
}
```
## Who is signed in
Call `identifyUser(subject)` from the barrel wherever the app learns who is
signed in (the scaffolded auth context, Clerk's `useUser`, Auth0's
`useAuth0`), and `identifyUser(null)` on sign-out. It attaches the opaque id to
every span and replay (so the Sessions view and `forge obs sessions --user`
work) and sends one `auth_signed_in {kind: "resumed"}` per user per UTC day,
which is how the console counts active users. `trackAuthEvent("signed_in" |
"signed_up" | "signed_out", { userId, … })` reports the auth outcome itself, for
an app whose auth never touches a forge server. Both refuse an email-shaped id;
under GPC or DNT they send no auth event and attach no id. Below the `full`
tier the daily marker is kept in memory, never stored. The contract and the server-side
emitters: `observability/product-events/auth-events`.
**On Supabase, Clerk, Auth0 or Firebase**, one line does it: the provider's
adapter subpath maps its callbacks onto `identifyUser` and the sign-out event,
with the provider named on each event (structurally typed, no dependency):
```ts
import { createSupabaseAuthTelemetry } from "@reliantlabs/forge-web-runtime/auth/supabase";
createSupabaseAuthTelemetry(supabase); // next to createClient
// /auth/clerk: createClerkAuthTelemetry(clerk) /auth/auth0: syncAuth0(client), reportAuth0SignOut(client)
// /auth/firebase: createFirebaseAuthTelemetry((cb) => onIdTokenChanged(auth, cb)), reportFirebaseSignIn(user, info)
```
Anonymous sessions (Supabase `signInAnonymously`, Firebase anonymous auth) are
never identified or counted. An app with its own `onAuthStateChange` passes
`supabaseAuthTelemetryListener()` its `(event, session)` instead.
## Interactions: click to usable
A fetch span times one RPC. To time what the user waits for — several RPCs,
a stream's first frame, a render — open an `interaction` (barrel) on intent
and end it when the screen is usable:
```ts
const op = interaction("chat.open", { "chat.id": id }); // in the click handler
useInteractionEnd(op, loaded); // endAfterPaint() on the first ready commit
```
It is one root span (`interaction.name|scope|outcome`), and every RPC made
while it is open is its child, server spans included — no `context.with`,
which a browser loses at the first `await`. The choice is made when the call
enters the interceptor chain, so a call held by auth's `getToken()` stays in
its own interaction; a chain whose outermost stages are the app's own and
await puts `interactionContextInterceptor()` first. A span the caller has
active when it makes the call still wins. One interaction is open per `scope` (default
`foreground`); a new one ends the old as `superseded`. `endAfterPaint()` waits
two animation frames; ends are idempotent; unended ones end as `timeout` after
60s; a page hidden while open stamps `page.hidden`. `mark(name)` adds a phase
event; `currentInteraction()` finds the open one. With telemetry off it records
nothing but its RPCs still share one trace id; it never throws.
Custom spans: `getTracer("checkout")` from `@/lib/otel_gen`.
Distributed tracing (the traceparent on every RPC) is independent and always
on — it does **not** depend on this module.