// rum-init.js
import { initRUM } from '@your-rum-sdk/core';
import { reportWebVitals } from 'web-vitals';

function initializeRUM() {
  const config = {
    applicationId: process.env.RUM_APP_ID,
    clientToken: process.env.RUM_CLIENT_TOKEN,
    site: process.env.RUM_SITE || 'us',
    service: process.env.APP_NAME,
    env: process.env.NODE_ENV,
    version: process.env.APP_VERSION,
    trackInteractions: true,
    trackResources: true,
    trackLongTasks: true,
    // Performance budget: skip heavy tracking if LCP > 2.5s
    beforeSend: (event) => {
      if (window.__rumLCP > 2500 && event.type === 'resource') {
        return false; // Drop resource events on slow loads
      }
      return true;
    }
  };

  const rum = initRUM(config);

  // Stream Core Web Vitals
  reportWebVitals((metric) => {
    rum.addPerformanceMetric(metric.name, metric.value, {
      rating: metric.rating,
      navigationType: metric.navigationType
    });
  });

  return rum;
}

// Defer initialization until first paint
if ('requestIdleCallback' in window) {
  requestIdleCallback(() => initializeRUM(), { timeout: 2000 });
} else {
  window.addEventListener('load', () => setTimeout(initializeRUM, 100));
}

// sampling.js
export function configureSampling(rum) {
  const samplingRules = {
    // 100% capture for authenticated users on checkout
    authenticatedCheckout: (ctx) => ctx.user?.isAuthenticated && ctx.route?.includes('/checkout'),
    // 30% capture for public browsing
    publicBrowsing: (ctx) => !ctx.user?.isAuthenticated,
    // 100% capture if errors detected in session
    errorDriven: (ctx) => ctx.session?.errorCount > 0
  };

  rum.configureSampling({
    defaultRate: 0.3,
    rules: Object.entries(samplingRules).map(([name, predicate]) => ({
      name,
      predicate,
      sampleRate: name.includes('authenticated') || name.includes('error') ? 1.0 : 0.3
    })),
    fallback: 'probabilistic' // Uses hash(sessionId) for consistency
  });

  // Attach deterministic session context
  rum.setGlobalContext({
    sessionId: crypto.randomUUID(),
    userId: window.__currentUser?.id || 'anonymous',
    tenantId: window.__appConfig?.tenant,
    featureFlags: window.__featureFlags || {}
  });
}

. Custom Business Events & Funnel Tracking

Map technical telemetry to business outcomes. Track conversion steps, payment attempts, and feature adoption without blocking the main thread.

// business-events.js
export function trackBusinessEvents(rum) {
  const funnelSteps = {
    product_view: { category: 'commerce', priority: 'high' },
    add_to_cart: { category: 'commerce', priority: 'high' },
    checkout_start: { category: 'commerce', priority: 'critical' },
    payment_initiated: { category: 'commerce', priority: 'critical' },
    payment_success: { category: 'commerce', priority: 'critical' }
  };

  window.addEventListener('business_event', (e) => {
    const { step, metadata = {} } = e.detail;
    const config = funnelSteps[step];
    if (!config) return;

    rum.addUserEvent(step, {
      ...metadata,
      category: config.category,
      timestamp: Date.now(),
      route: window.location.pathname,
      deviceClass: navigator.userAgentData?.mobile ? 'mobile' : 'desktop'
    });
  });
}

4. Error & Exception Capture with Stack Trace Sanitization

Capture unhandled errors, promise rejections, and resource failures. Sanitize PII and strip source maps in production.

// error-tracking.js
export function configureErrorTracking(rum) {
  // Override global handlers
  window.onerror = (message, source, lineno, colno, error) => {
    rum.addError(error || new Error(message), {
      source: 'unhandled_exception',
      lineno,
      colno,
      stack: error?.stack?.replace(/\/\/[^/]+\/[^/]+\//g, '[REDACTED]')
    });
  };

  window.onunhandledrejection = (event) => {
    rum.addError(event.reason, { source: 'unhandled_promise_rejection' });
  };

  // Resource failures
  window.addEventListener('error', (event) => {
    if (event.target?.tagName === 'SCRIPT' || event.target?.tagName === 'LINK') {
      rum.addError(new Error(`Failed to load ${event.target.src || event.target.href}`), {
        source: 'resource_load_failure',
        tagName: event.target.tagName,
        url: event.target.src || event.target.href
      });
    }
  }, true);
}

5. Privacy & Consent Gating

Instrumentation must respect user consent states. Delay telemetry emission until explicit permission is granted.

// privacy-gating.js
export function configurePrivacy(rum, consentManager) {
  const consentState = consentManager.getConsent(); // Returns { analytics: boolean, personalization: boolean }

  if (!consentState.analytics) {
    rum.pause(); // Suspend all telemetry
    consentManager.onConsentChange((newConsent) => {
      if (newConsent.analytics) {
        rum.resume();
      } else {
        rum.pause();
      }
    });
  }

  // Strip PII from all payloads
  rum.addBeforeSend((event) => {
    const sensitiveKeys = ['email', 'phone', 'address', 'token', 'ssn', 'password'];
    const recursiveStrip = (obj) => {
      if (typeof obj !== 'object' || obj === null) return obj;
      Object.keys(obj).forEach(key => {
        if (sensitiveKeys.includes(key.toLowerCase())) {
          obj[key] = '[REDACTED]';
        } else if (typeof obj[key] === 'object') {
          recursiveStrip(obj[key]);
        }
      });
      return obj;
    };
    return recursiveStrip(event);
  });
}

---

Pitfall Guide

1. Over-Instrumentation & Payload Bloat

Logging every click, scroll, and network request creates massive payloads that degrade performance and inflate storage costs. Mitigation: Implement event sampling, debounce high-frequency actions, and use beforeSend to drop low-value telemetry. Prioritize business-critical paths over exhaustive logging.

2. Ignoring Privacy & Consent Frameworks

Shipping RUM without consent gating violates GDPR, CCPA, and emerging AI/data regulations. Unfiltered PII in telemetry creates legal liability. Mitigation: Integrate with a CMP, gate initialization behind consent states, sanitize payloads server-side and client-side, and maintain audit trails of consent changes.

3. Static Sampling Strategies

Fixed sampling rates (e.g., 10% everywhere) miss high-value sessions (checkout failures, enterprise users) and waste budget on healthy browsing. Mitigation: Use adaptive sampling based on user tier, route complexity, error presence, and conversion stage. Maintain deterministic hashing for session consistency.

4. Missing Session & User Context Correlation

Telemetry without session IDs, user attributes, or feature flags becomes unactionable noise. Engineers cannot reproduce issues or segment impact. Mitigation: Attach deterministic session IDs, propagate trace headers to the client, enrich events with tenant/user metadata, and ensure backend services return correlation IDs in API responses.

5. Firehose Data Without Alerting Thresholds

Collecting data is not monitoring. Without calibrated alerts, teams experience alert fatigue or miss regressions until customer complaints spike. Mitigation: Define SLOs per route/user segment, use rolling window anomaly detection, alert on error rate deltas rather than absolute values, and tie alerts to deployment pipelines.

6. Treating RUM as Siloed Frontend Observability

Client metrics divorced from backend traces create blind spots. A slow API response appears as a frontend timeout without root cause visibility. Mitigation: Propagate W3C Trace Context headers to the browser, inject backend trace IDs into RUM events, and build unified dashboards that join client sessions with service spans.

7. Neglecting Mobile & Cross-Platform Parity

Web RUM configs rarely translate to React Native, Flutter, or native iOS/Android. Inconsistent instrumentation breaks cross-platform SLOs. Mitigation: Abstract telemetry into a shared SDK layer, standardize event schemas across platforms, and enforce parity in sampling, privacy, and error capture rules during PR reviews.

---

Production Bundle

✅ Pre-Launch Checklist

• RUM SDK initialized post-first-paint with performance budget gating
• Dynamic sampling rules configured per user tier & route
• Core Web Vitals + custom business events wired to telemetry pipeline
• Error handlers capture unhandled exceptions, promise rejections, resource failures
• Session IDs deterministic; user/tenant context enriched
• Consent gating integrated with CMP; PII sanitization active
• Trace context propagation configured for backend correlation
• Alert thresholds defined per SLO; deployment pipeline hooks tested
• Data retention policy aligned with compliance & cost targets
• Load testing validates RUM overhead < 2% CPU / < 50KB payload/session

📊 Decision Matrix

Scenario	Recommended Approach	Rationale
High-traffic consumer app	Adaptive sampling (10–30% baseline, 100% on errors/checkout)	Balances cost with conversion-critical visibility
Enterprise SaaS	100% capture for authenticated users, 10% for public	Enterprise SLAs require full session reproducibility
Strict privacy jurisdiction	Gated init + server-side PII stripping + short retention (7d)	Compliance-first; minimizes legal exposure
Microservices architecture	W3C Trace Context propagation + unified dashboard	End-to-end correlation across frontend/backend
Mobile + Web parity	Shared telemetry SDK + schema validation in CI	Consistent SLOs across platforms
Budget-constrained team	Web Vitals + error tracking only; defer custom events	Lowest overhead, highest ROI for initial rollout

⚙️ Config Template

// rum.config.js
export const RUM_CONFIG = {
  applicationId: process.env.RUM_APP_ID,
  clientToken: process.env.RUM_CLIENT_TOKEN,
  env: process.env.NODE_ENV,
  version: process.env.APP_VERSION,
  service: process.env.APP_NAME,
  
  // Performance
  trackInteractions: true,
  trackResources: false, // Enable only for critical routes
  trackLongTasks: true,
  beforeSend: 'filter-heavy-payloads',
  
  // Sampling
  sampling: {
    defaultRate: 0.2,
    rules: [
      { name: 'checkout', predicate: 'route.includes("/checkout")', rate: 1.0 },
      { name: 'authenticated', predicate: 'user.isAuthenticated', rate: 0.5 },
      { name: 'error-session', predicate: 'session.errorCount > 0', rate: 1.0 }
    ]
  },
  
  // Privacy
  privacy: {
    consentRequired: true,
    piiKeys: ['email', 'phone', 'token', 'address'],
    retentionDays: 30,
    anonymizeIp: true
  },
  
  // Errors
  errors: {
    captureUnhandled: true,
    captureRejections: true,
    captureResources: true,
    stackSanitization: true
  },
  
  // Correlation
  correlation: {
    propagateTraceHeaders: true,
    injectBackendTraceId: true,
    sessionAttribute: 'sessionId'
  }
};

🚀 Quick Start (5-Minute Setup)

1. Install SDK: npm install @your-rum-sdk/core web-vitals
2. Create Config: Copy rum.config.js to your project root. Set environment variables for RUM_APP_ID and RUM_CLIENT_TOKEN.
3. Initialize: Add rum-init.js to your app entry point. Wrap initialization in requestIdleCallback or window.addEventListener('load').
4. Wire Events: Add trackBusinessEvents.js and configureErrorTracking.js. Import and call in your main module.
5. Deploy & Validate: Push to staging. Verify telemetry in the RUM dashboard. Confirm sampling rules fire. Test consent gating. Set up one alert for error_rate > 2% over 5m. Promote to production.

---

Real user monitoring is not a plugin; it is a data pipeline. When architected with sampling discipline, privacy boundaries, session correlation, and business alignment, RUM transforms client telemetry from operational noise into a strategic feedback loop. Implement the patterns above, validate against your SLOs, and iterate. The observability gap closes when telemetry meets intention.