Table of Contents

• Overview
• What Gets Collected
• Quick Start
• Installation Modes
• Configuration
• Public API
• Telemetry Schema Reference
• Trace Context Propagation
• Build and Local Run
• Contributor Appendix
• Browser Support
• License

Overview

The SDK loads modules dynamically based on a decide endpoint response:

1. Loader script is added to the page (vunet-rum-loader.js).
2. Loader calls decide API and evaluates sampling.
3. Core RUM and/or Session Replay modules are loaded conditionally.
4. Modules initialize and begin telemetry collection/export.

Bundles

• dist/vunet-rum-loader.js: loader/entrypoint
• dist/vunet-rum-core.js: tracing + logs instrumentation
• dist/vunet-rum-session-replay.js: rrweb-based replay capture
• dist/vunet-rum.js: backward-compatible alias of loader

What Gets Collected

Automatic instrumentation includes:

• Document/page load spans and resource timing
• Fetch and XHR spans
• User interaction spans
• SPA route-change spans
• Long-task spans
• Browser error logs (uncaught exception, unhandled rejection, document errors, console errors, custom errors)
• Session replay events (when enabled by sampling)

Quick Start

<script
  id="vunet-rum"
  async
  crossorigin="anonymous"
  src="https://cdn.vunet.ai/rum/vunet-rum-loader.js"
  data-collection-source-url="https://collector.example.com/rum"
  data-service-name="my-frontend"
  data-service-namespace="my-app"
></script>

Keep crossorigin="anonymous" so browser error reporting includes useful details.

Installation Modes

1) Script tag (recommended)

Use data attributes for auto-init:

<script
  id="vunet-rum"
  async
  crossorigin="anonymous"
  src="https://your-cdn/vunet-rum-loader.js"
  data-collection-source-url="https://collector.example.com/rum"
  data-service-name="my-service"
  data-service-namespace="my-app"
  data-decide-api-endpoint="/vuSmartMaps/api/rum/"
></script>

2) Programmatic init

<script src="https://your-cdn/vunet-rum-loader.js"></script>
<script>
  window.vunetRum.initialize({
    collectionSourceUrl: 'https://collector.example.com/rum',
    serviceName: 'my-service',
    serviceNamespace: 'my-app',
    decideApiEndpoint: '/vuSmartMaps/api/rum/',
  });
</script>

3) NPM package

npm install @vunet/otel-rum

import { initialize } from '@vunet/otel-rum';

initialize({
  collectionSourceUrl: 'https://collector.example.com/rum',
  serviceName: 'my-service',
  serviceNamespace: 'my-app',
});

Configuration

Important options

| Data Attribute | Programmatic Option | Type | Required | Default | | ------------------------------------------ | --------------------------------- | ------------------------- | -------- | ----------------------- | | data-collection-source-url | collectionSourceUrl | string | Yes | - | | data-decide-api-endpoint | decideApiEndpoint | string | No | /vuSmartMaps/api/rum/ | | data-authorization-token | authorizationToken | string | No | - | | data-service-name | serviceName | string | No | unknown | | data-service-namespace | serviceNamespace | string | No | - | | data-deployment-environment | deploymentEnvironment | string | No | - | | data-default-attributes | defaultAttributes | Record<string, unknown> | No | {} | | data-buffer-max-spans | bufferMaxSpans | number | No | 2048 | | data-max-export-batch-size | maxExportBatchSize | number | No | 50 | | data-buffer-timeout | bufferTimeout | number | No | 2000 | | data-ignore-urls | ignoreUrls | (string \| RegExp)[] | No | [] | | data-propagate-trace-header-cors-urls | propagateTraceHeaderCorsUrls | (string \| RegExp)[] | No | [] | | data-collect-session-id | collectSessionId | boolean | No | true | | data-collect-errors | collectErrors | boolean | No | true | | data-drop-single-user-interaction-traces | dropSingleUserInteractionTraces | boolean | No | false | | data-drop-short-traces-ms | dropShortTracesMs | number | No | 0 | | data-user-interaction-element-name-limit | userInteractionElementNameLimit | number | No | 20 | | data-user-interaction-event-names | userInteractionEventNames | string[] | No | built-in list | | - | getOverriddenServiceName | (span) => string | No | - | | data-form | form | object | No | - | | data-inject-into-iframe | injectIntoIframe | boolean | No | false | | data-rum-logging | rumLogging | boolean | No | false |

Decide API response

{
  "sampling_percentage": 100,
  "session_replay_percentage": 50,
  "eventFilter": []
}

Static shorthand is also supported:

sr:50,sp:100

Function-based options like getOverriddenServiceName must be passed via programmatic initialize().

Public API

Available via window.vunetRum in browser mode:

• initialize(options)
• mapUser(id, userData)
• setDefaultAttribute(key, value)
• recordError(message, attributes?)
• getCurrentSessionId()
• onReady(callback)
• disableInstrumentations()
• registerInstrumentations()
• stopProcessing()
• tracer (OpenTelemetry tracer)
• api (OpenTelemetry API)

Example

window.vunetRum.onReady(() => {
  window.vunetRum.setDefaultAttribute('app.version', '1.2.3');
  window.vunetRum.mapUser('user-123', { plan: 'premium' });
});

Telemetry Schema Reference

This section consolidates key schema details from traces and logs.

Resource attributes (common)

• service.name
• service.namespace
• deployment.environment.name
• vunet.rum.version
• os.name
• user_agent.name
• vunet.rum.user_identifier (if mapped)
• vunet.rum.user_data (if mapped)

Trace span categories

• Document Load: documentLoad, documentFetch, resourceFetch
• Network: HTTP <METHOD> spans from fetch/xhr instrumentation
• User Interaction: click/input related spans
• Long Task: longtask
• Route Change: routeChange: <path>
• Form Navigation: Form Navigation: <id>

Log categories

• browser.error.uncaught_exception
• browser.error.unhandled_rejection
• browser.error.document
• browser.error.console
• browser.error.custom
• Session replay event logs under @vunet/sessionreplay

Common operational attributes

• session.id
• url.full, url.path
• vunet.document.visibility_state
• vunet.root_span.operation
• vunet.root_span.url
• vunet.http.action_type

Trace Context Propagation

Set propagateTraceHeaderCorsUrls to enable trace header propagation for selected cross-origin endpoints.

window.vunetRum.initialize({
  collectionSourceUrl: 'https://collector.example.com/rum',
  propagateTraceHeaderCorsUrls: [/^https:\/\/api\.example\.com/],
});

Server should allow headers:

Access-Control-Allow-Headers: traceparent, tracestate

Build and Local Run

Prerequisites

• Node.js >=18 (project uses .nvmrc)
• npm >=9
• Buf CLI (for protobuf generation)

Setup

git clone --recurse-submodules [email protected]:vunetsystems/vunet-rum-browser-sdk.git
cd vunet-rum-browser-sdk
npm install

If cloned without submodules:

git submodule update --init --recursive

Build

npm run build

Tests

npm test
npm run test:ut
npm run test:e2e

Quality checks

npm run eslint-fix
npm run prettier-format-all
npm run types

Common troubleshooting

• buf: not found -> install Buf and verify with buf --version
• submodule issues -> reinit with:

git submodule deinit --all -f
git submodule update --init --recursive

Contributor Appendix

Nx workflow

Prefer workspace tasks through Nx:

npm exec nx run otel-rum:build
npm exec nx run otel-rum:bundle
npm exec nx run-many -t test

Submodule branch sync (maintainer operation)

git config -f .gitmodules submodule.opentelemetry-js.branch develop
git config -f .gitmodules submodule.opentelemetry-js-contrib.branch develop
git submodule sync --recursive
git submodule update --remote --recursive

TypeScript globals package (optional for script-tag users)

npm install --save-dev @vunet/rum-types

Browser Support

| Browser | Minimum Version | | ------- | --------------- | | Chrome | 60+ | | Firefox | 55+ | | Safari | 12+ | | Edge | 79+ |

Internet Explorer is not supported.

License

Apache 2.0. See LICENSE.