@vunet/otel-rum NPM

Vunet OTEL RUM

The Vunet RUM OTEL auto-instrumentation JavaScript library is designed to enhance your browser experience by enabling both Session Replay and tracing. This powerful tool allows developers to capture and replay user sessions, providing valuable insights into user interactions and behaviors. Additionally, it facilitates comprehensive tracing within the browser, helping to identify and diagnose performance issues and errors more effectively.

Features

XMLHttpRequest and Fetch APIs auto-instrumentation
user interactions like click, submit, drop etc.
document load with fetched resources
History API and hash change support
web-vitals
session id
longtasks with automatic context attaching
uncaught exceptions, unhandled rejections, document errors and console errors
support for manual instrumentation
automatic context carrying through timers, promises, native async-await, events, observers and more

Installation

The easiest way to start collecting traces from your website is to put the code below inside the <head></head> tags on your website:

<script
  src="https://cdn.vunet.io/otel-rum/latest/rum.js"
  type="text/javascript"
></script>
<script>
  window.vunetRum &&
    window.vunetRum.initialize({
      collectionSourceUrl: 'vunet_traces_collector_source_url',
      serviceName: 'name_of_your_web_service',
      propagateTraceHeaderCorsUrls: [
        'list_of_domains_to_receive_trace_context',
      ],
      collectErrors: true,
    });
</script>

See configuration for all supported options.

There are no other required actions needed to take. With properly provided collectionSourceUrl and serviceName your website is ready and will send collected traces to the specified Sumo Logic collector.

You can load the script asynchronously using the script below, but some functionalities like user interactions or requests made before script run will be limited.

<script>
  (function (w, s, d, r, e, n) {
    (w[s] = w[s] || {
      readyListeners: [],
      onReady: function (e) {
        w[s].readyListeners.push(e);
      },
    }),
      ((e = d.createElement('script')).async = 1),
      (e.src = r),
      (n = d.getElementsByTagName('script')[0]).parentNode.insertBefore(e, n);
  })(
    window,
    'vunetRum',
    document,
    'https://cdn.vunet.io/otel-rum/latest/rum.js',
  );
  window.vunetRum.onReady(function () {
    window.vunetRum.initialize({
      collectionSourceUrl: 'vunet_traces_collector_source_url',
      serviceName: 'name_of_your_web_service',
      propagateTraceHeaderCorsUrls: [
        'list_of_domains_to_receive_trace_context',
      ],
      collectErrors: true,
    });
  });
</script>

Manual installation

The other option is to bundle this library inside your project and initialize it.

Inside your project directory execute npm install @vunet/otel-rum.

RUM needs to be initialized preferably before other functionalities in your code:

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

initialize({
  collectionSourceUrl: 'vunet_traces_collector_source_url',
  serviceName: 'name_of_your_web_service',
  propagateTraceHeaderCorsUrls: ['list_of_domains_to_receive_trace_context'],
});

Configuration

Both script tag and manual installation can be configured with following parameters:

Parameter	Type	Default	Description
collectionSourceUrl	`string`	required	Sumo Logic collector source url
authorizationToken	`string`		Sumo Logic collector authorization token
serviceName	`string`	`"unknown"`	Name of your web service
applicationName	`string`		Name of your application
deploymentEnvironment	`string`		The software deployment (e.g. `staging`, `production`)
defaultAttributes	`object`	`{}`	Attributes added to each span
samplingProbability	`number`	`1`	`1` means all traces are sent, `0` - no traces are send, `0.5` - there is 50% change for a trace to be sent
bufferMaxSpans	`number`	`2048`	Maximum number of spans waiting to be send
maxExportBatchSize	`number`	`50`	Maximum number of spans in one request
bufferTimeout	`number`	`2000`ms	Time in milliseconds for spans waiting to be send
ignoreUrls	`(string\\|RegExp)[]`	`[]`	List of XHR URLs to ignore (e.g. analytics)
propagateTraceHeaderCorsUrls	`(string\\|RegExp)[]`	`[]`	List of URLs where W3C Trace Context HTTP header will be injected
collectSessionId	`boolean`	`true`	Enables collecting `rum.session_id` attribute
dropSingleUserInteractionTraces	`boolean`	`true`	Automatically drops traces with only one span coming from the user-interaction instrumentation (click etc.)
collectErrors	`boolean`	`true`	Automatically collect and send uncaught exceptions, unhandled rejections, document errors and console errors
userInteractionElementNameLimit	`number`	`20`	Limit for user interaction element name, after which the name will be truncated with `...` suffix.
getOverriddenServiceName	(span: Span) => string		Function used for overridding the service name of a span during its creation.

Trace context propagation

By default, trace context propagation, allowing creation of end to and front end to backend traces for cross-origin requests is not enabled because of browser CORS security restrictions. To propagate tracing context to create front-end to back-end traces, set exact URLs or URL patterns in the propagateTraceHeaderCorsUrls configuration option. You must configure your server to return accept and return following CORS headers in its response: Access-Control-Allow-Headers: traceparent, tracestate. Read W3C Trace Context for more details. Sumo Logic cannot perform any validation correct configuration of services of other origins, so, please be careful when configuring this. You should always try enabling CORS in a test environment before setting it up in production.

For example:

// propagates trace context in requests made to https://api.vunet.io or http://localhost:3000/api URLs
propagateTraceHeaderCorsUrls: [
  /^https:\/\/api\.vunet.io\/.*/,
  /^http:\/\/localhost:3000\/api\/.*/,
],

Baggage

Baggage is contextual information that’s passed between spans. It’s a key-value store that resides alongside span context in a trace, making values available to any span created within that trace.

Imagine you want to have a customerId attribute on every span in your trace, which involves multiple services; however, customerId is only available in one specific service. To accomplish your goal, you can use OpenTelemetry Baggage to propagate this value across your system. In that sense it is different than defaultAttributes, which does not allow for data to be added dynamically. It could be said that setDefaultAttribute() serves similar function as Baggage (as attributes can be defined dynamically); however it will not add attributes retroactively (spans sent before calling setDefaultAttribute()).

OpenTelemetry uses Context Propagation to pass Baggage around, and each of the different library implementations has propagators that parse and make that Baggage available without you needing to explicitly implement it.

Baggage can be used by accessing methods in our window.vunetRum pulled from OpenTelemetry upstream:

const baggage =
  window.vunetRum.api.propagation.getBaggage(
    window.vunetRum.api.context.active(),
  ) || window.vunetRum.api.propagation.createBaggage();

baggage.setEntry('customerId', { value: 'customer-id-value' });
window.vunetRum.api.propagation.setBaggage(
  window.vunetRum.api.context.active(),
  baggage,
);

Useful links:

Manual instrumentation

When initialized by the <script /> tag, window attribute vunetRum is exposed. It gives possibility to create spans manually. Global vunetRum objects contains:

api - exposed @opentelemetry/api module
tracer - an instance of a Tracer from @opentelemetry/tracing
recordError - a function to create an error with the given message and optional attributes.

Example:

const { tracer, api, recordError } = vunetRum;
const span = tracer.startSpan('fetchUserData', {
  attributes: { organization: 'client-a' },
});
api.context.with(api.trace.setSpan(api.context.active(), span), () => {
  // long running operation
});
recordError('Cannot load data', { organization: 'test' });

Using in production, make sure your website works when vunetRum is not defined (e.g. blocked by a browser extension).

Disable instrumentation

Instrumentation can be disabled and enabled again in runtime using registerInstrumentations() and disableInstrumentations() methods.

vunetRum.disableInstrumentations();
// some code with instrumentations disabled
vunetRum.registerInstrumentations();

Public API

All method are available under the window.vunetRum object.

setDefaultAttribute(key, value)

Extends the list of default attributes specified during initialization.

Example: window.vunetRum.setDefaultAttribute('user_id', userId)

getCurrentSessionId()

Returns current value of the rum.session_id attribute. Returned value may change in time, so don't cache it.

Example: window.vunetRum.getCurrentSessionId()

recordError()

Sends an error with the given message and optional attributes.

Example: window.vunetRum.recordError('Cannot load data', { organization: 'test' })

License

This project is released under the Apache 2.0 License.

Contributing

Please refer to our Contributing documentation to get started.

Code Of Conduct

Please refer to our Code of Conduct.

opentelemetry tracing vunet rum session replay

4 months ago

4 months ago

5 months ago

5 months ago

6 months ago

6 months ago

6 months ago

6 months ago

6 months ago

6 months ago

6 months ago

6 months ago

6 months ago