jQuery Quick Start

Integrate Traceway into your jQuery application with the @tracewayapp/jquery package.

Installation

Via npm

npm install @tracewayapp/jquery

import { init } from "@tracewayapp/jquery";
 
init("your-token@https://cloud.tracewayapp.com/api/report");

Session recording is on by default — the last ~30s of DOM events ship with every captured exception.

Via CDN

No build step needed — add two script tags after jQuery:

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@tracewayapp/jquery@1/dist/traceway-jquery.iife.global.js"></script>
<script>
  TracewayJQuery.init("your-token@https://cloud.tracewayapp.com/api/report");
</script>

What It Does

Once initialized, the SDK automatically:

This automatically:

Captures uncaught JavaScript errors and unhandled promise rejections
Captures jQuery AJAX errors via $(document).ajaxError()
Injects traceway-trace-id headers into same-origin $.ajax() requests
Injects traceway-trace-id headers into same-origin fetch() requests

AJAX Error Capture

jQuery AJAX errors are captured automatically. When $.ajax() fails, Traceway records the URL, HTTP method, status code, and error message.

// This error is captured automatically
$.ajax({
  url: "/api/users",
  method: "GET",
  error: function (jqXHR, textStatus, errorThrown) {
    // Your error handling — Traceway also captures this
  },
});

Manual Error Capture

Capture errors explicitly in try/catch blocks:

import { captureException } from "@tracewayapp/jquery";
 
try {
  riskyOperation();
} catch (error) {
  captureException(error);
}

With Options

import { init } from "@tracewayapp/jquery";
 
init("your-token@https://cloud.tracewayapp.com/api/report", {
  debug: true,
  version: "1.0.0",
});

Options Reference

Option	Type	Default	Description
`debug`	`boolean`	`false`	Log captured events to the browser console
`debounceMs`	`number`	`1500`	Batch delay in milliseconds
`retryDelayMs`	`number`	`10000`	Retry delay for failed uploads
`version`	`string`	`undefined`	Your application version
`ignoreErrors`	`Array<string \| RegExp>`	`DEFAULT_IGNORE_PATTERNS`	Error patterns to ignore. Pass `[]` to capture all errors. See Error Filtering
`beforeCapture`	`(exception) => boolean`	`undefined`	Return `false` to suppress an error. See Error Filtering
`sessionRecording`	`boolean`	`true`	Enable the rrweb session recorder
`sessionRecordingSegmentDuration`	`number`	`30000`	rrweb segment length in ms
`recordAllSessions`	`boolean`	`false`	Always-on session recording. See Sessions
`captureLogs`	`boolean`	`true`	Mirror `console.*` calls into the rolling log buffer
`captureNetwork`	`boolean`	`true`	Record `fetch` / `XHR` calls as network actions
`captureNavigation`	`boolean`	`true`	Record History API push / replace / pop transitions

Error Filtering

By default, 4xx AJAX errors (e.g., 401, 422), network errors, and timeouts are not captured. This means $.ajax() calls that return 4xx status codes will not appear in your Traceway dashboard unless you opt in.

To capture all AJAX errors including 4xx:

init("your-token@https://cloud.tracewayapp.com/api/report", {
  ignoreErrors: [],
});

The jQuery SDK records HTTP status codes as attributes on captured errors. You can use beforeCapture to selectively filter by status:

init("your-token@https://cloud.tracewayapp.com/api/report", {
  ignoreErrors: [],
  beforeCapture: (exception) => {
    // Only capture 5xx server errors from AJAX
    const status = Number(exception.attributes?.status);
    if (status >= 400 && status < 500) return false;
    return true;
  },
});

Custom Attributes

Attach app-level identifiers (userId, tenant, feature flags, etc.) to every session and exception:

import {
  setAttribute,
  setAttributes,
  removeAttribute,
  clearAttributes,
} from "@tracewayapp/jquery";
 
setAttribute("userId", "u_42");
setAttributes({ tenant: "acme", plan: "pro" });
 
// On logout / tenant switch:
clearAttributes();

Layering on each event: defaults < global scope < per-call. See Sessions for the full attribute model.

Distributed Tracing

The SDK automatically instruments both XMLHttpRequest (used by $.ajax()) and fetch to propagate a traceway-trace-id header on same-origin requests. This links frontend errors to the backend requests that caused them.

With Symfony + OpenTelemetry

If your backend uses the Symfony OpenTelemetry Bundle, distributed tracing works out of the box. The bundle reads the traceway-trace-id header from incoming requests and attaches it as a span attribute, linking your jQuery frontend errors to Symfony backend traces.

// Frontend — trace header is injected automatically
$.post("/api/orders", { item: "widget" });

// Backend — the bundle reads traceway-trace-id automatically
// No extra configuration needed in your Symfony controllers

Test Your Integration

import { captureException } from "@tracewayapp/jquery";
 
$("#test-button").on("click", function () {
  captureException(new Error("Test error from jQuery"));
});

Click the button and check your Traceway dashboard to verify the error appears.

Next Steps

Distributed Tracing — Frontend ↔ backend correlation
JS SDK Reference — Full API reference

Context Setup Overview