The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
docs updated for full session replays
ddux84b7e40392d0
diff --git a/docs/pages/client/jquery/index.mdx b/docs/pages/client/jquery/index.mdxindex cb1507f0..fcf04d6c 100644--- a/docs/pages/client/jquery/index.mdx+++ b/docs/pages/client/jquery/index.mdx@@ -88,6 +88,12 @@ init("your-token@https://cloud.tracewayapp.com/api/report", {| `version` | `string` | `undefined` | Your application version || `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Error patterns to ignore. Pass `[]` to capture all errors. See [Error Filtering](/client/js-sdk/initialization#error-filtering) || `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |+| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder |+| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording. See [Sessions](/learn/sessions) |+| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |+| `captureNetwork` | `boolean` | `true` | Record `fetch` / `XHR` calls as network actions |+| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions |## Error Filtering@@ -115,6 +121,27 @@ init("your-token@https://cloud.tracewayapp.com/api/report", {});```+## Custom Attributes++Attach app-level identifiers (`userId`, `tenant`, feature flags, etc.) to every session and exception:++```javascript+import {+ setAttribute,+ setAttributes,+ removeAttribute,+ clearAttributes,+} from "@tracewayapp/jquery";++setAttribute("userId", "u_42");+setAttributes({ tenant: "acme", plan: "pro" });++// On logout / tenant switch:+clearAttributes();+```++Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.+## Distributed TracingThe SDK automatically instruments both `XMLHttpRequest` (used by `$.ajax()`) and `fetch` to propagate a `traceway-trace-id` header on same-origin requests. This links frontend errors to the backend requests that caused them.diff --git a/docs/pages/client/js-sdk/initialization.mdx b/docs/pages/client/js-sdk/initialization.mdxindex a8cb5fb6..bb2d46c3 100644--- a/docs/pages/client/js-sdk/initialization.mdx+++ b/docs/pages/client/js-sdk/initialization.mdx@@ -32,6 +32,14 @@ init("your-token@https://traceway.example.com/api/report", {| `version` | `string` | `undefined` | Your application version (shown in Traceway dashboard) || `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Patterns to filter out errors before capture. See [Error Filtering](#error-filtering) || `beforeCapture` | `(exception) => boolean` | `undefined` | Callback to programmatically suppress errors. Return `false` to drop. See [Error Filtering](#error-filtering) |+| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder. Required for both per-exception clips and always-on session recording |+| `sessionRecordingSegmentDuration` | `number` | `30000` | Length of each rrweb segment in milliseconds. Always-on recording uploads one row per segment, so a longer value means fewer rows and S3 reads at the cost of replay granularity |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording — upload every segment continuously and create a parent `sessions` row, not just exception-bound clips. See [Sessions](/learn/sessions) for the full feature |+| `captureLogs` | `boolean` | `true` | Mirror `console.{debug,log,info,warn,error}` into the rolling log buffer that ships with each clip / segment |+| `captureNetwork` | `boolean` | `true` | Record `fetch` and `XMLHttpRequest` calls as network actions |+| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions as navigation actions |+| `eventsWindowMs` | `number` | `10000` (`30000` w/ `recordAllSessions`) | Rolling window the log/action buffers retain |+| `eventsMaxCount` | `number` | `200` (`600` w/ `recordAllSessions`) | Hard cap on entries kept independently in the log and action buffers |## Auto-Capture Behavior@@ -138,6 +146,29 @@ init("your-token@https://traceway.example.com/api/report", {});```+## Custom Attributes (Global Scope)++The SDK auto-collects browser context (`url`, `userAgent`, `viewport`, etc.) on every session and exception. To attach app-level identifiers — `userId`, `tenant`, feature flags — call the imperative scope API once and they ride along every subsequent event:++```javascript+import {+ setAttribute,+ setAttributes,+ removeAttribute,+ clearAttributes,+} from "@tracewayapp/frontend";++setAttribute("userId", "u_42");+setAttributes({ tenant: "acme", plan: "pro" });++// On logout / tenant switch:+clearAttributes();+```++Layering on each event: **defaults < global scope < per-call**. `captureExceptionWithAttributes(err, { … })` still wins over global keys for the specific exception.++If `recordAllSessions: true` is on, calling `setAttribute*` mid-session also pushes a refresh upsert so the live session row picks up the new attributes immediately rather than waiting for close. See [Sessions](/learn/sessions) for the full attribute model.+## Multiple EnvironmentsFor different environments, use separate project tokens:diff --git a/docs/pages/client/js-sdk/session-replay.mdx b/docs/pages/client/js-sdk/session-replay.mdxindex df986e92..ed01689a 100644--- a/docs/pages/client/js-sdk/session-replay.mdx+++ b/docs/pages/client/js-sdk/session-replay.mdx@@ -34,7 +34,8 @@ init("your-token@https://traceway.example.com/api/report", {| Option | Type | Default | Description ||--------|------|---------|-------------|| `sessionRecording` | `boolean` | `true` | Enable or disable session recording |-| `sessionRecordingSegmentDuration` | `number` | `10000` | Duration of each recording segment in milliseconds |+| `sessionRecordingSegmentDuration` | `number` | `30000` | Duration of each recording segment in milliseconds |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording — upload every segment regardless of whether an exception fires. See [Always-on Session Recording](#always-on-session-recording) |## Privacy & Masking@@ -85,16 +86,38 @@ Reach for the `rr-*` classes whenever the sensitive content isn't in a form fiel## Segment Rotation-Recordings are split into segments to limit memory usage. Every 10 seconds (by default), the current segment is finalized and a new one begins with a fresh DOM snapshot.+Recordings are split into segments to limit memory usage. Every 30 seconds (by default), the current segment is finalized and a new one begins with a fresh DOM snapshot.You can adjust the segment duration:```javascriptinit("your-token@https://traceway.example.com/api/report", {- sessionRecordingSegmentDuration: 30000, // 30 seconds per segment+ sessionRecordingSegmentDuration: 60000, // 60 seconds per segment});```+A longer segment duration means fewer rows and fewer S3 reads when reassembling a session, at the cost of replay granularity. The default of 30 s is calibrated for typical browser apps.++## Always-on Session Recording++By default the recorder only ships clips when an exception fires. Pass `recordAllSessions: true` to upload **every** segment continuously and produce a parent `sessions` row in the dashboard:++```javascript+init("your-token@https://traceway.example.com/api/report", {+ recordAllSessions: true,+});+```++What changes when always-on is enabled:++- A persistent `sessionId` is generated at SDK init (or after bfcache restore).+- Each rrweb segment is uploaded as it rotates, linked to the parent session via `sessionId` + `segmentIndex`.+- Sessions end on **15 min inactivity**, **60 min max duration**, or `pagehide`. The closing payload is dispatched via `fetch keepalive` with raw JSON so it survives navigation.+- Logs and actions are flushed onto each segment as it rotates (drained from the rolling buffer to avoid double-counting).+- Exceptions captured during the session still produce their own clip on the issue page **and** stamp the parent `sessionId` so the dashboard renders a "View full session →" link.++Sessions appear on the dedicated **Sessions** page in the dashboard, with attribute filters (`userId=…`, `tenant=…`, etc.) and full-session replay. See [Sessions](/learn/sessions) for the full feature description.+## Viewing RecordingsWhen an exception includes session recording data, a **Session Replay** card appears on the exception detail page in the Traceway dashboard. The replay shows DOM state and user interactions leading up to the error.diff --git a/docs/pages/client/react-native/index.mdx b/docs/pages/client/react-native/index.mdxindex 0080f872..e8107a1d 100644--- a/docs/pages/client/react-native/index.mdx+++ b/docs/pages/client/react-native/index.mdx@@ -179,24 +179,24 @@ Each channel can be turned off individually via `TracewayProvider`'s `options`:>```-## Attributes (device info & globals)+## Attributes-Every captured exception ships with an `attributes` map. Two layers contribute:+Every captured exception ships with an `attributes` map composed of three layers (per-call wins, then global scope, then device info).-1. **Device info** — auto-collected at `init()` from React Native core APIs (no native modules required, works in Expo Go). The keys mirror what the Flutter and Android SDKs emit so the dashboard renders them consistently across platforms:+### 1. Device info — auto-collected- | Key | Source |- |---|---|- | `os.name` | `Platform.OS` (`ios` / `android` / `web`) |- | `os.version` | `Platform.Version` |- | `screen.resolution` | `Dimensions.get("screen")` (whole pixels) |- | `screen.density` | `PixelRatio.get()` |- | `device.locale` | `Intl.DateTimeFormat().resolvedOptions().locale` |- | `runtime.engine` | `hermes` / `javascriptcore` |+Auto-stamped at `init()` from React Native core APIs (no native modules required, works in Expo Go). The keys mirror what the Flutter and Android SDKs emit so the dashboard renders them consistently across platforms:-2. **Per-call attributes** via `captureExceptionWithAttributes(error, attrs)` — these win on key collision.+| Key | Source |+|---|---|+| `os.name` | `Platform.OS` (`ios` / `android` / `web`) |+| `os.version` | `Platform.Version` |+| `screen.resolution` | `Dimensions.get("screen")` (whole pixels) |+| `screen.density` | `PixelRatio.get()` |+| `device.locale` | `Intl.DateTimeFormat().resolvedOptions().locale` |+| `runtime.engine` | `hermes` / `javascriptcore` |-To replace or extend the auto-collected map at runtime (e.g. add a `tenant`, `build_channel`, or info from `expo-device` / `react-native-device-info` you've installed yourself):+To replace or extend the auto-collected map at runtime (e.g. add info from `expo-device` / `react-native-device-info` you've installed yourself):```tsimport { setDeviceAttributes, collectSyncDeviceInfo } from "@tracewayapp/react-native";@@ -206,18 +206,50 @@ setDeviceAttributes({...collectSyncDeviceInfo(),"device.model": Device.modelName ?? "","device.manufacturer": Device.manufacturer ?? "",- tenant: "acme-corp",- build_channel: process.env.EXPO_PUBLIC_BUILD_CHANNEL ?? "dev",});```-The same hook is exposed on `useTraceway()`:+To opt out of device info collection entirely, pass `captureDeviceInfo: false` in `options`.++### 2. Global scope — app-level identifiers++Use the global scope for things tied to the **user / tenant / app state**, not the device: user id, organization id, build channel, feature flags, A/B bucket. Two ways to set it.++**Declarative — `<TracewayAttributes>` or the `useTracewayAttributes` hook.** Pass a map; the SDK diffs against the previous map and pushes only the deltas. On unmount, every key the component owned is removed.```tsx-const { setDeviceAttributes } = useTraceway();+import { TracewayAttributes, useTracewayAttributes } from "@tracewayapp/react-native";++// As a component:+<TracewayAttributes attributes={user ? { userId: user.id, tenant: org.id } : null} />++// Or as a hook:+function App() {+ useTracewayAttributes({ build_channel: "canary" });+ return <RootNavigator />;+}```-To opt out of the device info collection entirely, pass `captureDeviceInfo: false` in `options`.+Both accept `null` / `undefined` as "empty map" — useful while user data loads or after logout.++**Imperative — `setAttribute` / `setAttributes` / `removeAttribute` / `clearAttributes`.** Use these outside React component trees (auth listeners, background tasks):++```ts+import { setAttribute, setAttributes, clearAttributes } from "@tracewayapp/react-native";++setAttribute("userId", "u_42");+setAttributes({ tenant: "acme", plan: "pro" });+// ...on logout:+clearAttributes();+```++### 3. Per-call attributes++`captureExceptionWithAttributes(error, attrs)` — wins on key collision over both layers above.++### Layering++For each captured exception: `device info < global scope < per-call`.## What Gets Captured Automaticallydiff --git a/docs/pages/client/react/provider.mdx b/docs/pages/client/react/provider.mdxindex 4a352df5..5194ebb5 100644--- a/docs/pages/client/react/provider.mdx+++ b/docs/pages/client/react/provider.mdx@@ -34,6 +34,45 @@ function App() {| `version` | `string` | `undefined` | Your application version || `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Error patterns to ignore. Pass `[]` to capture all errors. See [Error Filtering](/client/js-sdk/initialization#error-filtering) || `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |+| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder |+| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording. See [Sessions](/learn/sessions) |+| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |+| `captureNetwork` | `boolean` | `true` | Record `fetch` / `XHR` calls as network actions |+| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions |+| `eventsWindowMs` | `number` | `10000` (`30000` w/ `recordAllSessions`) | Rolling log/action buffer window |+| `eventsMaxCount` | `number` | `200` (`600` w/ `recordAllSessions`) | Hard cap on log/action buffer entries |++## Custom Attributes++Use `<TracewayAttributes>` or the `useTracewayAttributes` hook to bind a reactive map of attributes (`userId`, `tenant`, feature flags, etc.) to the SDK's global scope. The hook diffs against the previous map on every render and pushes only the deltas; on unmount, every key it currently owns is removed.++```jsx+import { TracewayAttributes, useTracewayAttributes } from "@tracewayapp/react";++// As a component:+<TracewayAttributes attributes={user ? { userId: user.id, tenant: org.id } : null} />++// Or as a hook:+function App() {+ useTracewayAttributes({ userId: user?.id, tenant: org?.id });+ return <Routes />;+}+```++Both accept `null` / `undefined` as "empty map" — useful while user data loads or after logout. New object reference with the same content does not trigger SDK calls.++For imperative use (background workers, init scripts), the same primitives are exported as plain functions:++```javascript+import { setAttribute, setAttributes, removeAttribute, clearAttributes } from "@tracewayapp/react";++setAttribute("build_channel", import.meta.env.VITE_CHANNEL ?? "dev");+setAttributes({ tenant: "acme", plan: "pro" });+clearAttributes(); // on logout+```++Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.## Example with Optionsdiff --git a/docs/pages/client/svelte/context.mdx b/docs/pages/client/svelte/context.mdxindex 7972ce4f..757fda8b 100644--- a/docs/pages/client/svelte/context.mdx+++ b/docs/pages/client/svelte/context.mdx@@ -43,6 +43,12 @@ Must be called during component initialization (not in an event handler):| `version` | `string` | `undefined` | Your application version || `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Error patterns to ignore. Pass `[]` to capture all errors. See [Error Filtering](/client/js-sdk/initialization#error-filtering) || `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |+| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder |+| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording. See [Sessions](/learn/sessions) |+| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |+| `captureNetwork` | `boolean` | `true` | Record `fetch` / `XHR` calls as network actions |+| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions |## getTraceway@@ -122,6 +128,44 @@ Child component:</form>```+## Custom Attributes++Use `useTracewayAttributes` to bind a reactive map of attributes (`userId`, `tenant`, feature flags, etc.) to the SDK's global scope. It's a factory: call it once during component setup, then invoke the returned setter from `$effect` (Svelte 5) or `$:` (Svelte 4). The setter diffs against the last map and pushes only the deltas; `onDestroy` removes every key it currently owns.++```svelte+<!-- Svelte 5 -->+<script>+ import { useTracewayAttributes } from "@tracewayapp/svelte";+ let { user, org } = $props();+ const sync = useTracewayAttributes();+ $effect(() => sync({ userId: user.id, tenant: org.id }));+</script>+```++```svelte+<!-- Svelte 4 -->+<script>+ import { useTracewayAttributes } from "@tracewayapp/svelte";+ export let user; export let org;+ const sync = useTracewayAttributes();+ $: sync({ userId: user.id, tenant: org.id });+</script>+```++The setter accepts `null` / `undefined` as "empty map" — useful while user data loads or after logout.++For imperative use (load functions, hooks), the same primitives are exported as plain functions:++```javascript+import { setAttribute, setAttributes, removeAttribute, clearAttributes } from "@tracewayapp/svelte";++setAttribute("build_channel", "canary");+setAttributes({ tenant: "acme", plan: "pro" });+clearAttributes(); // on logout+```++Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.+## TRACEWAY_KEYFor advanced use cases, you can access the context key directly:diff --git a/docs/pages/client/vue/plugin.mdx b/docs/pages/client/vue/plugin.mdxindex 833c656e..41a9cb3f 100644--- a/docs/pages/client/vue/plugin.mdx+++ b/docs/pages/client/vue/plugin.mdx@@ -35,6 +35,12 @@ app.mount("#app");| `version` | `string` | `undefined` | Your application version || `ignoreErrors` | `Array<string \| RegExp>` | `DEFAULT_IGNORE_PATTERNS` | Error patterns to ignore. Pass `[]` to capture all errors. See [Error Filtering](/client/js-sdk/initialization#error-filtering) || `beforeCapture` | `(exception) => boolean` | `undefined` | Return `false` to suppress an error. See [Error Filtering](/client/js-sdk/initialization#error-filtering) |+| `sessionRecording` | `boolean` | `true` | Enable the rrweb session recorder |+| `sessionRecordingSegmentDuration` | `number` | `30000` | rrweb segment length in ms |+| `recordAllSessions` | `boolean` | `false` | Always-on session recording. See [Sessions](/learn/sessions) |+| `captureLogs` | `boolean` | `true` | Mirror `console.*` calls into the rolling log buffer |+| `captureNetwork` | `boolean` | `true` | Record `fetch` / `XHR` calls as network actions |+| `captureNavigation` | `boolean` | `true` | Record History API push / replace / pop transitions |## Full Example@@ -100,6 +106,29 @@ app.use(createTracewayPlugin({}));```+## Custom Attributes++Attach app-level identifiers (`userId`, `tenant`, feature flags, etc.) to every session and exception using the imperative scope API. Drive it from `watchEffect` so it tracks reactive state:++```vue+<script setup>+import { watchEffect } from "vue";+import { setAttributes, clearAttributes } from "@tracewayapp/vue";+import { useUser } from "./auth";++const { user, org } = useUser();+watchEffect(() => {+ if (user.value && org.value) {+ setAttributes({ userId: user.value.id, tenant: org.value.id });+ } else {+ clearAttributes();+ }+});+</script>+```++The full API (`setAttribute`, `setAttributes`, `removeAttribute`, `clearAttributes`) is re-exported from `@tracewayapp/vue`. Layering on each event: **defaults < global scope < per-call**. See [Sessions](/learn/sessions) for the full attribute model.+## Manual InjectionFor advanced use cases, you can use the injection key directly:diff --git a/docs/pages/learn/_meta.json b/docs/pages/learn/_meta.jsonindex 7b40e7cd..0e532cbd 100644--- a/docs/pages/learn/_meta.json+++ b/docs/pages/learn/_meta.json@@ -4,6 +4,7 @@"traces": "Traces","ai-tracing": "AI Tracing","issues": "Issues",+ "sessions": "Sessions","attributes": "Attributes","spans": "Spans","metrics": "Metrics",diff --git a/docs/pages/learn/sessions.mdx b/docs/pages/learn/sessions.mdxnew file mode 100644index 00000000..23f41795--- /dev/null+++ b/docs/pages/learn/sessions.mdx@@ -0,0 +1,98 @@+# Sessions++A **session** is a full recording of one user's interactions with a browser app — typically the lifetime of an open tab. Where an [Issue](/learn/issues) shows you a single moment that something broke, a session shows you the entire journey: what the user clicked, navigated to, scrolled past, and saw on screen, with the same console logs and network calls layered on top.++Sessions are a browser-only concept. They're emitted by the JavaScript SDK and its framework wrappers (React, Vue, Svelte, jQuery) when **always-on session recording** is enabled. Backend and mobile SDKs do not produce sessions.++## Sessions vs. Exception Clips++Traceway's browser SDK has always shipped a short rrweb clip alongside every captured exception — the rolling window of events from just before the error fired. That clip stays on the issue detail page; it answers "what did the page look like the moment things went wrong?".++A session is the larger envelope around those moments:++| | Exception Clip | Session |+|---|---|---|+| Default behaviour | On (rolling window flushed with each captured exception) | Off — opt in with `recordAllSessions: true` |+| Scope | Last ~10 s before an exception | Entire tab lifetime, capped at 60 min |+| Storage | One file per exception | One file per ~30 s segment, many per session |+| When uploaded | At exception capture | Continuously, every segment rotation |+| Where surfaced | Inline on the issue page | Sessions list + dedicated detail page; linked from issues |++Both can coexist: an exception fired during an always-on session gets its inline clip on the issue page **and** a "View full session →" link to the parent session.++## What a Session Records++The recording uses [rrweb](https://github.com/rrweb-io/rrweb) to capture DOM mutations, input events, mouse movement, and viewport changes. Replay is a faithful reconstruction — text, layout, scrolling, hover states, even mouse trails. Privacy markers (`rr-mask`, `rr-block`, `rr-ignore`) work the same way they do for exception clips. See [Session Replay in the JS SDK guide](/client/js-sdk/session-replay#privacy--masking) for the full masking reference.++Alongside the rrweb stream, each segment carries:++- **Logs** — every `console.{debug,log,info,warn,error}` call recorded during the segment window.+- **Actions** — `fetch` / `XMLHttpRequest` calls, History API navigations, and any `recordAction(...)` breadcrumbs.++The dashboard's session detail page renders these as separate tabs below the player, scrub-synced to the replay timeline.++## Session Lifecycle++A session begins automatically when the SDK initializes with `recordAllSessions: true` (or when the page is restored from the bfcache after a back/forward navigation — a fresh `sessionId` is generated each time).++It ends on the first of:++| Trigger | When | Behaviour |+|---|---|---|+| **Inactivity timeout** | 15 minutes since the last DOM event rrweb observed | Session is closed; subsequent activity opens a new one |+| **Maximum duration** | 60 minutes from session start | Hard cap regardless of activity |+| **Page unload** | `pagehide` fires (close tab, hard refresh, navigate away) | Final segment is drained, closing payload sent via `fetch keepalive` |++If a session ends without an explicit close (e.g. the browser is force-quit before `pagehide` runs, or the closing flush is dropped), its `ended_at` stays NULL on the backend and the dashboard renders the duration as **Abandoned** once the row has been quiet for ≥ 15 min.++## Attributes++Every session ships with a context map. Three layers contribute:++1. **Auto-collected defaults** — the SDK stamps `url`, `path`, `referrer`, `userAgent`, `language`, `platform`, `viewport`, `screen`, and `timezone` from `window` / `navigator`. The backend additionally stamps `client.ip` from the request.+2. **Global scope** — anything set via `setAttribute("userId", "u_42")` / `setAttributes({ tenant: "acme" })` on the SDK. These flow through every subsequent session, exception, and segment update.+3. **Per-call attributes** — `captureExceptionWithAttributes(err, { … })` for exceptions only.++Layering: defaults → global scope → per-call. Higher layers win on key collision.++See the framework-specific guides for the API:++- [JS SDK initialization](/client/js-sdk/initialization)+- [React](/client/react/provider) — `setAttribute*` plus the `<TracewayAttributes>` component / `useTracewayAttributes` hook for declarative reactive scope+- [Svelte](/client/svelte/context) — `setAttribute*` plus the `useTracewayAttributes` factory+- [Vue](/client/vue/plugin) — `setAttribute*` (drive from `watchEffect`)+- [React Native](/client/react-native) — same as React, layered above device info++## Filtering Sessions++The Sessions page in the dashboard accepts:++- **Search by session ID** — paste a UUID for an exact match.+- **Attribute filters** — add `key=value` filters (e.g. `userId=u_42`, `tenant=acme`, `experiment.cart_redesign=variant_b`). Filters AND together; values are exact match.++Attribute filters are backed by a Map column with bloom-filter indexes on keys and values, so they stay fast even as the table grows.++## Sessions and Issues++Every exception captured inside an always-on session is stamped with the parent `sessionId`. From the dashboard:++- The **issue detail page** keeps showing the inline 10 s clip but renders a "View full session →" button when a session id is present.+- The **session detail page** renders a table of every exception that fired during that session, each linked back to its issue.++This stitching is independent of whether the exception was caught by your code or by the SDK's global handlers.++## Cost and Storage++Always-on session recording is more data than exception-only capture — every active tab uploads continuously, ~30 s segments, until the user leaves. Plan accordingly:++- Default segment duration is 30 s. This is a 3× reduction in S3 reads compared to a 10 s cadence; tune via `sessionRecordingSegmentDuration` (ms) if your traffic profile differs.+- Logs and actions are drained from the rolling buffer at each segment rotation, so a single segment carries the activity it spans (no double-counting across segments).+- Recordings older than the platform retention window are pruned automatically.++For most apps, recording a sample of sessions (or only premium-tier users, etc.) is the right balance. Set `recordAllSessions: false` to turn it off entirely — the SDK falls back to exception-only clips with no per-segment uploads.++## Next Steps++- [Session Replay in the JS SDK](/client/js-sdk/session-replay) — privacy masking, segment rotation, and the wire format.+- [Issues](/learn/issues) — how exceptions are grouped and what an issue page shows.+- [Attributes](/learn/attributes) — the broader attribute model that backs sessions, exceptions, traces, and tasks.diff --git a/docs/pages/protocol/index.md b/docs/pages/protocol/index.mdindex 25adab16..e648af5b 100644--- a/docs/pages/protocol/index.md+++ b/docs/pages/protocol/index.md@@ -8,7 +8,7 @@ This document is the complete protocol specification for the Traceway `/api/repoPOST /api/report```-A single endpoint accepts all telemetry data: **traces** (endpoints and tasks), **exceptions** (errors and messages), and **metrics**.+A single endpoint accepts all telemetry data: **traces** (endpoints and tasks), **exceptions** (errors and messages), **metrics**, and (for browser SDKs) **sessions** with **session recordings**.## Authentication@@ -50,7 +50,7 @@ Parse by splitting on the first `@`:### Gzip Requirement-The request body **must** be gzip-compressed JSON. The backend checks for the `Content-Encoding: gzip` header and returns `400 Bad Request` if it is missing. The body is decompressed server-side before JSON parsing.+The request body **should** be gzip-compressed JSON for the regular sync path. The backend's gzip middleware decompresses when `Content-Encoding: gzip` is present and passes the body through unchanged when it is absent. Browser SDKs use the uncompressed path on the page-unload (`pagehide`) flush so the request can dispatch synchronously inside the unload handler — `CompressionStream` is async and would yield control before the request leaves. Servers MUST therefore accept both compressed and uncompressed JSON on `/api/report`.## Request Payload@@ -78,7 +78,9 @@ Each frame is a batch of data collected during one collection interval.{"stackTraces": [ ... ],"metrics": [ ... ],- "traces": [ ... ]+ "traces": [ ... ],+ "sessions": [ ... ],+ "sessionRecordings": [ ... ]}```@@ -87,8 +89,10 @@ Each frame is a batch of data collected during one collection interval.| `stackTraces` | `ExceptionStackTrace[]` | Yes | Array of exception/message records || `metrics` | `MetricRecord[]` | Yes | Array of metric data points || `traces` | `Trace[]` | Yes | Array of endpoint and task traces |+| `sessions` | `Session[]` | No | Browser SDKs only: session-lifecycle markers (open / refresh / close). Omit for non-browser SDKs |+| `sessionRecordings` | `SessionRecording[]` | No | Browser SDKs only: rrweb segment uploads. Omit when there is nothing to ship |-All three arrays should be present. Use empty arrays `[]` or `null` when there is no data of that type.+All five fields are accepted. Use empty arrays `[]` or `null` (or omit entirely) when there is no data of that type.## Traces@@ -280,6 +284,125 @@ SDKs can send any `name`/`value` pair. There is no registry — any string name{ "name": "queue.length", "value": 42.0, "recordedAt": "2025-01-15T10:30:00Z" }```+## Sessions++A **session** represents one user's continuous interaction with a browser app — typically the lifetime of an open tab. Sessions are emitted only by browser SDKs that have **always-on session recording** enabled (`recordAllSessions: true`); back-end and mobile SDKs omit the `sessions` and `sessionRecordings` fields entirely.++The session row is upserted on the backend (keyed by `id`), so the same session can be emitted multiple times during its lifetime — each emission overwrites mutable fields (`endedAt`, `duration`, `attributes`). The shape is identical for the open, mid-session refresh, and close payloads; only the populated fields differ.++### Session Object++```json+{+ "id": "8a1f0b3c-2e7a-4f1d-9bd4-71e6c8a2b5d0",+ "startedAt": "2026-05-06T14:02:00.000Z",+ "endedAt": "2026-05-06T14:23:17.412Z",+ "clientIP": "",+ "attributes": {+ "url": "https://app.example.com/dashboard",+ "userAgent": "Mozilla/5.0 ...",+ "viewport": "1920x1080",+ "userId": "u_42",+ "tenant": "acme"+ },+ "distributedTraceId": ""+}+```++| Field | JSON Key | Type | Required | Description |+|-------|----------|------|----------|-------------|+| Id | `id` | `string` | Yes | UUID v4. Generated client-side at session start; persistent for the page lifecycle. The backend uses this directly as the session row id |+| StartedAt | `startedAt` | `string` | Yes | RFC 3339 timestamp of session start |+| EndedAt | `endedAt` | `string \| null` | No | RFC 3339 timestamp of session end. Omitted on the opening payload; populated on the close payload |+| ClientIP | `clientIP` | `string` | No | Optional client-side hint. The backend stamps the request's IP into `attributes["client.ip"]` regardless |+| Attributes | `attributes` | `object` | No | Key-value pairs (auto-collected browser context + caller-provided global scope) |+| DistributedTraceId | `distributedTraceId` | `string` | No | Optional UUID linking the session to a distributed trace |++### Session Lifecycle (browser SDKs)++A new session begins on:++1. SDK init when `recordAllSessions: true` and a browser context is available.+2. Page restore from bfcache (`pageshow` with `event.persisted === true`) — a fresh `id` is generated and the previous session row is left as-is.++A session ends on:++1. **Inactivity timeout** — 15 min since the last DOM event observed by rrweb (or the last `markActivity()` call).+2. **Maximum duration** — 60 min from `startedAt`.+3. **Page unload** — `pagehide` triggers a final flush and end.++The closing payload is sent via `fetch(..., { keepalive: true })` with raw JSON (no gzip) so it dispatches synchronously inside the `pagehide` handler.++### Auto-collected Attributes++Browser SDKs stamp these on every session at open and close (caller-provided keys via `setAttribute*` win on collision):++| Key | Source |+|---|---|+| `url` | `window.location.href` |+| `path` | `window.location.pathname` |+| `referrer` | `document.referrer` |+| `userAgent` | `navigator.userAgent` |+| `language` | `navigator.language` |+| `platform` | `navigator.platform` |+| `viewport` | `${window.innerWidth}x${window.innerHeight}` |+| `screen` | `${screen.width}x${screen.height}` |+| `timezone` | `Intl.DateTimeFormat().resolvedOptions().timeZone` |+| `client.ip` | Stamped server-side from the request's `RemoteAddr` |++## Session Recordings++Session recordings carry the actual replay data. Each recording is **one segment** — typically ~30 s of rrweb events. A session is reassembled at view time by ordering all of its recordings by `segmentIndex`.++A recording can be **session-bound** (always-on path), **exception-bound** (legacy, when an exception is captured), or both at once when an exception fires inside an always-on segment.++### SessionRecording Object++```json+{+ "exceptionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",+ "sessionId": "8a1f0b3c-2e7a-4f1d-9bd4-71e6c8a2b5d0",+ "segmentIndex": 4,+ "events": [ /* rrweb event objects */ ],+ "logs": [ /* console output entries */ ],+ "actions": [ /* fetch / navigation / custom breadcrumbs */ ],+ "startedAt": "2026-05-06T14:14:00.000Z",+ "endedAt": "2026-05-06T14:14:30.000Z"+}+```++| Field | JSON Key | Type | Required | Description |+|-------|----------|------|----------|-------------|+| ExceptionId | `exceptionId` | `string` | No | UUID linking the recording to a specific exception. Set on exception-bound clips; omitted for pure always-on segments |+| SessionId | `sessionId` | `string` | No | UUID linking the recording to a parent session. Set on always-on segments; omitted for legacy exception-bound clips |+| SegmentIndex | `segmentIndex` | `integer` | No | Monotonically increasing per-session counter starting at 0. Omitted (defaults to 0) for exception-bound clips |+| Events | `events` | `array` | Yes | rrweb event array (DOM mutations, input events, mouse moves) |+| Logs | `logs` | `array` | No | Console output entries captured in the segment window |+| Actions | `actions` | `array` | No | Network / navigation / custom breadcrumbs captured in the segment window |+| StartedAt | `startedAt` | `string` | No | RFC 3339 timestamp of the first event in the segment |+| EndedAt | `endedAt` | `string` | No | RFC 3339 timestamp of the last event in the segment |++The backend stores each recording as a row in `session_recordings` with the events bytes written to S3 (or a configured object store). At least one of `exceptionId` or `sessionId` must be set — recordings with neither linkage are dropped.++## Exception ↔ Session Linking++`ExceptionStackTrace` gains an optional `sessionId` field. Browser SDKs running with `recordAllSessions: true` stamp every exception with the current session id, so the dashboard can render a "View full session" link from the issue page even when the per-exception clip is the inline replay.++```json+{+ "stackTrace": "...",+ "recordedAt": "2026-05-06T14:14:23.000Z",+ "sessionId": "8a1f0b3c-2e7a-4f1d-9bd4-71e6c8a2b5d0",+ "isMessage": false+}+```++| Field | JSON Key | Type | Required | Description |+|-------|----------|------|----------|-------------|+| SessionId | `sessionId` | `string \| null` | No | UUID of the parent session. Omitted when no session is active or when `recordAllSessions` is off |++The legacy `sessionRecordingId` field still works for exception-bound clips. Both can be set on a single exception captured inside an always-on session.+## Batching and Collection StrategyThis section describes the recommended client-side implementation, based on the Go SDK.