Distributed tracing

While collection is active, core wraps browser fetch and XMLHttpRequest to add W3C-style traceparent headers to eligible requests. Your backend must read and propagate these headers for an end-to-end trace.

Configure destinations

Same-origin requests are eligible by default. Add only your own backend origins when cross-origin propagation is needed.

import { init } from '@askdepth/core';

init({
  writeKey: 'YOUR_BROWSER_WRITE_KEY',
  endpoint: 'https://YOUR_COLLECTOR/v1/telemetry',
  consent: 'unknown',
  allowedTracingOrigins: ['https://api.example.com/'],
});

The implementation checks an exact origin match or a raw URL prefix match. Use fully qualified trusted URLs and a trailing slash for a whole-origin prefix. A loose entry such as https://api.example.com can also prefix-match https://api.example.com.other-host.test; do not treat this option as a security origin parser.

The configured telemetry URL is excluded from tracing. This exclusion is based on the configured endpoint prefix, not every route on the collector host.

Backend CORS configuration

A cross-origin traceparent header can cause a preflight request. The target must allow your application origin and the traceparent request header. When a request suddenly fails after tracing is enabled, inspect the OPTIONS response and server CORS configuration.

The SDK does not add tracestate, create backend spans, or configure your observability provider. It creates a trace ID when collection starts and a fresh parent/span ID when generating a header, with flags 01.

Read a header manually

import { getTraceparent } from '@askdepth/core';

const header = getTraceparent();
if (header) {
  console.log('Current trace context:', header);
}

getTraceparent() returns null unless collection is active. Each call generates a fresh parent ID. For an eligible fetch, an existing traceparent header is preserved; avoid adding another header to the same request unnecessarily.

Request object caveat

In 0.3.0, the traced fetch(Request, init) branch clones the Request with tracing headers but does not forward the separate init argument. Put method, body, headers, credentials, and signal into the Request constructor, or call fetch(url, init) so your request options remain intact.

// URL + init follows the branch that preserves these options.
async function sendReport() {
  await fetch('/api/report', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ report_id: 'report_47' }),
  });
}

Limits of correlation

Network failures become ERROR_CLICK only when they correlate with a recent click. HTTP errors and failed requests are not a complete network log. Other libraries may also wrap fetch/history APIs; exercise your actual application and monitoring stack together before rollout.