@9apes/rum-sdk

Real User Monitoring by 9Apes

Production-grade RUM SDK for tracking performance, errors, user behavior, and session replay — all in one lightweight package.

Overview

@9apes/rum-sdk is part of the 9Apes observability platform. It captures real user data from your web applications and streams it to your 9Apes dashboard, giving you full visibility into how your product performs in the wild.

A valid 9Apes API key is required. Get yours at 9apes.com.

What it tracks

• Core Web Vitals — CLS, INP, FCP, LCP, TTFB
• Errors — JS exceptions, resource errors, unhandled promise rejections with full stack traces and severity classification
• Performance — Navigation timing, resource timing, memory usage
• User behavior — Clicks, scrolls, form interactions, rage click detection, automatic action tracking
• Network — Fetch/XHR request monitoring
• Session replay — rrweb-based full session recording with privacy controls and console capture
• CPU monitoring — Frame-based CPU usage estimation with dropped frame detection
• Long Animation Frames — Script-level attribution for UI jank (Chrome 123+)

Installation

pnpm add @9apes/rum-sdk

Quick Start

import { initWatchdog } from '@9apes/rum-sdk';

initWatchdog({
  apiKey: 'YOUR_API_KEY',
  env: 'production',     // optional — filter by environment in the dashboard
  userId: 'user-123',    // optional
});

That's it. With just an API key, the SDK automatically begins collecting Web Vitals, errors, performance data, and user behavior. All data is batched and sent to your 9Apes dashboard.

Configuration

Required

| Field | Type | Description | | -------- | -------- | ------------------------------------------------------- | | apiKey | string | Your 9Apes API key. Obtain from the 9Apes dashboard. |

Optional

initWatchdog({
  apiKey: 'YOUR_API_KEY',

  // Identity & environment
  userId: 'user-123',
  env: 'production',        // Sent with every event — filter by environment in the dashboard

  // Sampling (cost control)
  sampleRate: 100,                    // % of sessions to track (0-100, default: 100)
  sessionRecordingSampleRate: 50,     // % of tracked sessions with session replay (0-100, default: 100)

  // Feature toggles
  enableWebVitals: true,
  enableErrorTracking: true,
  enablePerformanceTracking: true,
  enableBehaviorTracking: true,
  enableBusinessMetrics: true,
  enableSessionRecording: false,

  // Privacy
  enablePrivacyMode: false,
  sensitiveSelectors: ['.credit-card', '#ssn'],
  maskAllInputs: true,

  // Console recording (when session recording is on)
  enableConsoleRecording: true,
  consoleRecordingLevels: ['log', 'warn', 'error', 'info', 'debug'],

  // Error behavior
  sendCriticalErrorsImmediately: true,

  // Action tracking
  enableActionTracking: true,
  actionAttributeName: 'data-watchdog-action',
  excludeActionSelectors: ['.ignore-tracking'],

  // Debugging
  debug: false,
});

API Reference

Core

initWatchdog(config: WatchdogConfig): void

Initialize the SDK. Must be called before any other function.

destroyWatchdog(): void

Tear down the SDK, flush remaining events, and release all resources.

Tracking

trackFeatureUsage(featureName: string, context?: object): void

Track product feature adoption.

trackFeatureUsage('export-pdf', { format: 'a4', pages: 10 });

trackConversion(event: string, value?: number, metadata?: object): void

Track conversion and revenue events.

trackConversion('purchase', 99.99, { productId: '123', quantity: 2 });

trackError(error: Error | string, context?: object): void

Manually report an error (useful for framework-level error boundaries).

trackError(error, { component: 'Checkout', info: 'Payment failed' });

addCustomBreadcrumb(message: string, data?: object): void

Add a breadcrumb for richer error context.

addCustomBreadcrumb('User clicked checkout', { cartItems: 3, total: 149.99 });

Session Control

pauseRecording(): void

Pause session recording — use on sensitive screens (e.g. payment forms).

resumeRecording(): void

Resume session recording.

updateUserId(userId: string): void

Update the user ID after login or authentication.

Utilities

forceFlush(): void

Immediately flush all buffered events to the 9Apes backend.

getAnalyticsStatus(): object | null

Returns current SDK status.

const status = getAnalyticsStatus();
// {
//   isRecording: true,
//   sessionId: '...',
//   bufferSize: 5,
//   collectors: ['WebVitalsCollector', 'ErrorCollector', ...]
// }

Middleware System

Extend the event pipeline with custom middleware. Three hooks are available:

| Hook | Purpose | | ---------------- | -------------------------------------------- | | onPreCollect | Filter or modify events before collection | | onPostCollect | Enrich events after collection | | onPreSend | Transform the full batch before transmission |

import { registerMiddleware } from '@9apes/rum-sdk';

registerMiddleware({
  name: 'build-tagger',

  onPostCollect(event) {
    return { ...event, buildVersion: '2.1.0' };
  },

  onPreSend(batch) {
    return { ...batch, metadata: { release: 'v2.1.0' } };
  },
});

Built-in Middleware

The SDK ships with enrichers that run automatically:

• BreadcrumbEnricher — attaches breadcrumb trail to error events
• SessionEnricher — adds session-level metrics
• ViewportEnricher — adds device category and viewport dimensions
• ConnectionEnricher — adds network quality classification

Framework Integrations

React

import { useEffect } from 'react';
import { initWatchdog, updateUserId } from '@9apes/rum-sdk';

function App() {
  useEffect(() => {
    initWatchdog({ apiKey: process.env.REACT_APP_9APES_KEY! });
  }, []);

  const handleLogin = (user) => {
    updateUserId(user.id);
  };

  return <YourApp />;
}

Next.js

// app/providers.tsx  (or pages/_app.tsx)
import { useEffect } from 'react';
import { initWatchdog } from '@9apes/rum-sdk';

export function Providers({ children }) {
  useEffect(() => {
    initWatchdog({ apiKey: process.env.NEXT_PUBLIC_9APES_KEY! });
  }, []);

  return <>{children}</>;
}

Vue

import { createApp } from 'vue';
import { WatchdogVuePlugin } from '@9apes/rum-sdk';
import App from './App.vue';

const app = createApp(App);

app.use(WatchdogVuePlugin, {
  apiKey: import.meta.env.VITE_9APES_KEY,
});

app.mount('#app');

License

This software is proprietary and provided under a commercial license by 9Apes Technologies. Unauthorized copying, modification, distribution, or use of this software outside the terms of your subscription agreement is strictly prohibited.

Refer to your service agreement or contact [email protected] for licensing details.

Support

| Channel | Details | | ------------------------ | ---------------------------------------------------- | | Documentation | docs.9apes.com | | Email | [email protected] | | Dashboard | app.9apes.com |

For enterprise support plans and SLAs, contact your account manager.