OpenTelemetry-Traces aus dem Browser

Das OpenTelemetry-JavaScript-SDK für Browser besteht aus mehreren Paketen: @opentelemetry/sdk-trace-web stellt die zentrale Tracing-Implementierung bereit, @opentelemetry/instrumentation-fetch erstellt automatisch Spans für alle fetch-API-Aufrufe und @opentelemetry/exporter-trace-otlp-http sendet Spans an einen Collector.

Der TracerProvider ist das zentrale Konfigurationsobjekt in OpenTelemetry. Er enthält die Liste der SpanProcessors (die bestimmen, was mit abgeschlossenen Spans geschieht), die Resource, die Ihre Anwendung beschreibt (Servicename, Version), sowie alle Sampling-Konfigurationen.

Der BatchSpanProcessor sammelt abgeschlossene Spans im Speicher und exportiert sie in Batches, statt jeden Span einzeln zu senden. Dadurch wird die Anzahl der HTTP-Anfragen an Ihren Collector drastisch reduziert, die Browser-Performance verbessert und die Last auf dem OTel-Collector-Endpunkt verringert.

OTLPTraceExporter sendet gebündelte Spans über HTTP im JSON- oder Protobuf-Format an einen OpenTelemetry-kompatiblen Collector. Sie konfigurieren die Collector-URL (z. B. den Proxy-Endpunkt Ihres OTel Collectors), und der Exporter übernimmt Serialisierung und Wiederholungslogik automatisch.

Ein Span repräsentiert eine einzelne Arbeitseinheit innerhalb eines Traces: das Mounten einer Komponente, einen API-Aufruf oder eine Benutzerinteraktion. Spans haben einen Namen, eine Startzeit, eine Endzeit, einen Status (OK oder ERROR) und eine Reihe von Schlüssel-Wert-Attributen. Zusammengehörige Spans sind durch eine gemeinsame Trace-ID und Eltern-Kind-Beziehungen miteinander verknüpft.

Sie erstellen einen Tracer mit provider.getTracer('react-app') und starten Spans mit tracer.startSpan('component-mount'). Rufen Sie nach Abschluss der Arbeit span.end() auf, um die Endzeit zu erfassen. Beenden Sie Spans immer — nicht freigegebene Spans verbrauchen Speicher und erzeugen unvollständige Daten in Ihrem Observability-Backend.

Attribute reichern Spans mit Kontextdaten an: span.setAttribute('user.id', userId) oder span.setAttribute('route', location.pathname). Attribute können in Ihrem Observability-Backend durchsucht werden und ermöglichen Abfragen wie „alle langsamen Spans für Benutzer 42 anzeigen“ oder „alle Fehler auf der Route /checkout anzeigen“.

@opentelemetry/instrumentation-fetch ersetzt die globale fetch-Funktion per Monkey-Patching, um automatisch Spans für jede ausgehende HTTP-Anfrage zu erstellen. Der Span erfasst URL, Methode, HTTP-Statuscode und Dauer, ohne dass Sie Ihre bestehenden fetch-Aufrufe ändern müssen.

Wenn die fetch-Instrumentierung für eine ausgehende Anfrage einen Span erstellt, fügt sie den W3C-TraceContext-Header traceparent in die Anfrage ein. Das empfangende Backend liest diesen Header und setzt denselben Trace fort, wodurch ein verbundener Trace entsteht, der Browser und Server umfasst.

Die Initialisierung von OTel muss erfolgen, bevor Komponenten gemountet werden – typischerweise in der Einstiegdatei der App (main.tsx), vor dem Aufruf von ReactDOM.createRoot. Erstellen Sie den Provider, registrieren Sie Prozessoren und Exporter und rufen Sie provider.register() auf, damit er zum globalen TracerProvider wird.

Das Aufzeichnen jeder Benutzerinteraktion in Anwendungen mit hohem Datenverkehr erzeugt riesige Mengen an Trace-Daten. Konfigurieren Sie im TracerProvider einen Sampler vom Typ TraceIdRatioBased (z. B. 10 % der Traces), um das Volumen zu reduzieren. Erfassen Sie mit einem Sampler vom Typ ParentBased immer 100 % der Fehler-Traces, damit kein Fehler übersehen wird.

Warum wird BatchSpanProcessor in Browseranwendungen anstelle eines SimpleSpanProcessor verwendet?

Das OpenTelemetry JavaScript SDK instrumentiert Browser mit TracerProvider, BatchSpanProcessor und OTLPTraceExporter. Spans stellen Arbeitseinheiten dar, die durch Attribute angereichert werden. Die Fetch-Instrumentierung erstellt automatisch Spans für API-Aufrufe und fügt W3C-TraceContext-Header für verteiltes Tracing von Ende zu Ende ein. Initialisieren Sie frühzeitig, führen Sie passendes Sampling durch und beenden Sie Spans immer, um saubere Trace-Daten zu gewährleisten.