Ślady OpenTelemetry z przeglądarki

SDK JavaScript OpenTelemetry dla przeglądarek składa się z kilku pakietów: @opentelemetry/sdk-trace-web udostępnia podstawową implementację śledzenia, @opentelemetry/instrumentation-fetch automatycznie tworzy spany dla wszystkich wywołań Fetch API, a @opentelemetry/exporter-trace-otlp-http wysyła spany do kolektora.

TracerProvider jest centralnym obiektem konfiguracyjnym w OpenTelemetry. Przechowuje listę SpanProcessors (określających, co dzieje się z ukończonymi spanami), zasób opisujący aplikację (nazwę usługi i wersję) oraz konfigurację próbkowania.

BatchSpanProcessor gromadzi ukończone spany w pamięci i eksportuje je partiami zamiast wysyłać każdy span osobno. Znacznie zmniejsza to liczbę żądań HTTP do kolektora, poprawiając wydajność przeglądarki i zmniejszając obciążenie punktu końcowego kolektora OTel.

OTLPTraceExporter wysyła spany zebrane w partiach do kolektora zgodnego z OpenTelemetry za pośrednictwem HTTP w formacie JSON lub protobuf. Należy skonfigurować adres URL kolektora (np. punkt końcowy proxy OTel Collector), a eksporter automatycznie obsłuży serializację i logikę ponawiania prób.

Span reprezentuje pojedynczą jednostkę pracy w ramach śladu: zamontowanie komponentu, wywołanie API lub interakcję użytkownika. Spany mają nazwę, czas rozpoczęcia, czas zakończenia, status (OK lub ERROR) oraz zestaw atrybutów klucz-wartość. Powiązane spany są łączone wspólnym identyfikatorem śladu i relacjami nadrzędny-podrzędny.

Należy utworzyć tracer za pomocą provider.getTracer('react-app') i rozpocząć spany za pomocą tracer.startSpan('component-mount'). Po zakończeniu pracy należy wywołać span.end(), aby zapisać czas zakończenia. Spany należy zawsze kończyć — pozostawione spany marnują pamięć i generują niekompletne dane w backendzie obserwowalności.

Atrybuty wzbogacają spany o dane kontekstowe: span.setAttribute('user.id', userId) lub span.setAttribute('route', location.pathname). Atrybuty można przeszukiwać w backendzie obserwowalności, co umożliwia wykonywanie zapytań takich jak „pokaż wszystkie wolne spany użytkownika 42” lub „pokaż wszystkie błędy na trasie /checkout”.

@opentelemetry/instrumentation-fetch zastępuje globalną funkcję fetch za pomocą monkey patchingu, aby automatycznie tworzyć spany dla każdego wychodzącego żądania HTTP. Span rejestruje URL, metodę, kod statusu HTTP i czas trwania bez konieczności wprowadzania zmian w istniejących wywołaniach fetch.

Gdy instrumentacja fetch tworzy span dla wychodzącego żądania, wstrzykuje do żądania nagłówek traceparent standardu W3C TraceContext. Backend odbierający żądanie odczytuje ten nagłówek i kontynuuje ten sam trace, tworząc połączony trace obejmujący przeglądarkę i serwer.

Inicjalizacja OTel musi nastąpić przed zamontowaniem jakichkolwiek komponentów — zwykle w pliku wejściowym aplikacji (main.tsx), przed wywołaniem ReactDOM.createRoot. Należy utworzyć providera, zarejestrować procesory i eksportery oraz wywołać provider.register(), aby ustanowić go globalnym TracerProvider.

Rejestrowanie każdej interakcji użytkownika w aplikacjach o dużym ruchu generuje ogromną ilość danych trace. Aby zmniejszyć ich ilość, należy skonfigurować sampler TraceIdRatioBased (np. próbkować 10% trace) w TracerProvider. Należy zawsze próbkować 100% trace zawierających błędy, używając samplera ParentBased, aby mieć pewność, że żaden błąd nie zostanie pominięty.

Dlaczego w aplikacjach przeglądarkowych używa się BatchSpanProcessor zamiast SimpleSpanProcessor?

OpenTelemetry JavaScript SDK instrumentuje przeglądarki za pomocą TracerProvider, BatchSpanProcessor i OTLPTraceExporter. Spany reprezentują jednostki pracy wzbogacone o atrybuty. Instrumentacja fetch automatycznie tworzy spany dla wywołań API i wstrzykuje nagłówki W3C TraceContext, umożliwiając rozproszone śledzenie od początku do końca. Należy inicjalizować OTel odpowiednio wcześnie, właściwie dobierać próbkowanie i zawsze kończyć spany, aby zachować uporządkowane dane trace.