Session Replay

Quick Start

Install the replay package and pass it as an addon to the browser SDK.

npm install @tracekit/replay

import { init } from '@tracekit/browser';
import { replayIntegration } from '@tracekit/replay';

init({
  apiKey: 'your-api-key',
  addons: [replayIntegration()],
});

How It Works

Configuration Reference

Pass a ReplayConfig object to replayIntegration(). All options are optional -- defaults are privacy-first and production-ready.

Annotated Configuration

import { replayIntegration } from '@tracekit/replay';

const replay = replayIntegration({
  // Sampling
  sessionSampleRate: 0.1,        // 10% of all sessions (default: 0.1)
  errorSampleRate: 0.0,          // Error-triggered capture disabled (default: 0.0)

  // Privacy
  unmask: [],                    // CSS selectors to unmask (default: [])

  // Session lifecycle
  idleTimeout: 1800000,          // 30 minutes before session ends (default: 1800000)

  // Transport
  flushInterval: 30000,          // Upload every 30 seconds (default: 30000)
  maxBufferSize: 24117248,       // 23MB max buffer size (default: 24117248)

  // Media
  inlineImages: false,           // Capture images as base64 data URIs (default: false)
  blockMedia: true,              // Block img/video/canvas/svg/iframe (default: true)
});

Options Reference

Option Details

Privacy Controls

Session replay is privacy-first by design. All text content, input values, and media are masked by default. You opt in to showing content, not opt out.

Default Behavior

Unmasking Specific Elements

Use CSS selectors in the unmask config option to reveal specific content that is safe to record.

replayIntegration({
  unmask: [
    '.public-content',    // Marketing copy, product titles
    '.product-title',     // Product names on e-commerce pages
    '.nav-label',         // Navigation menu labels
    'h1', 'h2', 'h3',    // All headings
  ],
})

You can also unmask individual elements with an HTML attribute:

<p data-tracekit-unmask>This text will be visible in the replay.</p>

Always Masked (No Override)

Recommended Approach

Sampling

Session replay provides two independent sampling modes. A session can be captured by either mode -- they do not conflict.

Example Configurations

replayIntegration({
  sessionSampleRate: 0.1,   // Record 10% of sessions
  errorSampleRate: 1.0,     // Always capture replay for errors
})

replayIntegration({
  sessionSampleRate: 1.0,   // Record every session
  errorSampleRate: 0.0,     // No error-only capture needed
})

replayIntegration({
  sessionSampleRate: 0.01,  // Record 1% of sessions
  errorSampleRate: 1.0,     // Always capture replay for errors
})

Sampling Interaction

API Reference

All exports are available from @tracekit/replay.

import { replayIntegration } from '@tracekit/replay';

const replay = replayIntegration({
  sessionSampleRate: 0.1,
  errorSampleRate: 1.0,
});

init({ apiKey: 'your-api-key', addons: [replay] });

const replay = replayIntegration();
init({ apiKey: 'your-api-key', addons: [replay] });

// Later, on a critical action:
document.getElementById('checkout')?.addEventListener('click', () => {
  replay.flush();
});

const replay = replayIntegration();
init({ apiKey: 'your-api-key', addons: [replay] });

const sessionId = replay.getSessionId();
if (sessionId) {
  console.log('Replay session:', sessionId);
}

ReplayConfig Type

Playback UI

The replay viewer in the TraceKit dashboard provides a full-featured playback experience for recorded sessions.

Session Card Metadata

Each session card in the replay list shows enriched metadata automatically collected by the SDK and backend:

Network Request Details

The network tab in the replay viewer shows all HTTP requests made during the session, synchronized with the playback timeline. Each request displays:

When distributed tracing is enabled (via tracePropagationTargets in the browser SDK config), network requests that include a traceparent header show a "View Backend Trace" link. Clicking it opens the distributed trace waterfall for that exact API call, connecting the frontend replay to the backend execution.

Console Output

The console tab displays all console.log, console.warn, and console.error output, synchronized with the replay playback position. Error-level entries include expandable stack traces. Object arguments are displayed as expandable trees.

Error Integration

When both @tracekit/browser and @tracekit/replay are installed, errors and replays are automatically linked. No additional configuration is required.

How It Works

"View Replay" Button

On the error detail page in the dashboard, a "View Replay" button appears when a replay_id is present on the error. Clicking it opens the session replay positioned 5 seconds before the error occurred (pre-roll), so you can see exactly what the user was doing leading up to the error.

Error Sampling Flow

When errorSampleRate is greater than 0, the SDK operates in "buffer" mode for sessions that were not selected by session sampling. In buffer mode:

• Replay events are captured into a 60-second ring buffer (older events are evicted by timestamp).
• No data is uploaded until an error occurs.
• When an error is captured, the ring buffer contents are flushed and uploaded as a compressed chunk.
• After the flush, the session transitions to full recording mode for the remainder of the session.

This approach gives you full replay context for error sessions with minimal storage cost -- you only pay for sessions where errors actually occurred.

Troubleshooting

replayIntegration({
  unmask: ['.public-content', '.product-title', 'h1', 'h2'],
})

Complete Example

A production-ready setup with @tracekit/browser and @tracekit/replay together.

import { init, captureException, setUser } from '@tracekit/browser';
import { replayIntegration } from '@tracekit/replay';

// 1. Create the replay integration with production config
const replay = replayIntegration({
  sessionSampleRate: 0.1,       // Record 10% of sessions
  errorSampleRate: 1.0,         // Always capture replay for errors
  unmask: [
    '.public-content',          // Marketing copy
    '.product-title',           // Product names
    'h1', 'h2', 'h3',          // Headings
    '.nav-label',               // Navigation labels
  ],
});

// 2. Initialize the browser SDK with replay as an addon
init({
  apiKey: process.env.TRACEKIT_API_KEY!,
  release: process.env.APP_VERSION || '0.0.0',
  environment: process.env.NODE_ENV || 'production',
  tracePropagationTargets: [
    'https://api.myapp.com',
    /^https:\/\/.*\.myapp\.com/,
  ],
  addons: [replay],
});

// 3. Set user context after authentication
async function onLogin(email: string, password: string) {
  const user = await api.login(email, password);
  setUser({ id: user.id, email: user.email });
}

// 4. Manual error capture -- replay_id is attached automatically
async function loadDashboard() {
  try {
    const data = await api.fetchDashboard();
    renderDashboard(data);
  } catch (err) {
    captureException(err as Error);
    showErrorFallback();
  }
}

// 5. Force flush on critical user actions
document.getElementById('checkout')?.addEventListener('click', () => {
  replay.flush();
});

// 6. Access the session ID for custom integrations
const sessionId = replay.getSessionId();
if (sessionId) {
  analytics.track('session_started', { replayId: sessionId });
}