Dash0 SDK Web

Overview

Use the Dash0 web sdk to instrument your web application for our website monitoring features. It allows to observe end-user page loads, website performance, sessions, fetch requests and errors. And seamlessly integrates website monitoring with your existing telemetry signals. It is 100% open source and its code and detailed documentation is available on github.

Use Cases

• Real User Monitoring (RUM): Gather detailed performance metrics from actual user interactions, including page load times, resource loading, and user interactions. This provides a realistic view of application performance compared to synthetic testing.
• Frontend Performance Bottleneck Identification: Pinpoint performance bottlenecks in the frontend by analyzing timings for various operations like network requests, script execution, and rendering.
• (Uncaught) Errors and Promise rejections: Capture and analyze JavaScript errors occurring in users' browsers, providing insights into the frequency and context of errors to prioritize bug fixes.
• Session Replay: Watch recordings of real user sessions to see what users saw and did before an error or a slow request. Session replay is optional and masks form inputs by default; see the Setup guide to enable it.
• Correlation of Frontend and Backend Traces: Connect frontend user interactions with corresponding backend traces, enabling end-to-end performance analysis and troubleshooting.
• Custom Instrumentation: Instrument specific user interactions or business logic within the application to gain deeper insights into critical workflows.

Before you begin

You'll need a couple of prerequisites before you can start using the sdk:

• An auth token, which you can get or create from the Auth Tokens settings page for your organization
• The endpoint url for your Dash0 region, which you find in the OTLP via HTTP endpoint tab of the Endpoints settings page for your organization

Installation

Next we'll need to install the sdk's package

npm install --save @dash0/sdk-web

Initialization

Finally the sdk needs to be initialized. This should happen as early as possible in your applications lifecycle. If you are using Next.js you can use their instrumentation-client.js file, but initialization is generally framework agnostic.

Here is a simple example:

import { init } from "@dash0/sdk-web";

init({
  serviceName: "my-website",
  endpoint: {
    // Replace this with the endpoint url identified during preparation
    url: "http://example.com",
    // Replace this with your auth token you created earlier
    // Ideally inject the value at build time to not commit the token to git, even if its effectively public
    authToken: "you-auth-token-goes-here",
  },
});

Usage

Most SDK features will work via auto instrumentation and do not require you to make any changes to your application beyond initializing the sdk. However these can be enhanced and extended with application specific data if you want. The following examples will give you a short overview on how to do this, please refer to the sdk's repository for additional details.

Providing additional attributes

import { addSignalAttribute, removeSignalAttribute } from "@dash0/sdk-web";

addSignalAttribute("environment", "production");
addSignalAttribute("version", "1.2.3");
removeSignalAttribute("environment");

Identifying Users

import { identify } from "@dash0/sdk-web";

identify("user123", {
  name: "johndoe",
  fullName: "John Doe",
  email: "john@example.com",
  roles: ["admin", "user"],
});

Reporting Errors

import { reportError } from "@dash0/sdk-web";

// Report a string error
reportError("Something went wrong in user flow");

// Report an Error object
try {
  // Some operation
} catch (error) {
  reportError(error);
}

// Report with component stack (useful for React)
reportError(error, {
  componentStack: getComponentStack(),
});

Sending custom events

import { sendEvent } from "@dash0/sdk-web";

sendEvent("user_action", {
  data: "button_clicked",
  attributes: {
    buttonId: "submit-form",
    page: "/checkout",
  },
  severity: "INFO",
});

Session Replay

Session replay records what your users see and do on your website, so you can watch a session back in Dash0 next to its page views, requests, errors and traces. The recorder is built on rrweb and ships as an optional, separate bundle: websites that do not record sessions do not download it.

Session replay requires @dash0/sdk-web version 0.25.0 or later.

Enabling session replay

Import the recorder and pass it to init:

import { init } from "@dash0/sdk-web";
import { recorder } from "@dash0/sdk-web/session-recording";

init({
  serviceName: "my-website",
  endpoint: {
    url: "http://example.com",
    authToken: "your-auth-token-goes-here",
  },
  sessionRecording: { recorder },
});

If you load the SDK with a script tag, add the recorder script next to it. The order of the two scripts does not matter:

<script defer crossorigin="anonymous" src="https://unpkg.com/@dash0/sdk-web/dist/dash0.iife.js"></script>
<script
  defer
  crossorigin="anonymous"
  src="https://unpkg.com/@dash0/sdk-web/dist/dash0-session-recording.iife.js"
></script>

If your Content Security Policy allows a specific script URL or hash rather than all of https://unpkg.com, add an entry for dash0-session-recording.iife.js as well. The recording is sent to the same endpoint as the rest of the SDK's telemetry, so connect-src needs no change.

The recorder only records while the page is visible, and it needs Proxy and MutationObserver. In browsers that lack them, the SDK keeps working and only skips session replay.

Protecting sensitive data

By default, the value of every visible input, textarea and select is replaced with asterisks before it leaves the browser. Page text and element attributes are recorded as they are. To keep more data out of the recording:

• Add the class dash0-mask to an element to mask its text.
• Add the class dash0-block to an element to leave it out of the recording. The replay shows a placeholder of the same size instead.
• Use maskTextSelector and blockSelector to mask or block elements by CSS selector.

init({
  // ...
  sessionRecording: {
    recorder,
    // Mask all text on the page
    maskTextSelector: "*",
    // Leave hidden inputs, whose values are attributes and not masked, out of the recording
    blockSelector: "input[type=hidden]",
  },
});

Recording a share of sessions

Use samplingRate to record a percentage of sessions, between 0 and 100 (default 100). The decision is made per session, and recorded sessions are always a subset of the sessions selected by sessionSamplingRate.

init({
  // ...
  sessionRecording: { recorder, samplingRate: 10 },
});

Starting and stopping recording

To record only after a user gives consent, or to pause recording on a page, leave the recorder out of init and start and stop the recording yourself:

import { startSessionRecording, stopSessionRecording } from "@dash0/sdk-web";
import { recorder } from "@dash0/sdk-web/session-recording";

startSessionRecording(recorder);

stopSessionRecording();

stopSessionRecording sends any events the recorder has buffered before it stops.

Watching replays

In Dash0, open Websites, select your website and go to the Sessions tab. Sessions that have a recording show a replay button in the Replay column. Open a session to watch its replay alongside the session's page views, events and errors.

For all session replay options, such as canvas recording, font collection and custom masking functions, see the session replay configuration in the SDK's documentation.

Learn more about the Website Monitoring or the SDK

Consult the Dash0 documentation to learn more about the website monitoring features, or visit the Dash0 SDK Web Repository to learn more about the sdk.