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.

[!IMPORTANT] To correlate frontend requests with a backend on a different origin, you must configure propagators below (recommended over the deprecated legacy propagateTraceHeadersCorsURLs option). Same-origin requests are propagated automatically. Misconfiguration of cross origin trace correlation can lead to request failures — please make sure to carefully validate the configuration provided in the next steps.

Propagators Configuration (Recommended)

Configure trace context propagators for different URL patterns:

js

1234567891011
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.

Configuration Key	Vercel system var (auto-prefixed per framework)
environment	`VERCEL_ENV`
deploymentName	`VERCEL_TARGET_ENV`
deploymentId	`VERCEL_BRANCH_URL`

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:

Resource attribute	Vercel source	Netlify source
`vcs.provider.name`	`VERCEL_GIT_PROVIDER`	derived from URL
`vcs.owner.name`	`VERCEL_GIT_REPO_OWNER`	derived from URL
`vcs.repository.name`	`VERCEL_GIT_REPO_SLUG`	derived from URL
`vcs.repository.url.full`	constructed from above	`REPOSITORY_URL`
`vcs.ref.head.name`	`VERCEL_GIT_COMMIT_REF`	`BRANCH`
`vcs.ref.head.revision`	`VERCEL_GIT_COMMIT_SHA`	`COMMIT_REF`
`vcs.change.id`	`VERCEL_GIT_PULL_REQUEST_ID`	`REVIEW_ID`

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.

Framework	Prefix
Next.js / Blitz.js	`NEXT_PUBLIC_`
Nuxt 3	`NUXT_PUBLIC_`
Nuxt 2	`NUXT_ENV_`
Create React App	`REACT_APP_`
Gatsby	`GATSBY_`
Vite / SvelteKit (v0) / SolidStart	`VITE_`
Astro / Hydrogen (v1) / modern SvelteKit	`PUBLIC_`
Vue CLI	`VUE_APP_`
RedwoodJS	`REDWOOD_ENV_`
Sanity Studio	`SANITY_STUDIO_`

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' 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, fetch and resource URLs.
** 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. 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
```
1234
type PropagatorConfig = {
  type: "traceparent" | "xray";
  match: RegExp[];
};
```
Example:
js
```
12345678
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