The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
Docs updated
ddux49a8564c4554
diff --git a/docs/pages/client/js-sdk/_meta.json b/docs/pages/client/js-sdk/_meta.jsonindex 6add2bcf..af7b0b1f 100644--- a/docs/pages/client/js-sdk/_meta.json+++ b/docs/pages/client/js-sdk/_meta.json@@ -3,6 +3,7 @@"initialization": "Initialization","exceptions": "Exceptions","messages": "Messages",+ "distributed-tracing": "Distributed Tracing","flush": "Flush & Lifecycle","sourcemap-upload": "Source Maps","session-replay": "Session Replay"diff --git a/docs/pages/client/js-sdk/distributed-tracing.mdx b/docs/pages/client/js-sdk/distributed-tracing.mdxnew file mode 100644index 00000000..3b209399--- /dev/null+++ b/docs/pages/client/js-sdk/distributed-tracing.mdx@@ -0,0 +1,135 @@+# Distributed Tracing++Correlate frontend errors with the backend requests that caused them. The Traceway JS SDK propagates a `traceway-trace-id` header from the browser to your backend, linking exceptions and traces across the stack.++## How It Works++1. The frontend SDK generates a unique trace ID for each outgoing HTTP request+2. The ID is sent as a `traceway-trace-id` header to your backend+3. Your backend middleware reads the header and attaches it to the trace context+4. Any exceptions or traces captured on either side are tagged with the same ID+5. In the Traceway dashboard, you can jump between the frontend error and the backend request++## With fetch (Automatic)++When you call `init()`, the SDK automatically instruments `window.fetch` to inject the `traceway-trace-id` header on **same-origin** requests. No extra code is needed.++```javascript+import { init } from "@tracewayapp/frontend";++init("your-token@https://traceway.example.com/api/report");++// All same-origin fetch calls are automatically instrumented+const res = await fetch("/api/orders", {+ method: "POST",+ body: JSON.stringify(order),+});+```++Cross-origin requests are **not** instrumented to prevent leaking the header to third-party services.++If an error is thrown during or after a fetch call (e.g., in a `.then()` handler), the SDK automatically tags the captured exception with the distributed trace ID of that in-flight request.++## With Axios (Manual Interceptor)++For Axios, use the `createAxiosInterceptor` helper to add the header to all requests:++```javascript+import axios from "axios";+import { createAxiosInterceptor } from "@tracewayapp/frontend";++const api = axios.create({ baseURL: "/api" });+api.interceptors.request.use(createAxiosInterceptor());++// All requests through this instance include the traceway-trace-id header+const res = await api.post("/orders", order);+```++### Exception Correlation with Axios++The Axios interceptor injects the header but does not set the active trace ID used by global error handlers. To correlate caught exceptions with Axios requests, pass the trace ID explicitly:++```javascript+import { captureException } from "@tracewayapp/frontend";++try {+ await api.post("/orders", order);+} catch (err) {+ captureException(err, {+ distributedTraceId: err.config?.headers?.["traceway-trace-id"],+ });+}+```++## Backend Setup++Your backend must read the `traceway-trace-id` header and pass it into the trace context. This is handled automatically by Traceway's backend middleware.++### NestJS++The `TracewayMiddleware` from `@tracewayapp/nestjs` automatically:+- Reads `traceway-trace-id` from incoming request headers+- Echoes the ID back in the response header+- Stores it in the trace context for the duration of the request++No additional configuration is needed — if you have the middleware installed, distributed tracing works out of the box.++```typescript+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";+import { TracewayModule, TracewayMiddleware } from "@tracewayapp/nestjs";++@Module({+ imports: [+ TracewayModule.forRoot({+ connectionString: "your-token@https://traceway.example.com/api/report",+ }),+ ],+})+export class AppModule implements NestModule {+ configure(consumer: MiddlewareConsumer) {+ consumer.apply(TracewayMiddleware).forRoutes("*");+ }+}+```++### Node.js (Express / Custom)++If you're using the `@tracewayapp/backend` package directly, extract the header and pass it to `withTraceContext`:++```javascript+import { withTraceContext, captureCurrentTrace, setTraceResponseInfo } from "@tracewayapp/backend";++app.use((req, res, next) => {+ const distributedTraceId = req.headers["traceway-trace-id"];++ if (distributedTraceId) {+ res.setHeader("traceway-trace-id", distributedTraceId);+ }++ withTraceContext({ endpoint: "", clientIP: req.ip, distributedTraceId }, () => {+ res.on("finish", () => {+ setTraceResponseInfo(res.statusCode, 0);+ captureCurrentTrace();+ });+ next();+ });+});+```++## API Reference++| Export | Description |+|--------|-------------|+| `createAxiosInterceptor()` | Returns an Axios request interceptor that adds the `traceway-trace-id` header |+| `getActiveDistributedTraceId()` | Returns the trace ID of the currently in-flight fetch request, or `null` |+| `DISTRIBUTED_TRACE_HEADER` | The header name constant: `"traceway-trace-id"` |++## How the Active Trace ID Works++The SDK keeps a module-level variable that tracks which fetch call is currently in-flight:++1. Before each same-origin `fetch()`, a new UUID is generated and stored as the "active" trace ID+2. The same ID is injected as the `traceway-trace-id` header+3. When the fetch promise settles (resolves or rejects), the active ID is cleared++If an exception is captured (via `captureException`, `window.onerror`, or `window.onunhandledrejection`) while a fetch is in-flight, the SDK automatically attaches the active trace ID to the exception. This is how frontend errors get linked to their triggering backend request without any manual work.diff --git a/docs/pages/client/js-sdk/index.mdx b/docs/pages/client/js-sdk/index.mdxindex 7e07f052..e0f040f3 100644--- a/docs/pages/client/js-sdk/index.mdx+++ b/docs/pages/client/js-sdk/index.mdx@@ -76,4 +76,5 @@ captureMessage("User completed checkout");- **Retry with backoff**: Failed uploads are automatically retried- **Stack trace capture**: Full stack traces are captured for exceptions- **Custom attributes**: Attach metadata to exceptions for better debugging+- **Distributed tracing**: Automatically correlates frontend errors with backend requests via `fetch` instrumentation, with manual support for Axios- **Lightweight**: Minimal bundle size impactdiff --git a/docs/pages/client/nestjs/middleware.mdx b/docs/pages/client/nestjs/middleware.mdxindex 24fede1a..72f1fe37 100644--- a/docs/pages/client/nestjs/middleware.mdx+++ b/docs/pages/client/nestjs/middleware.mdx@@ -68,11 +68,24 @@ For each request, the middleware captures:## How It Works1. **Request Start**: Creates a new trace context with `withTraceContext()`-2. **Request Processing**: Your controllers and services run within the trace context-3. **Response Finish**: On the `res.finish` event:+2. **Distributed Trace ID**: If the request contains a `traceway-trace-id` header (sent by the frontend SDK), the middleware reads it, echoes it back in the response, and stores it in the trace context+3. **Request Processing**: Your controllers and services run within the trace context+4. **Response Finish**: On the `res.finish` event:- Records status code and body size with `setTraceResponseInfo()`- Captures the trace with `captureCurrentTrace()`+## Distributed Tracing++The middleware automatically supports distributed tracing between the Traceway frontend SDK and your backend. When the frontend SDK sends a `traceway-trace-id` header (automatically via `fetch` instrumentation or manually via the Axios interceptor), the middleware:++1. Reads the header from the incoming request+2. Echoes it back in the response header (useful for debugging)+3. Passes it into the trace context — all traces and exceptions captured during that request are tagged with the distributed trace ID++This lets you correlate frontend errors with their triggering backend requests in the Traceway dashboard. No extra configuration is needed — if the middleware is installed, distributed tracing works out of the box.++See the [JS SDK Distributed Tracing](/client/js-sdk/distributed-tracing) guide for frontend setup details.+## Ignored RoutesUse the `ignoredRoutes` option in `TracewayModule.forRoot()` to skip tracing for specific routes:diff --git a/docs/pages/client/node-sdk/traces.mdx b/docs/pages/client/node-sdk/traces.mdxindex fa5c6a68..9edd2983 100644--- a/docs/pages/client/node-sdk/traces.mdx+++ b/docs/pages/client/node-sdk/traces.mdx@@ -34,6 +34,7 @@ await withTraceContext(| `isTask` | `boolean` | No | Mark as background task instead of HTTP trace || `attributes` | `Record<string, string>` | No | Initial trace attributes || `clientIP` | `string` | No | Client IP address for HTTP traces |+| `distributedTraceId` | `string` | No | Distributed trace ID from an incoming `traceway-trace-id` header (for frontend ↔ backend correlation) |## Reading Trace Context@@ -207,7 +208,69 @@ const elapsedMs = getTraceDuration();// Returns 0 if not in a trace context```-## Express Middleware Example+## Distributed Tracing++### getDistributedTraceId++Get the distributed trace ID from the current trace context:++```typescript+import { getDistributedTraceId } from "@tracewayapp/backend";++const distributedId = getDistributedTraceId();+// Returns undefined if no distributed trace ID is set+```++### Express Middleware with Distributed Tracing++When building a custom Express middleware, read the `traceway-trace-id` header and pass it into the trace context to enable frontend ↔ backend correlation:++```typescript+import {+ withTraceContext,+ setTraceAttribute,+ setTraceResponseInfo,+ captureCurrentTrace,+ captureException,+} from "@tracewayapp/backend";++function tracingMiddleware(req, res, next) {+ const distributedTraceId = req.headers["traceway-trace-id"];++ if (distributedTraceId) {+ res.setHeader("traceway-trace-id", distributedTraceId);+ }++ withTraceContext(+ {+ endpoint: `${req.method} ${req.path}`,+ clientIP: req.ip,+ distributedTraceId,+ },+ async () => {+ if (req.user) {+ setTraceAttribute("userId", req.user.id);+ }++ res.on("finish", () => {+ setTraceResponseInfo(res.statusCode, res.get("content-length") || 0);+ captureCurrentTrace();+ });++ try {+ await next();+ } catch (error) {+ captureException(error);+ throw error;+ }+ }+ );+}+```++See the [JS SDK Distributed Tracing](/client/js-sdk/distributed-tracing) guide for frontend setup details.++## Express Middleware Example (Basic)```typescriptimport {@@ -225,12 +288,10 @@ function tracingMiddleware(req, res, next) {clientIP: req.ip,},async () => {- // Add user info if authenticatedif (req.user) {setTraceAttribute("userId", req.user.id);}- // Capture response on finishres.on("finish", () => {setTraceResponseInfo(res.statusCode, res.get("content-length") || 0);captureCurrentTrace();diff --git a/docs/pages/client/react/index.mdx b/docs/pages/client/react/index.mdxindex e0abcd1a..e51af88a 100644--- a/docs/pages/client/react/index.mdx+++ b/docs/pages/client/react/index.mdx@@ -98,8 +98,25 @@ function TestButton() {Click the button and check your Traceway dashboard to verify the error appears.+## Distributed Tracing++The SDK automatically instruments `fetch` to propagate a `traceway-trace-id` header on same-origin requests. This links frontend errors to the backend requests that caused them — no extra configuration needed.++For Axios users, add the interceptor to your instance:++```jsx+import axios from "axios";+import { createAxiosInterceptor } from "@tracewayapp/frontend";++const api = axios.create({ baseURL: "/api" });+api.interceptors.request.use(createAxiosInterceptor());+```++See the [Distributed Tracing](/client/js-sdk/distributed-tracing) guide for full details.+## Next Steps- [TracewayProvider](/client/react/provider) - Configuration options- [Error Boundary](/client/react/error-boundary) - Automatic error capture- [Hooks](/client/react/hooks) - Manual error capture+- [Distributed Tracing](/client/js-sdk/distributed-tracing) - Frontend ↔ backend correlationdiff --git a/docs/pages/client/svelte/index.mdx b/docs/pages/client/svelte/index.mdxindex 95c1e81d..f1e8231e 100644--- a/docs/pages/client/svelte/index.mdx+++ b/docs/pages/client/svelte/index.mdx@@ -103,6 +103,23 @@ For SvelteKit, set up Traceway in your root layout:<slot />```+## Distributed Tracing++The SDK automatically instruments `fetch` to propagate a `traceway-trace-id` header on same-origin requests. This links frontend errors to the backend requests that caused them — no extra configuration needed.++For Axios users, add the interceptor to your instance:++```javascript+import axios from "axios";+import { createAxiosInterceptor } from "@tracewayapp/frontend";++const api = axios.create({ baseURL: "/api" });+api.interceptors.request.use(createAxiosInterceptor());+```++See the [Distributed Tracing](/client/js-sdk/distributed-tracing) guide for full details.+## Next Steps- [Context Setup](/client/svelte/context) - Configuration and advanced usage+- [Distributed Tracing](/client/js-sdk/distributed-tracing) - Frontend ↔ backend correlationdiff --git a/docs/pages/client/vue/index.mdx b/docs/pages/client/vue/index.mdxindex 633ea4f9..a391c3f4 100644--- a/docs/pages/client/vue/index.mdx+++ b/docs/pages/client/vue/index.mdx@@ -84,7 +84,24 @@ function sendTestError() {Click the button and check your Traceway dashboard to verify the error appears.+## Distributed Tracing++The SDK automatically instruments `fetch` to propagate a `traceway-trace-id` header on same-origin requests. This links frontend errors to the backend requests that caused them — no extra configuration needed.++For Axios users, add the interceptor to your instance:++```javascript+import axios from "axios";+import { createAxiosInterceptor } from "@tracewayapp/frontend";++const api = axios.create({ baseURL: "/api" });+api.interceptors.request.use(createAxiosInterceptor());+```++See the [Distributed Tracing](/client/js-sdk/distributed-tracing) guide for full details.+## Next Steps- [Plugin Setup](/client/vue/plugin) - Configuration options- [Composables](/client/vue/composables) - Using useTraceway+- [Distributed Tracing](/client/js-sdk/distributed-tracing) - Frontend ↔ backend correlation