Splunk distribution of OpenTelemetry JavaScript Browser

The Splunk distribution of OpenTelemetry JavaScript Browser provides a JavaScript file that can be added into a page that automatically captures:

• Document load information, including resource fetching
• User interactions (clicks)
• XmlHttpRequest (XHR) and fetch calls, including the full URL but not including any body/payload
• WebSocket activity
• Errors

By default, the following error sources are captured:

• addEventListener('error') which reports unhandled errors (e.g., from setInterval callbacks)
• addEventListener('unhandledrejection') which reports unhandled Promise rejections
• instrumenting usage of console.error
• document.documentElement.addEventListener('error', ... {capture:true}); which reports errors on DOM elements (e.g., image loading issue)

All data and errors captured are reported to Splunk RUM.

🚧 This project is currently in BETA.

Getting Started

To get started, download the JS file from the latest release and add its path to your page.

For example:

<script src="https://cdn.signalfx.com/o11y-gdi-rum/latest/splunk-otel-web.js" crossorigin="anonymous"></script>
<script>
  SplunkRum.init({
      beaconUrl: 'https://rum-ingest.<REALM>.signalfx.com/v1/rum',
      rumAuth: '<RUM_ACCESS_TOKEN>',
      app: '<YOUR_APPLICATION_NAME>'
    });
</script>

Please read INSTALLING.md for more advanced installation scenarios.

Supported browsers

Not all supported browsers support all features/attributes, but the following browsers are generally supported. We are actively working on expanding this list.

• Chrome 52+
• Safari 11+
• Firefox 57+
• Edge 79+
• IE not currently supported

Known issues

Auto-instrumentation doesn't currently capture events handled on document level, ie. document.addEventListener(...).

Web Workers and Service Workers are not supported. Code loaded within them will not be auto-instrumented, and currently there is no version of the code which can be used within either Web or Service Workers for manual instrumentation.

Open Telemetry version

All configuration options

SplunkRum.init({ })

Capturing modules

Capturing modules can be configured by passing following values to instrumentations object in config:

• false - disables this module
• true - enables this module with default options
• object - enables with additional options, which are described in the types definition

Additional configuration options are available for following modules:

User interactions

SplunkRum.setGlobalAttributes(attributes)

You can (re)set globalAttributes at any time with this method. Using it will overwrite specified properties and leave others unchanged. Any spans reported from this point on will have your new attributes set.
You can pass undefined to clear your global attributes.

Redacting Personally Identifiable Information (PII)

In certain situations, metadata collected by our instrumentation may include PII. We'd advise that you review these cases in particular:

• any network operation, where a secret piece of information might be present in the URL (e.g. an authentication token); please note that we do not capture or report any data from the payload of the request (i.e. the POST body), apart from its size;
• any user interaction (e.g. a click), where a target element might contain a secret piece of information in its id
• error messages produced by your app (e.g., usage of console.error or strings passed to an Error constructor).

To redact PII you can pass an option when initializing.

SplunkRum.init({
  ...otherOptions,
  exporter: {
    onAttributesSerializing: (attributes, span) => ({
      ...attributes,
      'http.url': /secret\=/.test(attributes['http.url']) ? '[redacted]' : attributes['http.url'],
    }),
  },
});

For a working example see this integration test. Span is provided a second argument for your convenience.

Manual OpenTelemetry instrumentation

Tracing Provider

If you would like to manually instrument your application (for example, to report timings for key events), you can use the OpenTelemetry API. Our TracingProvider is in SplunkRum.provider.

Example on how to manually instrument:

  const provider = SplunkRum.provider;
  const span = provider.getTracer('searchbox').startSpan('search');
  span.setAttribute('searchLength', searchString.length);
  // time passes
  span.end();

Errors

While many errors are captured by default, manual errors can be reported by using:

  SplunkRum.error(errorObjectOrMessageString);

Building and contributing

Please read CONTRIBUTING.md for instructions on building, running tests, and so forth.

License and versioning

The Splunk distribution of OpenTelemetry JavaScript Browser is a distribution of the OpenTelemetry JavaScript Browser project. It is released under the terms of the Apache Software License version 2.0. See the license file for more details.