Configuration

The following configuration options are available, in order to customize the behaviour of the Dash0 Web SDK. These can all be passed via the Dash0 Web SDK's init call.

Backend Correlation

The SDK supports trace context propagation to correlate frontend requests with backend services, for both fetch and XMLHttpRequest (including libraries built on XHR, such as axios's default browser adapter). You can configure different header types (traceparent, X-Amzn-Trace-Id) for different endpoints using the propagators configuration.

Propagators Configuration (Recommended)

Configure trace context propagators for different URL patterns:

init({
  propagators: [
    // W3C traceparent headers for internal APIs
    { type: "traceparent", match: [/.*\/api\/internal.*/] },
    // AWS X-Ray headers for AWS services
    { type: "xray", match: [/.*\.amazonaws\.com.*/] },
    // Send both headers to specific endpoints
    { type: "traceparent", match: [/.*\/api\/special.*/] },
    { type: "xray", match: [/.*\/api\/special.*/] },
  ],
});

Supported propagator types:

• "traceparent": W3C TraceContext headers for OpenTelemetry-compatible services
• "xray": AWS X-Ray trace headers for AWS services

Same-origin requests: All same-origin requests automatically receive traceparent headers plus headers for ALL other configured propagator types, regardless of match patterns. This ensures consistent trace correlation within your application.

Match patterns for cross-origin requests:

• RegExp: Regular expressions to match against full URLs

Multiple Headers: When multiple propagators match the same URL, both headers will be added to the request. This is useful when you need to support multiple tracing systems simultaneously.

Backend setup

• Make sure the endpoints respond to OPTIONS requests and include the appropriate headers in their Access-Control-Allow-Headers response header:
  • traceparent for W3C trace context
  • X-Amzn-Trace-Id for AWS X-Ray

Legacy Configuration

These configurations are deprecated

The legacy propagateTraceHeadersCorsURLs configuration is still supported but deprecated:

• Include a regex matching the endpoint you want to enable in the propagateTraceHeadersCorsURLs configuration option.

Configuration auto-detection

Certain configuration values can be auto-detected if using the module version of the Dash0 Web SDK in combination with certain cloud providers.

Vercel — environment and deployment

The SDK detects environment, deploymentName, and deploymentId from Vercel's auto-prefixed system env vars. The same 9 framework prefixes listed under VCS context are supported — the SDK picks up whichever variant the bundler substituted at build time.

VCS (version control) context

The SDK auto-detects VCS context from the build environment and applies it as OpenTelemetry vcs.* resource attributes on every signal. Pairing telemetry with the git commit, branch, and PR the build came from lets Dash0 Agent answer questions like "which PR introduced this error?" out of the box.

Detected attributes:

Supported framework prefixes:

The SDK enumerates the env vars above under every framework prefix the bundler exposes to the browser. On Vercel these prefixes are applied automatically. On Netlify (and other CI/CD platforms that do not auto-prefix) you can expose the raw build env vars under your framework's prefix to get the same auto-detection — e.g. set NEXT_PUBLIC_REPOSITORY_URL = $REPOSITORY_URL in your Netlify build env, or the equivalent for your bundler.

Bundler caveat for Vite-based setups: Vite reads env vars via import.meta.env.VITE_* by default and does not substitute process.env.VITE_* in source code. The SDK relies on process.env.VITE_* literal accessors, so Vite users on Vercel get auto-detection (Vercel applies VITE_ prefixing inside the build environment before Vite's substitution layer runs). Vite users on other platforms need to add a define entry or process.env polyfill to their vite.config.ts to substitute the relevant literals — or use the vcs manual override.

Detection precedence, per attribute: vcs (manual override) → Vercel env var → Netlify env var → unset. Set vcs to override any auto-detected value, or disableVcsDetection to disable env-var reads entirely.

Configuration Overview

General

• Enabled Instrumentations
  key: enabledInstrumentations
  type: InstrumentationName[]
  optional: true
  default: undefined
  List of instrumentations to enable. Defaults to undefined, enabling all instrumentations. Supported values: '@dash0/navigation' | '@dash0/web-vitals' | '@dash0/error' | '@dash0/fetch' | '@dash0/xhr' | '@dash0/session-recording' | '@dash0/frustration-signals' Please note that some dash0 features might not work as expected if instrumentations are disabled.

• Ignore URLs
  key: ignoreUrls
  type: Array<RegExp>
  optional: true
  default: undefined
  An array of URL regular expression for which no data should be collected. These regular expressions are evaluated against the document, XMLHttpRequest and fetch URLs. While the document URL matches, no page views, navigation timings, web vitals, errors or rage clicks are sent, and no session recording is started. Page views from startView and custom events from sendEvent are always sent. XMLHttpRequest and fetch requests made from an ignored page are still recorded, unless the request URL matches too. Signals sent from an ignored page have no page.url.* attributes, unless startView sets the URL explicitly. A page view has no referrer when the referrer matches. In error messages and stack traces, the page URL, the referrer, the URL the document was loaded with and the request URL are replaced with REDACTED when they match. Other URLs in these texts are not changed.

• ** URL Attribute Scrubber**
  key: urlAttributeScrubber
  type: UrlAttributeScrubber
  optional: true
  default: (attributes) => attributes Allows the application of a custom scrubbing function to url attributes before they are applied to signals. This is invoked for each url processed for inclusion in signal attributes. For example this applies both to page.url.* and url.* attribute namespaces. Sensitive parts of the url attributes should be replaced with REDACTED, avoid partially or fully dropping attributes to preserve telemetry quality. The scrubbed url.full value is also used where a url is reported as plain text: the navigation timing name, the page view referrer, HTTP request failure messages, and the page url inside error messages and stack traces. If the scrubber changes or removes any other url attribute but returns url.full unchanged, url.full is rebuilt from the scrubbed parts. Session replay data, including the urls it contains, does not pass this scrubber. Note: basic auth credentials in urls are automatically redacted before this is invoked.

Website Details and Attributes

• Service Name
  key: serviceName
  type: string
  optional: false
  The logical name or your website, maps to the service.name otel attribute.
• Service Namespace
  key: serviceNamespace
  type: string
  optional: true
  default: undefined
  A namespace for serviceName, maps to the service.namespace otel attribute.
• Service Version
  key: serviceVersion
  type: string
  optional: true
  default: undefined
  The current version of your website, maps to the service.version otel attribute.
• Environment
  key: environment
  type: string
  optional: true
  default: undefined
  Name of the deployment environment, for example staging, or production. Maps to the deployment.environment.name otel attribute. This value is auto detected in certain build environments.
• Deployment Name
  key: deploymentName
  type: string
  optional: true
  default: undefined
  Name of the deployment, maps to the deployment.name otel attribute. This value is auto detected in certain build environments.
• Deployment Id
  key: deploymentId
  type: string
  optional: true
  default: undefined
  Id of the deployment, maps to the deployment.id otel attribute. This value is auto detected in certain build environments.
• Additional Signal Attributes
  key: additionalSignalAttributes
  type: Record<string, AttributeValueType | AnyValue>
  optional: true
  default: undefined
  Allows the configuration of additional attributes to be included with any transmitted event. See AttributeValueType and AnyValue for detailed types.

VCS context

The SDK auto-detects VCS (version control) context from the build environment and applies it as vcs.* resource attributes — see Configuration auto-detection > VCS for the full list of detected attributes and supported framework prefixes.

• Disable VCS Detection
  key: disableVcsDetection
  type: boolean
  optional: true
  default: false
  When true, the SDK does not read any build env vars to derive vcs.* attributes. Any values supplied via vcs are still applied — manual overrides always win.

• VCS Manual Override
  key: vcs
  type: VcsAttributes
  optional: true
  default: undefined
  Manually specify VCS context. Each provided field overrides the auto-detected value for that attribute. Use this for platforms without supported auto-detection, or when the auto-detected values are wrong. Supported fields:

  • providerName — maps to vcs.provider.name
  • ownerName — maps to vcs.owner.name
  • repositoryName — maps to vcs.repository.name
  • repositoryUrlFull — maps to vcs.repository.url.full
  • refHeadName — maps to vcs.ref.head.name (branch or tag)
  • refHeadRevision — maps to vcs.ref.head.revision (commit SHA)
  • changeId — maps to vcs.change.id (PR / MR identifier)

Telemetry Transmission

• Endpoint
  key: endpoint
  type: Endpoint | Endpoint[]
  optional: false
  The OTLP to which the generated telemetry should be sent. Supports multiple endpoints in parallel if an array is provided.
• Endpoint URL
  key: endpoint.url
  type: string
  optional: false
  The OTLP HTTP URL of the endpoint, not including the /v1/* part of the path
• Endpoint Auth Token
  key: endpoint.authToken
  type: string
  optional: false
  The auth token used for the endpoint. Will be placed into Authorization: Bearer {auth_token} header.
• Endpoint Dataset
  key: endpoint.dataset
  type: string
  optional: true
  Optionally specify what dataset should be placed into. Can also be configured within Dash0 through the auth token.
• Enable Transport Compression
  key: enableTransportCompression
  type: boolean
  optional: true
  Enables telemetry transport compression using gzip. EXPERIMENTAL - in rare cases causes Chrome to crash to use at your own risk.

Session Tracking

• Session Sampling Rate
  key: sessionSamplingRate
  type: number
  optional: true
  default: 100
  The percentage of sessions for which telemetry data is recorded and transmitted. Must be a number between 0 and 100.

  • 0: No sessions are recorded or transferred.
  • 100: All sessions are recorded and transferred (default).
  • Any other value: That percentage of sessions are recorded and transferred.

  The sampling decision is deterministic per session ID, so a given session will always produce the same sampling outcome.

• Session Inactivity Timeout
  key: sessionInactivityTimeoutMillis
  type: number
  optional: true
  default: 10800000 (3 hours)
  The session inactivity timeout. Session inactivity is the maximum allowed time to pass between two page loads before the session is considered to be expired. The maximum value is the maximum session duration of 24 hours.

• Session Termination Timeout
  key: sessionTerminationTimeoutMillis
  type: number
  optional: true
  default: 21600000 (6 hours)
  The default session termination timeout. Session termination is the maximum allowed time to pass since session start before the session is considered to be expired.

Error tracking

• Ignore Error Messages
  key: ignoreErrorMessages
  type: Array<RegExp>
  optional: true
  default: undefined
  An array of error message regular expressions for which no data should be collected.
• Wrap Event Handlers
  key: wrapEventHandlers
  type: boolean
  optional: true
  default: true
  Whether we should automatically wrap DOM event handlers added via addEventListener for improved uncaught error tracking. This results in improved uncaught error tracking for cross-origin errors, but may have adverse effects on website performance and stability.
• Wrap Timers
  key: wrapTimers
  type: boolean
  optional: true
  default: true
  Whether we should automatically wrap timers added via setTimeout / setInterval for improved uncaught error tracking. This results in improved uncaught error tracking for cross-origin errors, but may have adverse effects on website performance and stability.

HTTP request instrumentation

• Propagators
  key: propagators
  type: PropagatorConfig[]
  optional: true
  default: undefined
  Configure trace context propagators for different URL patterns. Each propagator defines which header type to send for matching URLs.

  typescript

  type PropagatorConfig = {
    type: "traceparent" | "xray";
    match: RegExp[];
  };

  Example:

  js

  propagators: [
    // Use RegExp for specific cross-origin URL patterns
    { type: "traceparent", match: [/.*\/api\/internal.*/] },
    { type: "xray", match: [/.*\.amazonaws\.com.*/] },
    // Multiple propagators can match the same URL to send both headers
    { type: "traceparent", match: [/.*\/api\/both.*/] },
    { type: "xray", match: [/.*\/api\/both.*/] },
  ];

  Same-origin behavior: All same-origin requests automatically get traceparent headers plus headers for ALL other configured propagator types, regardless of match patterns.

  Cross-origin behavior: When multiple propagators match the same cross-origin URL, both headers will be sent. Duplicate propagator types for the same URL are automatically deduplicated.

  NOTE: Any cross origin endpoints allowed via this option need to include the appropriate headers in the Access-Control-Allow-Headers response header (traceparent for W3C, X-Amzn-Trace-Id for X-Ray). Misconfiguration will cause request failures!

• Propagate Trace Header Cors URLs ⚠️ DEPRECATED
  key: propagateTraceHeadersCorsURLs
  type: Array<RegExp>
  optional: true
  default: undefined
  DEPRECATED: Use propagators instead. An array of URL regular expressions for which trace context headers should be sent across origins by http client instrumentations. NOTE: Any cross origin endpoints allowed via this option need to include traceparent in the Access-Control-Allow-Headers response header. Misconfiguration will cause request failures!

• Max Wait For Resource Timings
  key: maxWaitForResourceTimingsMillis
  type: number
  optional: true
  default: 10000
  How long to wait after an XMLHttpRequest or fetch request has finished for the retrieval of resource timing data. Performance timeline events are placed on the low priority task queue and therefore high values might be necessary.

• Max Tolerance For Resource Timings
  key: maxToleranceForResourceTimingsMillis
  type: number
  optional: true
  default: 50
  The number of milliseconds of tolerance between resolution of a http request promise and the end time of performanceEntries applied when matching a request to its respective performance entry. A higher value might increase match frequency at the cost of potential incorrect matches. Matching is performed based on request timing and url.

• Headers to Capture
  key: headersToCapture
  type: Array<RegExp>
  optional: true
  default: undefined
  A set of regular expressions that will be matched against the HTTP request and response headers of requests made via the XMLHttpRequest and fetch instrumentations. Matching headers are transferred as span attributes (http.request.header.<name> and http.response.header.<name>). Matching is performed against the lowercased header name, so make sure your regular expressions match lowercase names (e.g. /^x-my-header$/ instead of /^X-My-Header$/).

  NOTE: For cross-origin requests, browsers only expose response headers that the server lists in its Access-Control-Expose-Headers response header (besides the CORS-safelisted ones). Response headers that are not exposed this way are silently omitted from the span — the browser hides them without any error or log entry.

Both the fetch and XMLHttpRequest instrumentations report request outcomes on the span as follows:

Responses: http.response.status_code is always set when a response was received. Status codes 200-399 leave the span status unset; all other status codes set the span status to error. For fetch, a response with status 0 (e.g. an opaque response) additionally sets error.type to the response type.

Errors and timeouts: A failed fetch (rejected promise) sets the span status to error, records an exception span event, and sets error.type to the exception name (typically TypeError); no http.response.status_code is set. A failed XMLHttpRequest behaves the same, with error.type set to error for network errors and timeout when xhr.timeout elapses (including synchronous requests, where send() throws).

Cancellations: Aborted requests (via AbortController for fetch, or xhr.abort()) are considered benign: the span gets dash0.web.request.cancelled set to true, the span status stays unset, and no error.type or exception event is recorded. If the response headers had already arrived (e.g. the request was aborted while the body was being read), http.response.status_code is present as well. Note that AbortSignal.timeout() surfaces as a cancellation for fetch, while an XMLHttpRequest timeout is an error — this asymmetry is inherent to the two APIs.

Page view instrumentation

• Provide Page Metadata
  key: pageViewInstrumentation.generateMetadata
  type: (url: URL) => PageViewMeta | undefined
  optional: true
  default: undefined
  Allows websites to dynamically provide page metadata based on the current url. Metadata may include the page title and a set of attributes. See PageViewMeta for detailed type information.
• Track Virtual Page Views
  key: pageViewInstrumentation.trackVirtualPageViews
  type: boolean
  optional: true
  default: true
  Whether the sdk should track virtual page views by instrumenting the history api. Only relevant for websites utilizing virtual navigation.
• Track Url Part Changes
  key: pageViewInstrumentation.includeParts
  type: Array<"HASH" | "SEARCH">
  optional: true
  default: []
  Additionally generate virtual page views when these url parts change.
  • "HASH" changes to the urls hash / fragment
  • "SEARCH" changes to the urls search / query parameters

Session replay

Session replay captures a replay of the user's session with rrweb and transmits it as browser.session_recording log records. Every record of one recording shares a trace ID that embeds the session ID, so a replay can be opened from any span or log of that session.

The recorder ships as a separate bundle, @dash0/sdk-web/session-recording, so websites that do not use session replay do not pay for it. See Setup for how to load it. All options below live under the sessionRecording key of the init options.

By default, the value of every visible input, textarea and select is replaced with asterisks before it leaves the browser. Page text is captured, and so are element attributes: <input type="hidden"> values, <meta content>, data-* attributes and value= set in markup are not masked. Add the class dash0-mask to an element to mask its text, or dash0-block to leave it out of the recording entirely (for example blockSelector: 'input[type=hidden]' to drop hidden inputs). Set maskTextSelector to "*" to mask all text on the page.

• Recorder
  key: sessionRecording.recorder
  type: SessionRecorder
  optional: true
  default: undefined
  The recorder to use. Pass recorder from @dash0/sdk-web/session-recording. When omitted, recording starts as soon as a recorder is registered through startSessionRecording(recorder) or through the dash0-session-recording.iife.js script.
• Sampling Rate
  key: sessionRecording.samplingRate
  type: number
  optional: true
  default: 100
  The percentage of sessions for which a recording is captured, between 0 and 100. The decision is deterministic per session ID and uses the same hash as sessionSamplingRate, so recorded sessions are always a subset of the sessions for which telemetry is transmitted.
• Mask All Inputs
  key: sessionRecording.maskAllInputs
  type: boolean
  optional: true
  default: true
  Replace the value of every visible input, textarea and select with asterisks. <input type="hidden"> values are element attributes and are not masked; use blockSelector for those. Set to false only when no form on the page accepts sensitive data.
• Mask Text Selector
  key: sessionRecording.maskTextSelector
  type: string
  optional: true
  default: undefined
  CSS selector for elements whose text content must be masked. Use "*" to mask all text on the page.
• Mask Text Class
  key: sessionRecording.maskTextClass
  type: string | RegExp
  optional: true
  default: "dash0-mask"
  Elements with this class have their text content masked.
• Block Class
  key: sessionRecording.blockClass
  type: string | RegExp
  optional: true
  default: "dash0-block"
  Elements with this class are not recorded. The replay shows a placeholder with the same dimensions.
• Block Selector
  key: sessionRecording.blockSelector
  type: string
  optional: true
  default: undefined
  CSS selector for elements that are not recorded.
• Mask Input Function
  key: sessionRecording.maskInputFn
  type: (text: string, element: HTMLElement | null) => string
  optional: true
  default: undefined
  Custom function to mask input values. Receives the raw value and the element and returns the masked value.
• Mask Text Function
  key: sessionRecording.maskTextFn
  type: (text: string, element: HTMLElement | null) => string
  optional: true
  default: undefined
  Custom function to mask text nodes. Receives the raw text and the parent element and returns the masked text.
• Record Canvas
  key: sessionRecording.recordCanvas
  type: boolean
  optional: true
  default: false
  Record the content of canvas elements. This is expensive.
• Collect Fonts
  key: sessionRecording.collectFonts
  type: boolean
  optional: true
  default: false
  Collect fonts so the replay renders with the same typefaces. Adds payload size.
• Chunk Max Bytes
  key: sessionRecording.chunkMaxBytes
  type: number
  optional: true
  default: 48000
  The maximum serialized size of one chunk. When buffered events reach this size, a chunk is transmitted. A single rrweb event larger than this, typically a full snapshot, is transmitted on its own.
• Chunk Max Millis
  key: sessionRecording.chunkMaxMillis
  type: number
  optional: true
  default: 5000
  The maximum time buffered events wait before they are transmitted as a chunk.
• Checkout Interval
  key: sessionRecording.checkoutEveryNms
  type: number
  optional: true
  default: 300000
  How often the recorder takes a new full snapshot of the DOM, in milliseconds. A replay can start from any chunk that contains a full snapshot.

Session replay can be disabled without removing the recorder bundle by leaving @dash0/session-recording out of enabledInstrumentations.

Frustration signals

The @dash0/frustration-signals instrumentation watches user interaction for signs of frustration. It currently detects rage clicks: a burst of clicks in the same place, which usually means a control did not respond the way the user expected.

Clicks are only observed while session replay is recording. Detection starts and stops with the recording, which itself follows document visibility, so a rage click always comes with the replay that shows it. This instrumentation therefore does nothing unless @dash0/session-recording is enabled and a recorder is registered — see session replay. A burst that is still open when a recording ends is reported at that point.

Each detected burst is emitted as a browser.rage_click event once the burst ends, carrying the number of clicks, its duration, a CSS selector and the visible label of the clicked element, the click coordinates, and the dash0.session_recording.id of the recording it happened in, which lets Dash0 open the replay at that moment. The element label is omitted whenever it could carry user data — the element is masked or blocked by the session replay configuration (sessionRecording.maskTextClass, maskTextSelector, blockClass, blockSelector), or it is a field the user types into. Only trusted primary-button clicks are considered, so clicks synthesized by scripts are ignored.

• Minimum Clicks
  key: frustrationSignals.rageClick.minClicks
  type: number
  optional: true
  default: 3
  How many clicks in the same place constitute a rage click.
• Click Window
  key: frustrationSignals.rageClick.windowMillis
  type: number
  optional: true
  default: 1000
  The maximum time allowed between two consecutive clicks for them to belong to the same burst. A burst is reported once this long has passed without another click.
• Click Radius
  key: frustrationSignals.rageClick.radiusPixels
  type: number
  optional: true
  default: 30
  How far apart, in CSS pixels, two clicks may be and still count as the same spot. Only applies to clicks that did not land on the same element; clicks on one element always belong together.