API Reference

The Dash0 Web SDK provides several API functions to help you customize telemetry collection and add contextual information to your signals.

Signal attributes

Functions for managing custom attributes that are included with all signals.

addSignalAttribute(name, value)

Adds a signal attribute to be transmitted with every signal.

Parameters:

• name (string): The attribute name
• value (AttributeValueType | AnyValue): The attribute value

Example:

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

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

// Script
dash0("addSignalAttribute", "environment", "production");

Note: If you need to ensure attributes are included with signals transmitted on initial page load, use the additionalSignalAttributes property in the init() call instead.

removeSignalAttribute(name)

Removes a previously added signal attribute.

Parameters:

• name (string): The attribute name to remove

Example:

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

removeSignalAttribute("environment");

// Script
dash0("removeSignalAttribute", "environment");

User identification

identify(id, opts)

Associates user information with telemetry signals. See OTEL User Attributes for the matching attributes

Parameters:

• id (string, optional): User identifier
• opts (object, optional): Additional user information
  • name (string, optional): Short name or login/username of the user
  • fullName (string, optional): User's full name
  • email (string, optional): User email address
  • hash (string, optional): Unique user hash to correlate information for a user in anonymized form.
  • roles (string[], optional): User roles

Example:

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

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

// Script
dash0("identify", "user123", { name: "johndoe" });

Custom Events

sendEvent(name, opts)

Sends a custom event with optional data and attributes. Event name cannot be one of the event names internally used by the Dash0 Web SDK. See Event Names

Parameters:

• name (string): Event name
• opts (object, optional): Event options
  • title (string, optional): Human readable title for the event. Should summarize the event in a single short sentence.
  • timestamp (number | Date, optional): Event timestamp
  • data (AttributeValueType | AnyValue, optional): Event data
  • attributes (Record<string, AttributeValueType | AnyValue>, optional): Event attributes
  • severity (LOG_SEVERITY_TEXT, optional): Log severity level

Example:

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

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

// Script
dash0("sendEvent", "user_action", { data: "button_clicked", severity: "INFO" });

Page Views

startView(name, opts)

Manually records a page view. Side-effect free: this never calls history.pushState / history.replaceState and never mutates location. Use this for single-page applications that own their own router and cannot let the SDK touch navigation state — for example, an Electron app that serves the whole application from one root URL, where automatic page-view tracking would report every screen as /.

The emitted page view is indistinguishable from an automatic virtual page view downstream (same browser.page_view event, same type value), with two differences: it is never accompanied by a change_state value, since no history mutation occurred, and the pageViewInstrumentation's generateMetadata callback is not invoked for manual views — supply title and attributes directly via the options object instead.

Parameters:

• name (string): The name of the view, e.g. /settings. Transmitted as the page view's title.
• opts (object, optional): Additional page view details:
  • url (string, optional): Overrides the url reflected in page.url.* attributes for this view. Accepts an absolute or relative url; relative urls are resolved against the current location.href. Falls back to the real location.href if omitted or invalid. Display-only — never navigates or mutates history/location.
  • attributes (Record<string, AttributeValueType | AnyValue>, optional): Additional attributes to include with the page view. Added after the SDK-generated attributes, so they can override them.

Example:

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

startView("/settings", {
  attributes: {
    "app.screen": "settings",
  },
});

startView("/checkout");

// Script
dash0("startView", "/settings", { attributes: { "app.screen": "settings" } });

Error Reporting

reportError(error, opts)

Manually reports an error to be tracked in telemetry.

Parameters:

• error (string | ErrorLike): Error message or error object
• opts (object, optional): Error reporting options
  • componentStack (string | null | undefined, optional): Component stack trace for React errors
  • attributes (Record<string, AttributeValueType | AnyValue>, optional): Additional attributes to include with the error report

Example:

// Module
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);
}

reportError(error, {
  // Report with component stack (useful for React)
  componentStack: getComponentStack(),
  // Additional attributes
  attributes: {
    "user.id": "user123",
  },
});

// Script
dash0("reportError", "Something went wrong in user flow");

Session Management

terminateSession()

Manually terminates the current user session.

Example:

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

// Terminate session on user logout
function handleLogout() {
  terminateSession();
  // Additional logout logic
}

// Script
dash0("terminateSession");

Note: Sessions are automatically managed by the Dash0 Web SDK based on inactivity and termination timeouts configured during initialization. Manual termination is typically only needed for explicit user logout scenarios.

Session Replay

startSessionRecording(recorder)

Starts session replay, which records the session with rrweb. The recording is transmitted as browser.session_recording log records. All records of one recording share a trace ID that embeds the session ID. See Session replay configuration for privacy and chunking options.

The recorder lives in the separate @dash0/sdk-web/session-recording bundle. Passing it to init through sessionRecording.recorder is equivalent to calling this function. It is safe to call this before init; the recorder is kept and recording starts once the SDK is initialized with a sampled session.

Parameters:

• recorder (SessionRecorder, optional): recorder from @dash0/sdk-web/session-recording. When omitted, the SDK uses window.dash0Recorder, which the dash0-session-recording.iife.js script sets. Calls without a usable recorder are ignored.

Example:

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

init({ serviceName: "my-website", endpoint: { url: "...", authToken: "..." } });
startSessionRecording(recorder);

// Script: dash0-session-recording.iife.js calls this for you. Call it yourself only after stopSessionRecording.
dash0("startSessionRecording");

stopSessionRecording()

Stops the running recording and transmits buffered events. A no-op when no recording is running.

Example:

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

stopSessionRecording();

// Script
dash0("stopSessionRecording");

Internal Telemetry

setActiveLogLevel(logLevel)

Changes the active log level of this SDK. Defaults to warn.

Example:

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

setActiveLogLevel("debug");

// Script
dash0("setActiveLogLevel", "debug");