Guide

La tua app Vue gira sulla macchina di qualcun altro, su una rete che non controlli, in una versione di browser che non hai scelto. I log del server ti dicono che è arrivata una richiesta ed è uscita una risposta; non ti dicono nulla dei quattro secondi passati dall'utente a fissare uno spinner. OpenTelemetry è lo standard neutrale che chiude quel buco: un solo modo di produrre tracce, metriche e log, e qualsiasi backend che parli il protocollo può riceverli.

Il guadagno è una traccia unica che comincia nel browser e finisce nel tuo database. Uno span di caricamento del documento, poi il fetch che la pagina lancia, poi lo span server che quel fetch ha provocato, tutto ricucito dal contesto di traccia propagato negli header HTTP. È proprio quello che né i devtools di Vue né l'agente lato server del tuo APM danno da soli, ed è il motivo per cui si ricorre a OpenTelemetry sul front end.

SDK stabile, terreno mobile

Veniamo alla parte onesta, quella che si sorvola di continuo. L'SDK di tracing per browser, `@opentelemetry/sdk-trace-web`, è marcato stabile nel repository OpenTelemetry JS. Ma la documentazione ufficiale è netta sul quadro d'insieme: «Client instrumentation for the browser is experimental and mostly unspecified». Le due affermazioni sono vere insieme e non si contraddicono. L'idraulica che crea ed esporta gli span è assestata; le convenzioni su cosa dovrebbe contenere uno span di browser, e su quali segnali un front end dovrebbe emettere, non lo sono.

C'è anche un cantiere più recente da conoscere prima di costruire su supposizioni. Il repository `open-telemetry/opentelemetry-browser` pubblica `@opentelemetry/browser-instrumentation`, il cui stato è indicato come sperimentale. Il suo approccio differisce dai pacchetti più vecchi: emette record di log strutturati per le prestazioni del browser e le interazioni utente, a complemento delle strumentazioni basate su span mantenute altrove. Chi comincia oggi costruisca sulla via stabile degli span e tratti quella basata su eventi come qualcosa da tenere d'occhio, non da cui dipendere.

I pacchetti e il cablaggio

L'insieme di pacchetti utile è piccolo. `@opentelemetry/api` fornisce l'interfaccia tracer, `@opentelemetry/sdk-trace-web` il provider per browser, `@opentelemetry/sdk-trace-base` i processori di span e l'exporter su console, `@opentelemetry/context-zone` il context manager e `@opentelemetry/instrumentation` l'utilità di registrazione. Le singole strumentazioni arrivano a parte, come gli exporter OTLP. Nulla qui è specifico di Vue, il che è già un indizio su quel che segue.

• `@opentelemetry/sdk-trace-web` è stabile, ma la documentazione ufficiale afferma che la strumentazione client per il browser è sperimentale e in gran parte non specificata
• Tre chiamate per cablarlo: creare `WebTracerProvider` con i processori di span, `provider.register()` con `ZoneContextManager`, poi `registerInstrumentations()`
• La copertura pronta all'uso è caricamento del documento, interazioni utente, XHR e fetch - raggruppati in `@opentelemetry/auto-instrumentations-web`
• Non esiste una strumentazione Vue ufficiale: gli span di componenti e router sono codice che scrivi e mantieni tu
• `@opentelemetry/browser-instrumentation` (il più recente repository opentelemetry-browser) è sperimentale ed emette record di log strutturati invece di span
• `SimpleSpanProcessor` con la console per lo sviluppo, `BatchSpanProcessor` con un exporter OTLP per la produzione

Il cablaggio sono tre chiamate. Crei il provider con i suoi processori di span, per esempio `new WebTracerProvider({ spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())] })`. Lo registri con un context manager, `provider.register({ contextManager: new ZoneContextManager() })`. Poi registri le tue strumentazioni con `registerInstrumentations({ instrumentations: [new DocumentLoadInstrumentation()] })`. Console e `SimpleSpanProcessor` servono in sviluppo; in produzione vuoi `BatchSpanProcessor` e un exporter OTLP, così gli span partono a lotti invece di una richiesta per span.

Cosa cattura l'auto-instrumentation

Quello che le strumentazioni pronte catturano davvero è più stretto di quanto ci si aspetti. `@opentelemetry/instrumentation-document-load` produce span per il caricamento del documento e il navigation timing. `@opentelemetry/instrumentation-user-interaction` traccia le interazioni utente, i clic per esempio. `@opentelemetry/instrumentation-xml-http-request` e l'equivalente per fetch coprono le richieste in uscita. `@opentelemetry/auto-instrumentations-web` le raggruppa, così ne registri una invece di quattro. In tutto ottieni caricamento pagina, clic e chiamate di rete: copertura reale, ma copertura del browser, non dei tuoi componenti.

Il context manager merita una sosta. `ZoneContextManager` esiste perché il contesto asincrono non si propaga da solo in un browser: senza di lui, uno span aperto prima di un await perde spesso il suo genitore e la traccia si frammenta in orfani. Si appoggia a zone.js, il che significa spedire ed eseguire quella libreria nel tuo bundle. È un costo reale in peso e in global patchati, ed è proprio il tipo di compromesso che conviene misurare invece che supporre, soprattutto su uno stack che lavora sui suoi Core Web Vitals.

Il buco a forma di Vue

Ora il buco. Non esiste una strumentazione Vue ufficiale. Né nel repository principale né nei pacchetti contrib. Quello che circola come «strumentazione Vue» nei post di blog e nelle guide dei fornitori è codice scritto a mano: span aperti negli hook del ciclo di vita, span avvolti attorno alle navigation guard del router, un plugin che avvia uno span per render di componente. È del tutto ragionevole costruirlo e può servire davvero, ma va saputo che lo scrivi e lo mantieni tu, senza convenzioni semantiche a cui aderire e senza un upstream da cui ereditare correzioni.

Dove vanno i dati è l'ultima decisione, e quella che determina se tutto questo ripaga. L'exporter parla OTLP su HTTP verso un collector o direttamente verso un backend; da lì la scelta dello strumento è tua, proprio perché lo standard è neutrale. Comincia più in piccolo di quanto pensi: `ConsoleSpanExporter` finché gli span non sembrano corretti nei devtools, poi document-load e fetch verso un backend vero, poi decidi se gli span a livello di componente si guadagnano il posto. Strumentare tutto il primo giorno è il modo in cui i progetti di osservabilità front end finiscono in rumore che nessuno legge.