About the Web SDK

This SDK enables users of Dash0's web monitoring features to instrument a website or single-page-application to capture and transmit telemetry to Dash0.

Features include:

• Page view instrumentation
• Navigation timing instrumentation
• HTTP request instrumentation (fetch and XMLHttpRequest)
• Error tracking

Getting started

Prerequisites

To setup the web sdk you'll need the following:

1. Log in to your desired Dash0 account. You can sign up here

2. Retrieve the following information from your Dash0 account:

   • The OTLP via HTTP endpointCopy URL for your Dash0 region (Dash0 link)

   • The authTokenCopy with IngestingCopy permissions for the dataset (Dash0 link)

     • Auth tokens for client monitoring will be public as part of your website, please make sure to:
       • Use a separate token, exclusively for website monitoring; if you want to monitor multiple websites, it is best to use a dedicated token for each
       • Limit the dataset permissions on the auth token to the dataset you want to ingest Website Monitoring data with
       • Limit permissions on the auth token to IngestingCopy

Installation steps

1. Add the SDK to your dependencies

123456
# npm
npm install @dash0/sdk-web
# yarn
yarn add @dash0/sdk-web
# pnpm
pnpm install @dash0/sdk-web

1. Initialize the SDK in your code: you'll need to call the initCopy function at a convenient time in your applications lifecycle. Ideally this should happen as early as possible in the web page initialization, as most instrumentations shipped by the SDK can only observe events after init has been called.

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

init({
  serviceName: "my-website",
  endpoint: {
    // Replace this with the endpoint URL for your Dash0 region, that you retrieved earlier in "prerequisites"
    url: "{OTLP via HTTP endpoint}",
    // Replace this with your auth token you retrieved earlier in "prerequisites"
    // Ideally, you will inject the value at build time in order not commit the token to git,
    // even if its effectively public in the HTML you ship to the end user's browser
    authToken: "{authToken}",
  },
});

[!IMPORTANT] To correlate frontend requests with a backend on a different origin, you must configure propagators — see Propagators Configuration (recommended over the deprecated legacy propagateTraceHeadersCorsURLsCopy option). Same-origin requests are propagated automatically.

Session Sampling

You can control the percentage of user sessions that produce telemetry by setting sessionSamplingRateCopy (0–100, default 100):

12345
init({
  serviceName: "my-website",
  endpoint: { url: "{OTLP via HTTP endpoint}", authToken: "{authToken}" },
  sessionSamplingRate: 50, // Only 50% of sessions will be recorded
});

For more detailed instructions, refer to INSTALL.mdCopy.

Development

See DEVELOPMENT.mdCopy for instructions on the development setup, testing and release process.