The Dash0 Web SDK instruments your website or single-page application to capture real user sessions, Core Web Vitals, page views, HTTP requests, and frontend errors.

After installing the SDK and initializing it with your Dash0 endpoint, telemetry flows automatically to the Websites Explorer where you can:

Monitor frontend performance and web vitals in the Overview and Web Vitals tabs
Investigate individual user sessions and filter by page, browser, or deployment
Drill down from slow HTTP requests into full backend traces to diagnose performance issues across the full stack

For a complete walkthrough of session investigation and trace correlation, see Correlate Sessions with Backend Traces.

Setup Walkthrough Available

The Website Monitoring with OpenTelemetry and Dash0 Guide includes short videos showing how to install the Dash0 Web SDK and initialize Website Monitoring at application startup.

Prerequisites

Before integrating the Web SDK into your application, ensure you have the necessary configuration details from your Dash0 account.

Log in to your desired Dash0 account. You can sign up here.
Retrieve the following information from your Dash0 account:
- The OTLP via HTTP endpoint URL for your Dash0 region (Dash0 link)
- The authToken with Ingesting permissions for the dataset (Dash0 link)

Info

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 Ingesting

Installation Methods

The Web SDK can be installed in two ways:

NPM package (Recommended) — for applications with a build process and module bundlers (webpack, vite, etc.), such as Next.js or React applications. This approach provides more control over SDK initialization, TypeScript types, a more ergonomic API, and automatic Vercel environment detection.
Script bundle — for static websites or applications without a build process, where you include the SDK via a script tag directly in your HTML. Use this when you cannot use module builds.

NPM Installation (Recommended)

For applications with a build process, install the SDK as an npm package. This approach is recommended because it:

Provides more control over when the SDK is loaded and initialized
Ensures the SDK is bundled with your application and immediately available
Includes TypeScript types for better development experience
Offers a more ergonomic API (direct function imports vs. global wrapper)
Automatically detects Vercel environment variables for deployment tracking

Install the SDK:

typescript

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

init({
  serviceName: "my-app",
  endpoint: {
    // Get in the OTLP over HTTP tab of https://app.dash0.com/settings/endpoints
    url: "...",
    // Get or create from the https://app.dash0.com/settings/auth-tokens
    authToken: "...",
  },
  sessionInactivityTimeoutMillis: 30 * 60 * 1000, // 30 min
  sessionTerminationTimeoutMillis: 4 * 60 * 60 * 1000, // 4 hours
});

In this example, if a user is inactive for 30 minutes, the session ends. Any session also terminates after 4 hours, even if the user remains active.

For static websites or applications without a build process, you can load the SDK directly from a CDN using unpkg. The SDK is distributed as an IIFE (Immediately Invoked Function Expression) bundle that exposes a global dash0 function.

Add the following to your HTML, placing the configuration script before the SDK script:

html

1234567891011121314151617181920212223242526272829303132333435363738
<!DOCTYPE html>
<html>
<head>
  <!-- Initialize configuration before the SDK loads -->
  <script>
    (function (d, a, s, h, z, e, r, o) {
      d[a] ||
        ((z = d[a] =
          function () {
            h.push(arguments);
          }),
        (z._t = new Date()),
        (z._v = 1),
        (h = z._q = []));
    })(window, "dash0");
    dash0("init", {
      serviceName: "my-static-website",
      endpoint: {
        // Get in the OTLP over HTTP tab of https://app.dash0.com/settings/endpoints
        url: "https://ingress.eu-west-1.aws.dash0.com/v1/traces",
        // Get or create from the https://app.dash0.com/settings/auth-tokens
        authToken: "your-auth-token-here",
      },
      sessionInactivityTimeoutMillis: 30 * 60 * 1000, // 30 min
      sessionTerminationTimeoutMillis: 4 * 60 * 60 * 1000, // 4 hours
    });
  </script>

  <!-- Load the SDK (latest version) -->
  <script src="https://unpkg.com/@dash0/sdk-web/dist/dash0.iife.js" defer crossorigin="anonymous"></script>
  
  <!-- OR pin to a specific version (recommended for production) -->
  <!-- <script src="https://unpkg.com/@dash0/sdk-web@0.18.1/dist/dash0.iife.js" defer crossorigin="anonymous"></script> -->
</head>
<body>
  <!-- Your page content -->
</body>
</html>

The configuration script creates a window.dash0 function that queues API calls until the SDK loads. Once loaded, all queued calls are executed automatically.

API Differences

When using the script bundle, all SDK functions are called through the global dash0 function with method names as strings. For example:

Module API: addSignalAttribute(key, value)
Script bundle API: dash0("addSignalAttribute", key, value)

Content Security Policy

If your website uses Content Security Policy (CSP), you'll need to allow the SDK script and connections to the Dash0 ingestion endpoint. Add the following directives to your CSP configuration:

12
script-src 'self' https://unpkg.com;
connect-src 'self' https://ingress.eu-west-1.aws.dash0.com;

If you've pinned to a specific SDK version, you can restrict the script source further:

1
script-src 'self' https://unpkg.com/@dash0/sdk-web@0.18.1/dist/dash0.iife.js;

For stricter CSP policies using integrity hashing, you can view the script hash by appending ?meta to the unpkg URL:

1
https://unpkg.com/@dash0/sdk-web@0.18.1/dist/dash0.iife.js?meta

Replace https://ingress.eu-west-1.aws.dash0.com with your actual Dash0 endpoint URL in the connect-src directive.

For more detailed guidance, refer to the Dash0 Web SDK documentation on GitHub.

Tracking Users

The SDK automatically tracks sessions, but to count users you need to call the identify() method:

typescript

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

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

Tracking Anonymous Visitors

For websites with anonymous visitors, generate and persist an anonymous ID before calling identify:

typescript

1234567
let anonymousId = localStorage.getItem('dash0_anonymous_id');
if (!anonymousId) {
  // Use your preferred method to generate a unique string identifier
  anonymousId = generateUniqueId(); // Implement this function based on your needs
  localStorage.setItem('dash0_anonymous_id', anonymousId);
}
identify(anonymousId);

When the user logs in, call identify again with the authenticated user ID to maintain continuity between anonymous and logged-in sessions.

Set Deployment Attributes

Deployment attributes enable you to filter and compare telemetry across different environments, deployments, and versions. The Web SDK supports three deployment-related attributes that map to OpenTelemetry semantic conventions:

deployment.environment.name — the environment where the application is running (e.g., production, staging, development)
deployment.name — a human-readable name for the deployment (e.g., main, preview-feature-xyz)
deployment.id — a unique identifier for this specific deployment (e.g., a commit SHA, build number, or deployment URL)

Configure Deployment Attributes

You can set deployment attributes in two ways:

1. At initialization time — use additionalSignalAttributes to include attributes with all transmitted signals:

typescript

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

init({
  serviceName: "my-website",
  endpoint: {
    url: "https://ingress.eu-west-1.aws.dash0.com/v1/traces",
    authToken: "your-auth-token",
  },
  additionalSignalAttributes: {
    "deployment.environment.name": "production",
    "deployment.name": "main",
    "deployment.id": process.env.VERCEL_DEPLOYMENT_ID || "local",
    "service.version": "1.2.3",
  },
});

2. At runtime — use addSignalAttribute() to add or update attributes dynamically:

typescript

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

// Add deployment ID after it becomes available
addSignalAttribute("deployment.id", deploymentId);

Auto-Detection on Vercel

When using the NPM package installation, the SDK automatically detects deployment attributes when running on Vercel by reading environment variables:

deployment.environment.name — detected from NEXT_PUBLIC_VERCEL_ENV
deployment.name — detected from NEXT_PUBLIC_VERCEL_TARGET_ENV
deployment.id — detected from NEXT_PUBLIC_VERCEL_BRANCH_URL

If you're deploying to Vercel with the NPM package, these attributes are set automatically without additional configuration.

Info

Auto-detection of Vercel environment variables is only available when using the NPM package installation. If you're using the script bundle, you must set deployment attributes manually via additionalSignalAttributes in the init configuration.

Use Deployment Attributes for Filtering

Once set, deployment attributes appear in the Website Monitoring filters, allowing you to:

Compare web vitals between production and staging environments
Isolate issues to specific deployments or branches
Track performance regressions across versions
Filter sessions by environment to focus on production users

The filter bar in the Overview, Web Vitals, and Sessions tabs lets you narrow data by Environment, Deployment Name, and Deployment ID simultaneously.

Set Up the Web SDK

Prerequisites

Installation Methods

NPM Installation (Recommended)

Script Bundle Installation

Content Security Policy

Tracking Users

Tracking Anonymous Visitors

Set Deployment Attributes

Configure Deployment Attributes

Auto-Detection on Vercel

Use Deployment Attributes for Filtering

Further Reading