Trace OpenTelemetry dal browser

L'SDK JavaScript di OpenTelemetry per i browser è composto da diversi pacchetti: @opentelemetry/sdk-trace-web fornisce l'implementazione di base del tracing, @opentelemetry/instrumentation-fetch crea automaticamente gli span per tutte le chiamate all'API fetch e @opentelemetry/exporter-trace-otlp-http invia gli span a un collector.

TracerProvider è l'oggetto centrale per la configurazione in OpenTelemetry. Contiene l'elenco degli SpanProcessors, che determinano cosa accade agli span completati, la resource che descrive l'applicazione, inclusi nome e versione del servizio, e qualsiasi configurazione di sampling.

BatchSpanProcessor raccoglie in memoria gli span completati e li esporta in batch anziché inviare ogni span singolarmente. In questo modo riduce drasticamente il numero di richieste HTTP al collector, migliorando le prestazioni del browser e riducendo il carico sull'endpoint del collector OTel.

OTLPTraceExporter invia gli span raggruppati a un collector compatibile con OpenTelemetry tramite HTTP, in formato JSON o protobuf. Si configura l'URL del collector, ad esempio l'endpoint proxy del vostro OTel Collector, e l'exporter gestisce automaticamente la serializzazione e la logica di retry.

Uno Span rappresenta una singola unità di lavoro all'interno di una traccia: il montaggio di un componente, una chiamata API o un'interazione dell'utente. Gli span hanno un nome, un'ora di inizio, un'ora di fine, uno stato (OK o ERROR) e un insieme di attributi chiave-valore. Gli span correlati sono collegati da un trace ID condiviso e da relazioni padre-figlio.

Si crea un tracer con provider.getTracer('react-app') e si avviano gli span con tracer.startSpan('component-mount'). Al termine dell'operazione, si chiama span.end() per registrare l'ora di fine. È importante chiudere sempre gli span: quelli lasciati aperti sprecano memoria e producono dati incompleti nel backend di osservabilità.

Gli attributi arricchiscono gli span con dati contestuali: span.setAttribute('user.id', userId) o span.setAttribute('route', location.pathname). Gli attributi sono ricercabili nel backend di osservabilità e consentono query come "mostra tutti gli span lenti per l'utente 42" o "mostra tutti gli errori sulla rotta /checkout".

@opentelemetry/instrumentation-fetch applica una monkey patch alla funzione globale fetch per creare automaticamente span per ogni richiesta HTTP in uscita. Lo span registra l'URL, il metodo, il codice di stato HTTP e la durata senza richiedere modifiche alle chiamate fetch esistenti.

Quando la strumentazione fetch crea uno span per una richiesta in uscita, inietta l'header traceparent di W3C TraceContext nella richiesta. Il backend ricevente legge questo header e continua la stessa traccia, creando una traccia collegata che comprende browser e server.

L'inizializzazione di OTel deve avvenire prima del montaggio di qualsiasi componente, in genere nel file di ingresso dell'app (main.tsx), prima della chiamata a ReactDOM.createRoot. Crei il provider, registri processor ed exporter e chiami provider.register() per renderlo il TracerProvider globale.

La registrazione di ogni interazione dell'utente nelle app ad alto traffico genera enormi quantità di dati di traccia. Configuri un sampler TraceIdRatioBased nel TracerProvider (ad esempio, per campionare il 10% delle tracce) così da ridurre il volume. Campioni sempre il 100% delle tracce con errori utilizzando un sampler ParentBased, per assicurarsi che nessun errore venga ignorato.

L'SDK JavaScript di OpenTelemetry strumenta i browser con TracerProvider, BatchSpanProcessor e OTLPTraceExporter. Gli span rappresentano unità di lavoro arricchite con attributi. La strumentazione fetch crea automaticamente span per le chiamate API e inietta gli header W3C TraceContext per il tracing distribuito end-to-end. Inizializzi presto, configuri il campionamento in modo appropriato e termini sempre gli span per mantenere puliti i dati di traccia.