Distributed Tracing
The 2.x browser SDK records every fetch and XMLHttpRequest call as an OpenTelemetry CLIENT span and propagates its context in the W3C traceparent header. An instrumented backend extracts that header and joins the same trace, so the browser request and the server work share one trace in Traceway's trace view.
Initialize propagation
import { init } from "@tracewayapp/frontend";
init("your-token@https://traceway.example.com/api/report", {
propagateTraceHeaderCorsUrls: [/^https:\/\/api\.example\.com\//],
});Same-origin requests receive the header automatically, with no option. Cross-origin requests receive it only when their URL matches an entry of propagateTraceHeaderCorsUrls. A regular expression is tested against the request URL; a string must equal the whole URL, so use a regular expression for an API host. The API's CORS policy must allow traceparent in request headers. Axios and jQuery AJAX are covered because they use fetch or XMLHttpRequest; they need no additional interceptor. With captureNetwork: false requests are not instrumented, so no span is recorded and no header is sent.
Configure your backend's OpenTelemetry instrumentation and exporter using the OpenTelemetry guides. Standard trace-context extraction is all the backend needs; it replaces the custom header middleware once written for SDK 1.x.
When request spans are uploaded
The header is sent whether or not the browser's span is uploaded, so the backend's spans always carry the browser's trace ID. The browser's own span follows the network signal, which is buffered by default: the span stays on the device and uploads with the breadcrumbs of an error, during a capture, or for the sessions baselineSampleRate selects. To see the browser span on every trace, stream the signal with collection: { signals: { network: { mode: "stream" } } }, with recordAllSessions: true, or with a Data Collection rule.
Trace context and exceptions
Request spans carry session.id. Their rows in the session timeline link to the distributed trace. An exception is associated with the active OpenTelemetry context when emitted; an arbitrary error after an await is not automatically assigned to whichever request happened most recently. Session breadcrumbs still show the requests surrounding the error.
Migrating from SDK 1.x
Remove createAxiosInterceptor() and getActiveDistributedTraceId() calls, and the { distributedTraceId } option of captureException and captureExceptionWithAttributes. The 2.x browser SDK no longer generates traceway-trace-id; it uses traceparent. Remove the backend middleware that copied traceway-trace-id onto the server span as traceway.distributed_trace_id as well: Traceway no longer reads that attribute, for 1.x clients either, so it links nothing (see SDK 1.x). The migration guide lists the other changes.
See Initialization for browser options and Remote SDK Config for controlling whether network spans stream, buffer, or remain off.
Trace an entire interaction explicitly
Clicks remain breadcrumb events. A session groups visits; it is not a causal trace. To connect a multi-step interaction, start an interaction span and bind callbacks that continue it:
import { startInteraction } from "@tracewayapp/frontend";
const interaction = startInteraction("checkout");
try {
const response = await interaction.run(() => fetch("/api/cart"));
const cart = await response.json();
await interaction.run(() => fetch("/api/checkout", {
method: "POST",
body: JSON.stringify(cart),
}));
} catch (error) {
interaction.captureException(error);
} finally {
interaction.end();
}The SDK must be initialized before starting an interaction: before init(), startInteraction returns undefined. The returned object has:
| Member | Purpose |
|---|---|
traceId | The interaction's trace ID, for your own logs |
run(callback) | Runs callback with the interaction as the active context and returns its result |
bind(callback) | Returns a function that runs callback in the interaction's context, for a deferred callback |
captureException(error, attributes?) | Captures the error inside the interaction and marks the interaction as failed |
end() | Ends the interaction span; later calls do nothing |
run activates context while its callback executes; it does not implicitly carry context through every await. Use another run around each later operation, or interaction.bind(callback) for a deferred callback. captureException explicitly associates the error with the interaction. Always end it, including failure paths. Two concurrent interactions keep separate trace IDs, and unrelated errors are not attached to whichever interaction happened most recently.
Requests started in the bound context propagate the same trace to instrumented backends. Collection settings still apply: an interaction does not override disabled tracing or automatically upload a healthy unsampled session. The span of an interaction that captured an exception is sent when it ends even while request spans are buffered. Traceway's trace explorer can show the interaction span and request children when collected.