RUM Setup Guide

This guide will walk you through setting up OpenObserve RUM in your web application.

Prerequisites

A running OpenObserve instance
A web application where you want to add RUM monitoring
npm or yarn package manager

Step 1: Install Required Packages

Install the OpenObserve browser packages:

npm install @openobserve/browser-rum @openobserve/browser-logs

Or using yarn:

yarn add @openobserve/browser-rum @openobserve/browser-logs

Step 2: Get Your Client Token

Log in to your OpenObserve instance
Navigate to Ingestion menu
Select RUM or Custom ingestion
Copy your client token - you'll need this for configuration

Step 3: Initialize RUM

Add the following code to your application's entry point (e.g., main.js, index.js, or App.vue):

import { openobserveRum } from '@openobserve/browser-rum';
import { openobserveLogs } from '@openobserve/browser-logs';

const options = {
  clientToken: 'your-client-token-here', // Get this from the Ingestion page
  applicationId: 'web-application-id',
  site: 'localhost:5080', // Your OpenObserve instance URL
  service: 'my-web-application',
  env: 'production', // or 'development', 'staging', etc.
  version: '0.0.1',
  organizationIdentifier: 'default',
  insecureHTTP: true, // Set to false if using HTTPS
  apiVersion: 'v1',
};

// Initialize RUM
openobserveRum.init({
  applicationId: options.applicationId,
  clientToken: options.clientToken,
  site: options.site,
  organizationIdentifier: options.organizationIdentifier,
  service: options.service,
  env: options.env,
  version: options.version,
  trackResources: true,
  trackLongTasks: true,
  trackUserInteractions: true,
  apiVersion: options.apiVersion,
  insecureHTTP: options.insecureHTTP,
  defaultPrivacyLevel: 'allow' // 'allow' or 'mask-user-input' or 'mask'
});

// Initialize Logs
openobserveLogs.init({
  clientToken: options.clientToken,
  site: options.site,
  organizationIdentifier: options.organizationIdentifier,
  service: options.service,
  env: options.env,
  version: options.version,
  forwardErrorsToLogs: true,
  insecureHTTP: options.insecureHTTP,
  apiVersion: options.apiVersion,
});

// Set user context (optional)
openobserveRum.setUser({
  id: "1",
  name: "Captain Hook",
  email: "captainhook@example.com",
});

// Start session replay recording
openobserveRum.startSessionReplayRecording();

Step 4: Configuration Options

RUM Configuration Options

Option	Type	Required	Description
`applicationId`	string	Yes	A unique identifier for your application
`clientToken`	string	Yes	Your OpenObserve client token from Ingestion page
`site`	string	Yes	Your OpenObserve instance URL (e.g., 'openobserve.example.com ')
`organizationIdentifier`	string	Yes	Your organization identifier (usually 'default')
`service`	string	Yes	Name of your service/application
`env`	string	Yes	Environment (e.g., 'production', 'staging', 'development')
`version`	string	Yes	Version of your application
`trackResources`	boolean	No	Track loading of resources (images, scripts, CSS). Default: false
`trackLongTasks`	boolean	No	Track long-running JavaScript tasks. Default: false
`trackUserInteractions`	boolean	No	Track clicks, form submissions, etc. Default: false
`defaultPrivacyLevel`	string	No	Privacy level: 'allow', 'mask-user-input', or 'mask'. Default: 'mask-user-input'
`insecureHTTP`	boolean	No	Set to true for HTTP, false for HTTPS. Default: false
`apiVersion`	string	No	API version to use. Default: 'v1'

Privacy Levels

Choose the appropriate privacy level for your application:

allow: Record all content including user input
mask-user-input: Mask form inputs but show other content (recommended)
mask: Mask all user input and text content

Logs Configuration Options

Option	Type	Required	Description
`clientToken`	string	Yes	Your OpenObserve client token
`site`	string	Yes	Your OpenObserve instance URL
`organizationIdentifier`	string	Yes	Your organization identifier
`service`	string	Yes	Name of your service
`env`	string	Yes	Environment
`version`	string	Yes	Application version
`forwardErrorsToLogs`	boolean	No	Automatically forward errors to logs. Default: true
`insecureHTTP`	boolean	No	Set to true for HTTP. Default: false
`apiVersion`	string	No	API version. Default: 'v1'

Step 5: Set User Context (Optional)

You can associate RUM data with specific users by setting user context:

openobserveRum.setUser({
  id: "user-123",
  name: "John Doe",
  email: "john.doe@example.com",
  // Add any custom attributes
  plan: "premium",
  signup_date: "2024-01-15"
});

To clear user context (e.g., on logout):

openobserveRum.clearUser();

Step 6: Start Session Replay

Session replay recording can be started in two ways:

Automatic Recording

Start recording for all sessions:

openobserveRum.startSessionReplayRecording();

Conditional Recording

Start recording only for specific sessions (e.g., when an error occurs):

// Start recording only when needed
if (userEncounteredError) {
  openobserveRum.startSessionReplayRecording({ force: true });
}

Stopping Session Replay

To stop recording:

openobserveRum.stopSessionReplayRecording();

Framework-Specific Integration

Vue.js

Add initialization in your main.js or main.ts:

import { createApp } from 'vue'
import App from './App.vue'
import { openobserveRum } from '@openobserve/browser-rum'
import { openobserveLogs } from '@openobserve/browser-logs'

// Initialize RUM
openobserveRum.init({
  // ... configuration
});

openobserveLogs.init({
  // ... configuration
});

const app = createApp(App)
app.mount('#app')

React

Add initialization in your index.js or index.tsx:

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import { openobserveRum } from '@openobserve/browser-rum';
import { openobserveLogs } from '@openobserve/browser-logs';

// Initialize RUM
openobserveRum.init({
  // ... configuration
});

openobserveLogs.init({
  // ... configuration
});

ReactDOM.render(<App />, document.getElementById('root'));

Angular

Add initialization in your main.ts:

import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';
import { openobserveRum } from '@openobserve/browser-rum';
import { openobserveLogs } from '@openobserve/browser-logs';

// Initialize RUM
openobserveRum.init({
  // ... configuration
});

openobserveLogs.init({
  // ... configuration
});

platformBrowserDynamic().bootstrapModule(AppModule);

Vanilla JavaScript

Add the script in your HTML file or main JavaScript file:

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <div id="app"></div>

  <script type="module">
    import { openobserveRum } from '@openobserve/browser-rum';
    import { openobserveLogs } from '@openobserve/browser-logs';

    // Initialize RUM
    openobserveRum.init({
      // ... configuration
    });

    openobserveLogs.init({
      // ... configuration
    });

    openobserveRum.startSessionReplayRecording();
  </script>
</body>
</html>

Step 7: Verify Installation

After deploying your application with RUM enabled:

Open your application in a browser
Perform some interactions (navigate pages, click buttons, etc.)
Log in to OpenObserve
Navigate to the RUM section
You should see data appearing in:
- Performance tab (metrics and web vitals)
- Sessions tab (your session)
- Error Tracking tab (if any errors occurred)

Troubleshooting

No Data Appearing

If you don't see any RUM data:

Check console for errors: Open browser DevTools and look for any error messages
Verify client token: Ensure your client token is correct
Check network requests: Look for requests to your OpenObserve instance in the Network tab
Verify site URL: Ensure the site option matches your OpenObserve instance URL
Check CORS settings: Make sure your OpenObserve instance allows requests from your application domain

Session Replay Not Recording

If session replay is not working:

Verify initialization: Ensure startSessionReplayRecording() is called after openobserveRum.init()
Check privacy settings: defaultPrivacyLevel affects what is recorded
Browser compatibility: Ensure you're using a modern browser that supports session replay
Force recording: If session is sampled out of replay, apply { force: true } to force recording:
```
openobserveRum.startSessionReplayRecording({ force: true });
```

Performance Impact

RUM is designed to have minimal impact on your application:

Asynchronous: Data collection happens asynchronously
Batching: Events are batched before sending
Small bundle size: The RUM SDK is lightweight
Sampling: You can configure sampling rates to reduce data volume

Advanced Configuration

Custom Sampling

Control which sessions are tracked:

openobserveRum.init({
  // ... other options
  sessionSampleRate: 100, // Track 100% of sessions
  sessionReplaySampleRate: 50, // Record 50% of sessions
});

Manual Error Tracking

Send custom errors:

try {
  // Your code
} catch (error) {
  openobserveLogs.logger.error('Custom error message', {
    error: error,
    context: 'additional context'
  });
}

Custom Actions

Track custom user actions:

openobserveRum.addAction('button_clicked', {
  button_name: 'subscribe',
  page: 'homepage'
});

Next Steps

Performance Monitoring - Learn about performance metrics
Session Tracking - Understand session data
Error Tracking - Track and debug errors
Session Replay - Use session replay effectively
Metrics Reference - Complete metrics documentation

On this page