Verteiltes Tracing für Browser

Browser monitoring ist ein Beta-Feature von AppSignal Labs. Das Paket @appsignal/browser wird unter dem beta-Tag auf npm veröffentlicht, und seine Konfiguration und API können sich zwischen Beta-Releases noch ändern. Teilen Sie Ihr Feedback in unserer Discord-Community.

Eine Checkout-Seite meldet POST https://api.example.com/orders: HTTP 503. Sie wissen, dass der Order-Request fehlgeschlagen ist, aber nicht warum. Der Order-Service hat möglicherweise vier Sekunden auf eine Datenbanksperre gewartet, bevor er 503 zurückgab. Verteiltes Tracing lässt Sie diesen Request vom Browser bis in den Order-Service verfolgen. Um den Browser-Fehler mit der Arbeit im Order-Service zu verbinden, richten Sie beide Seiten ein:

Browser: Fügen Sie Ihre API-URL-Muster zu tracePropagationTargets hinzu. Passende Requests tragen einen traceparent-Header. Eine 5xx-Response oder ein qualifizierender Timeout wird zu einem Browser-Fehler.
Empfangender API-Service: Instrumentieren Sie dessen HTTP-Server, damit er traceparent liest und Spans über einen gehosteten AppSignal-Collector meldet. Verwenden Sie eine unterstützte Integration oder eine OpenTelemetry-Instrumentierung für sein Framework.

Schritt 1 allein meldet nur den Browser-Fehler. Seine Trace-Timeline bleibt leer, bis der Order-Service in Schritt 2 instrumentiert ist, denn die Server-Spans stammen aus dieser Instrumentierung, nicht aus dem Browser-SDK. Beide Schritte sind nötig, um den Request als einen Trace zu sehen.

Verteiltes Tracing ist ein Beta-Feature von AppSignal Labs. Das Browser-SDK benötigt keinen Collector. Der empfangende Service benötigt einen gehosteten AppSignal-Collector für seine Spans.

Bevor Sie beginnen

Wählen Sie die Einrichtung für den Service, der den Browser-Request empfängt. Dessen HTTP-Server-Integration muss traceparent lesen, und der Service muss Spans über einen gehosteten AppSignal-Collector senden:

FastAPI: Installieren Sie opentelemetry-instrumentation-fastapi und verwenden Sie den Python-Collector-Modus.
Rails: Verwenden Sie die Gems appsignal und appsignal-opentelemetry im Collector-Modus. Die Rails-Integration liest eingehende Traces.
Go oder individuelles OpenTelemetry: Instrumentieren Sie Ihren HTTP-Server und konfigurieren Sie die Trace-Context-Propagation. Siehe Verfügbarkeit und Einrichtung.

Aktivieren

Fügen Sie für jeden API-Host und -Pfad ein Muster zu tracePropagationTargets hinzu. Die standardmäßig leere Liste lässt das Tracing ausgeschaltet:

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

Muster werden gegen den Host und Pfad jedes fetch- und XMLHttpRequest-Aufrufs abgeglichen. Sie ignorieren das Schema und den Query-String. Verwenden Sie * innerhalb eines Pfadsegments oder ** über Segmente hinweg. Geben Sie sowohl einen Host als auch einen Pfad an:

Muster	Trifft auf
`api.example.com/**`	Jeden Request an `api.example.com` auf dem Standardport.
`api.example.com:8443/**`	Jeden Request an `api.example.com` auf Port 8443. Geben Sie den Port an, wenn er nicht der Standard ist.
`.example.com/*`	Jeden Request an eine Subdomain von `example.com`.
`api.example.com/v1/**`	Requests unter `/v1` auf `api.example.com`.
`api.example.com`	Nichts. Es hat keinen Pfad, fügen Sie also `/**` hinzu.
`/api/**`	Nichts. Es hat keinen Host.
`/api/`	Diesen Pfad auf jedem Host, auch bei Drittanbietern, die Sie nie tracen wollten. Vermeiden Sie das.

In der Trace-Timeline beschriftet serviceName den Browser-Fehler-Span. Checkout UI kennzeichnet zum Beispiel Fehler aus Ihrem Checkout-Front-end. Der Standard ist Browser. Verwenden Sie für jedes Front-end, das Sie überwachen, einen eigenen Namen. Das SDK sendet den Namen mit jedem Fehlerbericht. Der Installationsassistent des Browser-SDK bietet Verteiltes Tracing als Option an. Es ist standardmäßig ausgeschaltet. Wählen Sie es aus, fügt das dem Browser-Snippet tracePropagationTargets: ["api.example.com/**"] hinzu. Ersetzen Sie den Beispiel-Host durch Ihren API-Host und instrumentieren Sie anschließend den empfangenden Service. Der Assistent installiert oder konfiguriert diesen Service nicht. Um die Propagation zu prüfen, laden Sie eine Seite, die Ihre API aufruft, und untersuchen Sie den Request im Network-Panel Ihres Browsers. Ein passender Request sollte einen traceparent-Header tragen. Prüfen Sie anschließend einen fehlgeschlagenen Request in AppSignal, um zu sehen, ob Back-end-Spans in seinem Trace erscheinen. Bei einer Cross-Origin-API, etwa api.example.com, aufgerufen von www.example.com, sendet der Browser möglicherweise vor dem Request einen CORS-Preflight. Erlauben Sie traceparent in der Response Ihrer API auf den Preflight. Sonst blockiert der Browser den Request möglicherweise:

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

Das SDK fügt einem Request im no-cors-Modus keinen Header hinzu, weil der Browser ihn entfernen würde. Diese Requests werden nie als fehlgeschlagene Requests gemeldet.

Was gemeldet wird

Das SDK meldet diese Ergebnisse für einen passenden Request, der einen traceparent-Header gesendet hat:

Eine 5xx-Response wird als HTTPError gemeldet.
Ein Timeout wird als TimeoutError gemeldet. Das ist ein fetch, der mit einem TimeoutError abgelehnt wird, wie es ein durch AbortSignal.timeout() begrenzter tut. Es ist auch ein XMLHttpRequest, dessen timeout auslöst. Der Server hat einen Request mit Timeout möglicherweise empfangen und in einem Trace erfasst.

Die Meldung benennt den Request und sein Ergebnis, zum Beispiel POST https://api.example.com/orders: HTTP 503 oder GET https://api.example.com/orders: timed out. Neben allem, was ein gewöhnlicher Browser-Fehler trägt, enthält der Bericht:

Den Request, als params.request: die url, die method, den status, wenn eine Response eingetroffen ist, und die duration_ms. Query-Parameter werden gemäß Ihrer Allowlist aus der URL entfernt.
Den Span: die Trace-ID und Span-ID aus dem traceparent des Requests, mit seiner Startzeit und Dauer. AppSignal baut daraus den Span des Browsers, sodass er den Request so abdeckt, wie der Browser ihn gesehen hat. Nach einem Timeout können die Spans des Back-ends länger laufen als der Span des Browsers.
Den Servicenamen, den Sie gesetzt haben, oder Browser.

Für Folgendes wird nichts gemeldet:

Einen erfolgreichen Request. Der Header wird gesendet, aber der Browser bleibt still, sodass der Back-end-Trace für sich steht.
Eine 4xx-Response. Das SDK stuft sie nicht als fehlgeschlagenen Request für Tracing ein.
Einen Request, den der Browser nicht zustellen konnte: abgewiesen, DNS-Fehler oder von einer Extension blockiert. Kein Server hat ihn verarbeitet, es gibt also keinen Back-end-Trace, dem er beitreten könnte.
Einen Timeout, während das Gerät offline ist, was nichts über das Back-end aussagt.
Einen Request, den Ihr Code abgebrochen hat.

Diese Requests können trotzdem einen Netzwerk-Breadcrumb hinterlassen, sofern sie nicht auf privacy.networkBlocklist passen oder die Breadcrumb-Erfassung deaktiviert ist. Ein Breadcrumb für einen Request, der den Context propagiert hat, enthält dessen Trace-ID. Ein fehlgeschlagener Request durchläuft dieselbe Pipeline wie jeder andere Fehler. errors.enabled, errors.sampleRate, die Rate-Limits und die Deduplizierung von Wiederholungen gelten alle. beforeError erhält ihn als HTTPError oder TimeoutError, mit dem Request unter context.request. Sie können ihn dort verwerfen oder redigieren. Ein Request, der auf privacy.networkBlocklist passt, wird nie gemeldet. Das SDK vermeidet es, dieselbe fetch-Ablehnung zweimal zu melden, wenn sie auch einen Unhandled-Rejection-Handler oder captureError() erreicht. Wenn Ihr Code nach einer 500-Response einen neuen Fehler wirft, hat dieser Fehler seinen eigenen Trace. Der fehlgeschlagene Request bleibt ein separater Bericht.

In AppSignal lesen

Fehlgeschlagene Requests erscheinen in der Errors-Ansicht des Browser-Bereichs als HTTPError- und TimeoutError-Issues. Sie werden nach der Route gruppiert, auf der sich der Nutzer befand, wie jeder andere Front-end-Fehler. Mehr dazu unter Front-end-Fehler in AppSignal. Öffnen Sie ein Issue, um seine Meldung, Breadcrumbs und Tags zu sehen. Wählen Sie auf der vollständigen Issue-Seite Traces. Wählen Sie dann Fullscreen in der Karte Trace timeline, um die unten gezeigte Ansicht zu öffnen. Wenn die Vorschau Spans auslässt, lautet die Schaltfläche All spans. Im Seitenpanel der Browser Errors führt Open full trace page Sie zur Issue-Seite. In der Vollbild-Trace-Timeline beschriftet Browser den Service des Browser-Spans. Wählen Sie diesen Span, um die Request- und Fehlerdetails zu sehen. Dieses Beispiel zeigt eine Produktseite, auf der GET /api/boom/ HTTP 500 zurückgab. In der Trace-Timeline können Sie den fehlgeschlagenen Request vom Browser bis in den Django-Service verfolgen:

Browser zeigt einen HTTPError auf /product/chocolate-stroopwafel (85 ms). Die Details des ausgewählten Spans zeigen die Request-URL und die HTTP-500-Response.
Darunter zeigt django GET api/boom/ mit einem RuntimeError (81 ms).
Der Django-Request enthält zwei SELECT-Spans und einen POST-Span, mit ihren Dauern.

Trace-Timeline, die einen 85 ms langen Browser-HTTPError für GET /api/boom/ (HTTP 500) mit einem 81 ms langen Django-RuntimeError verbindet, mit SELECT- und POST-Child-Spans. — Der fehlgeschlagene Browser-Request und die zugehörigen Django-Spans in einem Trace.

Die Service-Map zeigt den gesamten Trace von Anfang bis Ende: den Fehler im Django-Service, verbunden mit dem fehlgeschlagenen Request im Browser, der ihn ausgelöst hat.

Trace-Service-Map mit zwei Boxen, Browser und django, beide mit einem Fehler markiert, verbunden durch eine 81 ms lange Kante. — Die Service-Map für denselben Trace: der Back-end-Fehler, verbunden mit dem Browser-Fehler, der ihn ausgelöst hat.

Einem Trace beitreten, den Ihr Code gestartet hat

Ihre Anwendung setzt möglicherweise bereits einen gültigen traceparent auf einen Request, zum Beispiel über ein OpenTelemetry-Browser-SDK. AppSignal für Browser lässt diesen Header dann unangetastet, und ein fehlgeschlagener Request tritt dem Trace bei, den Ihr Code gestartet hat. Das gilt gleichermaßen für fetch und XMLHttpRequest. Öffnen Sie im Tab Traces des Issues die Trace-Timeline im Vollbildmodus, um die Back-end-Arbeit zu untersuchen.

SDKs & Telemetrie

Sprach-SDKs

Telemetrie-Tools

Bevor Sie beginnen

Aktivieren

Was gemeldet wird

In AppSignal lesen

Einem Trace beitreten, den Ihr Code gestartet hat

​Bevor Sie beginnen

​Aktivieren

​Was gemeldet wird

​In AppSignal lesen

​Einem Trace beitreten, den Ihr Code gestartet hat

Bevor Sie beginnen

Aktivieren

Was gemeldet wird

In AppSignal lesen

Einem Trace beitreten, den Ihr Code gestartet hat