JS SDK Reference
SDK 1.x (stable)
Distributed Tracing

Distributed Tracing (SDK 1.x)

This page covers the stable 1.x browser SDK, which npm install @tracewayapp/frontend (and the React, Vue, Svelte and jQuery packages) installs today. The 2.x SDK, with remote SDK config, is in beta: see Distributed Tracing for its version of this page.

⚠️

The 1.x SDK does not link browser errors to backend traces. It sends its own traceway-trace-id header, and Traceway no longer uses it: the id is ignored on the exceptions the SDK reports, and the traceway.distributed_trace_id span attribute that backends used to set no longer joins traces. To see a browser request and the backend work it caused in one trace, use the 2.x SDK, which propagates the standard W3C traceparent header.

What 1.x links

Every exception the 1.x SDK reports still becomes an issue with its stack trace and attributes. When session replay is on, the issue carries the replay clip, and an exception inside a recorded session links to that session. The breadcrumbs inside the replay list the fetch and XHR calls the page made around the error.

What it cannot do is name the backend request behind a browser error. The backend's own traces are unaffected: services that propagate OpenTelemetry context share one trace id, and Traceway shows them as one distributed trace, whichever of them you open it from.

What the 1.x SDK sends

init() instruments window.fetch and XMLHttpRequest (which covers $.ajax() and Axios) and adds a traceway-trace-id header, a fresh UUID per request, to same-origin requests. Cross-origin requests are left alone, so the header never reaches third-party services. An exception captured while a request is in flight carries that request's id.

The header is harmless, and nothing on your backend has to read it. Code written for the old linking has no effect and can go:

  • A backend middleware that copies traceway-trace-id onto the server span as traceway.distributed_trace_id, or echoes the header back. Traceway ignores the attribute (see Upgrading to the V2 trace tables).
  • getActiveDistributedTraceId() calls, and the { distributedTraceId } third argument of captureExceptionWithAttributes.
  • createAxiosInterceptor(). Axios already goes through the instrumented XMLHttpRequest, and the interceptor only adds a second id under the same header name.

Linking browser and backend

Upgrade to the 2.x SDK (beta). It records fetch and XHR as OpenTelemetry CLIENT spans and sends the W3C traceparent header, so a backend instrumented with OpenTelemetry joins the same trace with no extra middleware. Distributed Tracing covers the setup, including propagateTraceHeaderCorsUrls for APIs on another origin, and Initialization the other changes from 1.x.

API Reference

These 1.x exports still exist so that code using them keeps compiling. None of them changes what Traceway shows.

ExportDescription
getActiveDistributedTraceId()Returns the id of the same-origin request currently in flight, or null
DISTRIBUTED_TRACE_HEADERThe header name constant: "traceway-trace-id"
createAxiosInterceptor()Returns an Axios request interceptor that adds the header. Not needed in a browser app