Zum Hauptinhalt springen
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 Produktseite meldet einen fehlgeschlagenen 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:
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 diesen Trace: der Back-end-Fehler, verbunden mit dem Browser-Fehler, der ihn ausgelöst hat.

Um den Browser-Fehler mit der Arbeit im Back-end zu verbinden, richten Sie beide Seiten ein:
  1. Browser: Fügen Sie Ihre API-URL-Muster zu tracePropagationTargets hinzu. Passende Requests tragen einen traceparent-Header und einen tracestate-Header, der den Browser-Service und seine Route nennt. Eine 5xx-Response oder ein qualifizierender Timeout wird zu einem Browser-Fehler.
  2. Empfangendes Back-end: Instrumentieren Sie den Service, der diese Requests bearbeitet. Die Instrumentierung liest traceparent und meldet Spans über einen gehosteten AppSignal-Collector. 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 das Back-end 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

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 das appsignal-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 traceparent aus 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 mit otel.SetTextMapPropagator.
  • traceparent und tracestate über Origins hinweg erlauben. Ein Back-end kann auf einem anderen Origin liegen, etwa api.example.com, aufgerufen von www.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 nur traceparent erlaubt, blockiert der Browser den Request:
Node.js und Elixir werden noch nicht unterstützt. Bei einem Node.js-Back-end, etwa Express oder Next.js-API-Routen, werden fehlgeschlagene Requests weiterhin als Browser-Fehler gemeldet. Ihre Traces zeigen keine Back-end-Spans.

Aktivieren

Fügen Sie für jeden Back-end-Host und -Pfad ein Muster zu tracePropagationTargets hinzu. Die standardmäßig leere Liste lässt das Tracing ausgeschaltet:
Muster werden gegen den Host und Pfad jedes 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 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. 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 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 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:
  • 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.

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.