Connect RUM

This capability is only available to BYOC deployments. Check out our pricing page for more information about subscription plans and the available deployment modes.

groundcover’s Real User Monitoring (RUM) SDK allows you to capture front-end performance data, user events, and errors from your web applications.

Start capturing RUM data by installing the browser SDK in your web app.

This guide will walk you through installing the SDK, initializing it, identifying users, sending custom events, capturing exceptions, and configuring optional settings.

Install the SDK

npm install @groundcover/browser
# or
yarn add @groundcover/browser

Initialize the SDK

Initialization

import groundcover from '@groundcover/browser';

groundcover.init({
  apiKey: 'your-ingestion-key',
  cluster: 'your-cluster',
  environment: 'production',
  dsn: 'your-dsn',
  appId: 'your-app-id',
});

Configuration Parameters

apiKey	A dedicated Ingestion Key of type RUM (Settings -> Access -> Ingestion Keys)
dsn	Your public groundcover endpoint in the format of https://example.platform.grcv.io , where example.platform.grcv.io is your ingress.site installation value.
cluster	Identifier for your cluster; helps filter RUM data by specific cluster.
environment	Environment label (e.g., production, staging) used for filtering data.
appId	Custom application identifier set by you; useful for filtering and segmenting data on a single application level later.

Advanced Configuration

You can customize SDK behavior (event sampling, data masking, enabled events). The following properties are customizable:

export interface SDKOptions {
  batchSize: number;
  batchTimeout: number;
  eventSampleRate: number;
  sessionSampleRate: number;
  environment: string;
  debug: boolean;
  tracePropagationUrls: string[];
  beforeSend: (event: Event) => boolean;
  enabledEvents: Array<"dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance">;
  excludedUrls: [];
}

You can pass the values by calling the init function:

groundcover.init({
  apiKey: 'your-ingestion-key',
  cluster: 'your-cluster',
  environment: 'production',
  dsn: 'your-dsn',
  appId: 'your-app-id',
  releaseId: 'your-release-identifier'
  options: {
    batchSize: 50,
    sessionSampleRate: 0.5, // 50% sessions sampled
    eventsSampleRate: 0.5,
  },
});

Or via the updateConfig function:

groundcover.updateConfig({
   batchSize: 20,
});

Identify Users

Link RUM data to specific users:

groundcover.identifyUser({
  id: 'user-id',
  email: '[email protected]',
});

Send Custom Events

Instrument key user interactions:

groundcover.sendCustomEvent({
  event: 'PurchaseCompleted',
  attributes: { orderId: 1234, amount: 99.99 },
});

Capture Exceptions

Manually track caught errors:

try {
  performAction();
} catch (error) {
  groundcover.captureException(error);
}

Source Maps

Source maps map minified/bundled code back to your original source files. With them, stack traces in RUM (e.g. in session details and exceptions) show your real file names, line numbers, and function names instead of bundle names and minified positions.

Please note that this feauture is in gradual release phases. Please be in touch with teh groundcover team to ensure it's enabled in your account

Pre-condition - source maps were enabled in your CI operation.

To enable source maps in your account, follow these steps:

1. Enable source maps ingestion - in the BYOC ingestor, add the following snippet to its YAML configuration

    sourceMaps:
      enabled: false              # disabled by default
      port: 8027                  # default: 8027
      provider: "s3"              # default: "s3". The source maps storage provider
      region: ""                  # default: "". The provider region
      storageAccount: ""          # default: "" (must be provided for Azure)
      maxUploadSize: 100MB        # max source map to be accepted

1. Upload source maps from your CI job via the API - Add a call to this endpoint

POST /api/rum/sourcemaps
Content-Type: multipart/form-data

form-data fields:

• app_id - your application identifier (alphanumeric, dots, hyphens, underscores), as provided in the RUM init call.

• release_id - the release/version being deployed (same character restrictions), as provided in the RUM init call.

• file - the source map file

Authentication will be done using API key (same as other groundcover API calls).

Here is an example of source maps uploading using curl:

curl -X POST "https://<groundcover-endpoint>/api/rum/sourcemaps" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-Backend-Id: $BACKEND_ID" \
-F "app_id=my-web-app" \
-F "release_id=1.2.3" \
-F "file=@./dist/main.js.map" 

groundcover-endpoint will be app.groundcover.com for BYOC customers.

Response (201):

{
"status": "uploaded",
"app_id": "my-web-app",
"release_id": "1.2.3",
"filename": "main.js.map",
"size_bytes": 524288
}

Files will be stored in the selected provider at the path: sourcemaps/<app_id>/<release_id>/<filename> . Every new RUM trace that holds a stack trace will be automatically converted based on the source map.

Session Replay

Enable session recording in order to replay your users behavior and see the actions that led to specific RUM events.

How to set it up?

Session replay requires enabling the RUM SDK

Add the following instrumentation to your code:

groundcover.startReplayRecording();

For example, you can add the above once the user navigated to a specific page or upon a session start.

Add the following if there is a need to stop the recording, e.g. before a sensitive section in your app.

groundcover.stopReplayRecording();

Recording will be stored on your BYOC server and will be deleted along with the RUM session, in accordance to your retention policy.

Viewing sessions

In the summary page, you will see an indication next to sessions with a recording.

Within the drawer, open the Session Replay tab to see the recording

In case there is a need to mask elements in the session, add any of the following to your HTML

• .rr-ignore - no input events recorded

• .rr-block - elements will not be recorded, instead a placeholder will be shown

• .rr-mask - text will be replaced with *