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.GET /api/boom/-Request: HTTP 500. Sie wissen, dass der Request fehlgeschlagen ist, aber nicht warum. Verteiltes Tracing verfolgt diesen Request vom Browser bis in das Back-end, das ihn bearbeitet und einen RuntimeError ausgelöst hat. In diesem Beispiel ist das eine Django-App. Jedes Back-end, das verteiltes Tracing unterstützt, funktioniert genauso.
Die Service-Map zeigt beide Seiten dieses Trace:

Die Service-Map für diesen Trace: der Back-end-Fehler, verbunden mit dem Browser-Fehler, der ihn ausgelöst hat.
- Browser: Fügen Sie Ihre API-URL-Muster zu
tracePropagationTargetshinzu. Passende Requests tragen einentraceparent-Header und einentracestate-Header, der den Browser-Service und seine Route nennt. Eine 5xx-Response oder ein qualifizierender Timeout wird zu einem Browser-Fehler. - Empfangendes Back-end: Instrumentieren Sie den Service, der diese Requests bearbeitet. Die Instrumentierung liest
traceparentund meldet Spans über einen gehosteten AppSignal-Collector. Verwenden Sie eine unterstützte Integration oder eine OpenTelemetry-Instrumentierung für sein Framework.
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
Ihr Front-end braucht nur das Browser-SDK. Der Rest der Einrichtung liegt im Back-end: dem Service, der die Requests Ihres Front-ends bearbeitet. Im Beispiel oben ist das der Django-Service. Er kann eine API auf einem eigenen Host sein oder dieselbe App, die Ihre Seiten ausliefert. Richten Sie ihn zuerst ein, damit seine Spans im Trace erscheinen, wenn ein Request fehlschlägt:- Über einen gehosteten Collector melden. Öffnen Sie auf der Seite „Hosted Collectors” in den Einstellungen Ihrer Organisation einen Collector und kopieren Sie seine Collector URL. Senden Sie die Daten des Service an diese URL. Ist die Liste leer, erstellen Sie dort zuerst einen Collector. Verteiltes Tracing funktioniert nur über einen gehosteten Collector. Setzen Sie in Python und Ruby die URL als
collector_endpoint-Option. Ruby benötigt außerdem dasappsignal-opentelemetry-Gem. - Einen Servicenamen festlegen. Geben Sie dem Service einen eigenen Namen. Der Trace nutzt ihn, um den Service von Browser und anderen Services zu unterscheiden. Wo Sie ihn setzen, hängt von der Sprache des Back-ends ab:
- Dessen HTTP-Server instrumentieren. Verwenden Sie eine Integration für sein Framework, die
traceparentaus eingehenden Requests liest. So tritt der Service dem Trace des Browsers bei, statt einen eigenen zu starten. Registrieren Sie in Go außerdem einen Propagator mitotel.SetTextMapPropagator. traceparentundtracestateüber Origins hinweg erlauben. Ein Back-end kann auf einem anderen Origin liegen, etwaapi.example.com, aufgerufen vonwww.example.com. Der Browser sendet dann möglicherweise vor dem Request einen CORS-Preflight. Erlauben Sie beide Header in der Response des Back-ends auf den Preflight. Wenn es nurtraceparenterlaubt, blockiert der Browser den Request:
Aktivieren
Fügen Sie für jeden Back-end-Host und -Pfad ein Muster zutracePropagationTargets hinzu. Die standardmäßig leere Liste lässt das Tracing ausgeschaltet:
fetch- und XMLHttpRequest-Aufrufs abgeglichen. Weil das SDK sich in diese Browser-APIs einklinkt, ist die Einrichtung in React, Vue oder reinem JavaScript dieselbe. Das schließt Bibliotheken ein, die darauf aufbauen, etwa axios.
Muster ignorieren das Schema und den Query-String. Eine relative URL wird gegen die Adresse der Seite aufgelöst. Ein Aufruf von /api/orders von www.example.com aus trifft deshalb auf www.example.com/api/**. Verwenden Sie * innerhalb eines Pfadsegments oder ** über Segmente hinweg. Geben Sie sowohl einen Host als auch einen Pfad an:
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 den Host Ihres Back-ends 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 traceparent- und tracestate-Header tragen. Prüfen Sie anschließend einen fehlgeschlagenen Request in AppSignal, um zu sehen, ob Back-end-Spans in seinem Trace erscheinen.
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 einentraceparent-Header gesendet hat:
- Eine 5xx-Response wird als
HTTPErrorgemeldet. - Ein Timeout wird als
TimeoutErrorgemeldet. Das ist einfetch, der mit einemTimeoutErrorabgelehnt wird, wie es ein durchAbortSignal.timeout()begrenzter tut. Es ist auch einXMLHttpRequest, dessentimeoutauslöst. Der Server hat einen Request mit Timeout möglicherweise empfangen und in einem Trace erfasst.
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: dieurl, diemethod, denstatus, wenn eine Response eingetroffen ist, und dieduration_ms. Query-Parameter werden gemäß Ihrer Allowlist aus der URL entfernt. - Den Span: die Trace-ID und Span-ID aus dem
traceparentdes 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.
- 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.
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. Seine Schaltfläche Open trace öffnet die Timeline dieses Traces.
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 alsHTTPError- 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 im Seitenpanel zu sehen. Sein Tab Sample zeigt außerdem den Trace: die Karten Trace service map, Trace timeline und die zugehörigen Log-Zeilen. Wählen Sie 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. Open full trace page, das Symbol neben der Issue-Nummer, öffnet die vollständige 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.
Im Beispiel der Produktseite gab GET /api/boom/ HTTP 500 zurück. In der Trace-Timeline können Sie den fehlgeschlagenen Request vom Browser bis in den Django-Service verfolgen:
Browserzeigt einenHTTPErrorauf/product/chocolate-stroopwafel(85 ms). Die Details des ausgewählten Spans zeigen die Request-URL und die HTTP-500-Response.- Darunter zeigt
djangoGET api/boom/mit einemRuntimeError(81 ms). - Der Django-Request enthält zwei
SELECT-Spans und einenPOST-Span, mit ihren Dauern.

Der fehlgeschlagene Browser-Request und die zugehörigen Django-Spans in einem Trace.
Einem Trace beitreten, den Ihr Code gestartet hat
Ihre Anwendung setzt möglicherweise bereits einen gültigentraceparent 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.