jQuery Quick Start

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

Installation

Via npm

npm install @tracewayapp/jquery jquery

import $ from "jquery";
import { init } from "@tracewayapp/jquery";
 
// The AJAX hook binds to the global jQuery, so publish it before init().
window.jQuery = window.$ = $;
 
init("your-token@https://cloud.tracewayapp.com/api/report");

init() binds $(document).ajaxError() on window.jQuery (or window.$). If jQuery is only a bundled module and never lands on window, uncaught errors and captureException() still work but AJAX errors are silently skipped. Call init() after jQuery is on the page. If jQuery already comes from a <script> tag, it is global already and you can drop the two jQuery lines above.

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>

The CDN build exposes everything on the TracewayJQuery global: TracewayJQuery.captureException, TracewayJQuery.captureMessage, TracewayJQuery.setAttribute, TracewayJQuery.flush, and so on. The import examples below are for the npm build, so prefix them with TracewayJQuery. when you use the CDN.

What It Does

Once initialized, the SDK 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

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.

The backend has to hold up its end: it must set the incoming header on its server span as the traceway.distributed_trace_id attribute. The Symfony bundle does this for you, everything else needs one small middleware. See Distributed Tracing.

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"));
});

On the CDN build, call TracewayJQuery.captureException(new Error("Test error from jQuery")) instead.

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