Distributed tracing for Browser

1. Browser: Add your API URL patterns to tracePropagationTargets. Matching requests carry a traceparent header. A 5xx response or qualifying timeout becomes a browser error.
2. Receiving back end: Instrument the service that handles those requests. The instrumentation reads traceparent and reports spans through an AppSignal hosted collector. Use a supported integration or OpenTelemetry instrumentation for its framework.

​

Before you start

• Report through a hosted collector. On the Hosted Collectors page in your organization settings, open a collector and copy its Collector URL. Send the service’s data to that URL. If the list is empty, create a collector there first. Distributed tracing only works through a hosted collector. In Python and Ruby, set the URL as the collector_endpoint option. Ruby also needs the appsignal-opentelemetry gem.
• Set a service name. Give the service its own name. The trace uses it to tell the service apart from the browser and other services. Where you set it depends on the back end’s language:
  • Python, Ruby, and PHP: the service_name option.
  • Go and Java: the service.name resource attribute.
  • Other OpenTelemetry setups: the service.name resource attribute.
• Instrument its HTTP server. Use an integration for its framework that reads traceparent from incoming requests. That is how the service joins the browser’s trace instead of starting its own. In Go, also register a propagator with otel.SetTextMapPropagator.
• Allow traceparent across origins. A back end can be on another origin, such as api.example.com called from www.example.com. The browser may then send a CORS preflight before the request. Allow traceparent in the back end’s response to the preflight. Otherwise the browser may block the request:

Access-Control-Allow-Headers: content-type, traceparent

​

Enable it

import { init } from "@appsignal/browser";

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  appVersion: "<YOUR_APP_REVISION>",
  // Your API hosts, matched against host + pathname
  tracePropagationTargets: ["api.example.com/**"],
  // How this front end is named in a trace. Defaults to "Browser"
  serviceName: "Checkout UI",
});

​

What is reported

• A 5xx response is reported as an HTTPError.
• A timeout is reported as a TimeoutError. That is a fetch that rejects with a TimeoutError, as one bounded by AbortSignal.timeout() does. It is also an XMLHttpRequest whose timeout fires. The server may have received and traced a timed-out request.

• The request, as params.request: the url, the method, the status when a response arrived, and the duration_ms. Query parameters are removed from the URL as set by your allowlist.
• The span: the trace ID and span ID from the request’s traceparent, with its start time and duration. AppSignal builds the browser’s span from these, so it covers the request as the browser saw it. After a timeout, the back end’s spans can run longer than the browser’s span.
• The service name you set, or Browser.

• A successful request. The header is sent, but the browser stays silent, so the back-end trace stands on its own.
• A 4xx response. The SDK does not classify it as a failed request for tracing.
• A request the browser could not deliver: refused, failed DNS, or blocked by an extension. No server handled it, so there is no back-end trace to join.
• A timeout while the device is offline, which says nothing about the back end.
• A request your code canceled.

​

Reading it in AppSignal

• Browser shows an HTTPError on /product/chocolate-stroopwafel (85 ms). The selected span’s details show the request URL and HTTP 500 response.
• Beneath it, django shows GET api/boom/ with a RuntimeError (81 ms).
• The Django request contains two SELECT spans and a POST span, with their durations.

​

Joining a trace your code started