Traces OpenTelemetry depuis le navigateur

Le SDK JavaScript OpenTelemetry pour les navigateurs se compose de plusieurs paquets : @opentelemetry/sdk-trace-web fournit l'implémentation centrale du traçage, @opentelemetry/instrumentation-fetch crée automatiquement des unités de trace pour tous les appels de l'API fetch et @opentelemetry/exporter-trace-otlp-http envoie les unités de trace à un collecteur.

TracerProvider est l'objet central de configuration d'OpenTelemetry. Il contient la liste des SpanProcessors (qui déterminent ce qui arrive aux unités de trace terminées), la ressource décrivant votre application (nom du service, version) et toute configuration d'échantillonnage.

BatchSpanProcessor rassemble les unités de trace terminées en mémoire et les exporte par lots au lieu d'envoyer chaque unité individuellement. Cela réduit considérablement le nombre de requêtes HTTP adressées à votre collecteur, améliore les performances du navigateur et diminue la charge sur le point de terminaison du collecteur OTel.

OTLPTraceExporter envoie des unités de trace regroupées à un collecteur compatible avec OpenTelemetry via HTTP, au format JSON ou protobuf. Vous configurez l'URL du collecteur (par exemple, le point de terminaison mandataire de votre collecteur OpenTelemetry), puis l'exportateur gère automatiquement la sérialisation et la logique de nouvelle tentative.

Une unité de trace représente une seule opération au sein d'une trace : le montage d'un composant, un appel d'API ou une interaction de l'utilisateur. Les unités de trace possèdent un nom, une heure de début, une heure de fin, un état (OK ou ERROR) et un ensemble d'attributs clé-valeur. Les unités de trace associées sont reliées par un ID de trace partagé et par des relations parent-enfant.

Créez un traceur avec provider.getTracer('react-app') et démarrez des unités de trace avec tracer.startSpan('component-mount'). Une fois l'opération terminée, appelez span.end() pour enregistrer l'heure de fin. Terminez toujours les unités de trace : les unités abandonnées gaspillent de la mémoire et produisent des données incomplètes dans votre serveur d'observabilité.

Les attributs enrichissent les unités de trace avec des données contextuelles : span.setAttribute('user.id', userId) ou span.setAttribute('route', location.pathname). Les attributs peuvent être recherchés dans votre serveur d'observabilité, ce qui permet d'effectuer des requêtes comme « afficher toutes les unités de trace lentes pour l'utilisateur 42 » ou « afficher toutes les erreurs sur la route /checkout ».

@opentelemetry/instrumentation-fetch modifie la fonction globale fetch afin de créer automatiquement des unités de trace pour chaque requête HTTP sortante. L'unité de trace capture l'URL, la méthode, le code d'état HTTP et la durée, sans aucune modification de vos appels fetch existants.

Lorsque l’instrumentation de fetch crée un segment pour une requête sortante, elle injecte l’en-tête traceparent de W3C TraceContext dans la requête. Le serveur destinataire lit cet en-tête et poursuit la même trace, créant ainsi une trace connectée qui couvre le navigateur et le serveur.

L’initialisation d’OpenTelemetry doit avoir lieu avant le montage de tout composant — généralement dans le fichier d’entrée de l’application (main.tsx), avant l’appel à ReactDOM.createRoot. Créez le fournisseur, enregistrez les processeurs et les exportateurs, puis appelez provider.register() pour en faire le TracerProvider global.

Enregistrer chaque interaction utilisateur dans des applications à fort trafic génère des quantités énormes de données de trace. Configurez un échantillonneur TraceIdRatioBased (par exemple, échantillonnez 10 % des traces) dans le TracerProvider afin de réduire le volume. Échantillonnez toujours 100 % des traces d’erreur à l’aide d’un échantillonneur ParentBased pour vous assurer qu’aucune erreur ne passe inaperçue.

Pourquoi utiliser BatchSpanProcessor plutôt que SimpleSpanProcessor dans les applications de navigateur ?

Le SDK JavaScript d’OpenTelemetry instrumente les navigateurs avec TracerProvider, BatchSpanProcessor et OTLPTraceExporter. Les segments représentent des unités de travail enrichies d’attributs. L’instrumentation de fetch crée automatiquement des segments pour les appels d’API et injecte des en-têtes W3C TraceContext pour le traçage distribué de bout en bout. Initialisez tôt, échantillonnez de manière appropriée et terminez toujours les segments afin de conserver des données de trace propres.