Trazas de OpenTelemetry desde el navegador

El SDK de JavaScript de OpenTelemetry para navegadores consta de varios paquetes: @opentelemetry/sdk-trace-web proporciona la implementación principal de trazas, @opentelemetry/instrumentation-fetch crea automáticamente spans para todas las llamadas a la API fetch y @opentelemetry/exporter-trace-otlp-http envía los spans a un collector.

TracerProvider es el objeto de configuración central de OpenTelemetry. Contiene la lista de SpanProcessors (que determinan qué ocurre con los spans completados), el recurso que describe su aplicación (nombre del servicio y versión) y cualquier configuración de muestreo.

BatchSpanProcessor recopila los spans completados en memoria y los exporta en lotes, en lugar de enviar cada span individualmente. Esto reduce drásticamente el número de solicitudes HTTP al collector, mejora el rendimiento del navegador y reduce la carga del endpoint del collector de OTel.

OTLPTraceExporter envía spans agrupados a un collector compatible con OpenTelemetry mediante HTTP, en formato JSON o protobuf. Configure la URL del collector (por ejemplo, el endpoint proxy de su OTel Collector) y el exporter gestionará automáticamente la serialización y la lógica de reintento.

Un Span representa una unidad de trabajo individual dentro de una traza: el montaje de un componente, una llamada a una API o una interacción del usuario. Los spans tienen un nombre, una hora de inicio, una hora de finalización, un estado (OK o ERROR) y un conjunto de atributos clave-valor. Los spans relacionados se vinculan mediante un mismo ID de traza y relaciones padre-hijo.

Cree un tracer con provider.getTracer('react-app') e inicie spans con tracer.startSpan('component-mount'). Cuando termine el trabajo, llame a span.end() para registrar la hora de finalización. Finalice siempre los spans; los spans que quedan abiertos desperdician memoria y generan datos incompletos en su backend de observabilidad.

Los atributos enriquecen los spans con datos contextuales: span.setAttribute('user.id', userId) o span.setAttribute('route', location.pathname). Los atributos permiten realizar búsquedas en su backend de observabilidad, lo que habilita consultas como «mostrar todos los spans lentos del usuario 42» o «mostrar todos los errores de la ruta /checkout».

@opentelemetry/instrumentation-fetch modifica la función fetch global mediante monkey patching para crear automáticamente spans para cada solicitud HTTP saliente. El span captura la URL, el método, el código de estado HTTP y la duración sin que tenga que modificar sus llamadas fetch existentes.

Cuando la instrumentación de fetch crea un span para una solicitud saliente, inyecta el encabezado traceparent de W3C TraceContext en la solicitud. El backend receptor lee este encabezado y continúa la misma traza, creando una traza conectada que abarca el navegador y el servidor.

La inicialización de OTel debe realizarse antes de montar cualquier componente, normalmente en el archivo de entrada de la aplicación (main.tsx), antes de la llamada a ReactDOM.createRoot. Cree el proveedor, registre los procesadores y exportadores, y llame a provider.register() para convertirlo en el TracerProvider global.

Registrar cada interacción del usuario en aplicaciones con mucho tráfico genera cantidades enormes de datos de trazas. Configure un muestreador TraceIdRatioBased (por ejemplo, para muestrear el 10 % de las trazas) en el TracerProvider con el fin de reducir el volumen. Muestree siempre el 100 % de las trazas con errores mediante un muestreador ParentBased para asegurarse de no omitir ningún error.

¿Por qué se utiliza BatchSpanProcessor en lugar de SimpleSpanProcessor en aplicaciones de navegador?

El SDK de OpenTelemetry para JavaScript instrumenta los navegadores con TracerProvider, BatchSpanProcessor y OTLPTraceExporter. Los spans representan unidades de trabajo enriquecidas con atributos. La instrumentación de fetch crea automáticamente spans para las llamadas a API e inyecta encabezados de W3C TraceContext para realizar un seguimiento distribuido de extremo a extremo. Inicialice pronto, configure el muestreo adecuadamente y finalice siempre los spans para mantener datos de trazas limpios.