Un Span est le nom de l’objet que nous utilisons pour capturer des données sur une erreur et son contexte environnant. Il est conçu pour être similaire, mais pas exactement identique, au Span de la spécification standard OpenTelemetry.
Créer un nouveau Span
Un Span peut être créé en appelant appsignal.createSpan(), qui initialise un nouvel objet Span avec toutes les options par défaut que vous avez passées lors de l’initialisation de l’objet Appsignal.
const span = appsignal.createSpan();
createSpan() peut également prendre une fonction en paramètre, vous permettant de définir les données du Span en même temps qu’il est créé.
const span = appsignal.createSpan((span) => {
return span.setTags({
tag: "value",
});
});
Spans ne peuvent pas être imbriqués, et plusieurs Spans ne peuvent pas être passés à appsignal.send() en même temps. Nous recommandons d’utiliser Promise.all pour les opérations send concurrentes.
const span1 = appsignal.createSpan();
const span2 = appsignal.createSpan();
Promise.all([appsignal.send(span1), appsignal.send(span2)]);
Mettre à jour un Span
Après la création d’un Span, vous pouvez commencer à y ajouter des données en utilisant les méthodes sur l’objet Span :
const span = appsignal.createSpan();
span.setTags({ tag: "value" });
console.log(span.serialize().tags); // { tag: "value" }
Span renvoie this, vous permettant de chaîner les méthodes ensemble :
const span = appsignal.createSpan();
span.setTags({ tag: "value" }).setError(new Error("test error"));
console.log(span.serialize().tags); // { tag: "value" }
console.log(span.serialize().error); // { name: "Error", message: "test error", backtrace: [...] }
span.setAction(name: string)
Définit l’action du Span actuel. L’action ne doit jamais être une chaîne vide - elle peut être soit undefined, soit une chaîne non vide. Un nom d’action est utilisé pour identifier l’emplacement d’un certain échantillon d’erreur et de problèmes de performance.
span.setNamespace(name: string)
Définit le namespace du Span actuel. Les espaces de noms sont un moyen de regrouper les incidents d’erreur, les incidents de performance et les métriques d’hôte dans votre application.
span.setError(error: Error | object)
Définit l’error du Span actuel. L’objet Error a une propriété name, message et backtrace. Veillez à n’utiliser que quelque chose décrivant le type de l’erreur comme name. AppSignal regroupe les erreurs en fonction de ce nom. Vous pouvez mettre tout ce que vous voulez dans le message.
Lorsqu’un objet Error est passé à la méthode setError, la propriété stack est normalisée et transformée en un tableau de chaînes, chaque chaîne représentant une ligne dans la stacktrace. Pour une cohérence avec nos autres intégrations, stack est renommé en backtrace.
Ajoute des tags au Span actuel. Les tags actuels seront fusionnés avec l’objet tags passé en paramètre.
span.setParams(params: object)
Ajoute des params au Span actuel. Les params actuels seront fusionnés avec l’objet params passé en paramètre.
Si vous utilisez une version antérieure à 1.3.28, l’objet params ne doit pas
contenir d’objets imbriqués.
span.serialize()
Renvoie le contenu d’un Span sous forme d’objet.
Envoyer un Span à AppSignal
Lorsque vous avez terminé d’ajouter des données au Span, il peut alors être passé à appsignal.send() pour être envoyé à notre API.
const span = appsignal.createSpan((span) => {
return span.setError(new Error("test error"));
});
appsignal.send(span);
send() est différente de la méthode sendError() car elle permet à un Span d’être passé en paramètre, qui est soit envoyé immédiatement à l’API, soit, en cas d’erreur réseau, ajouté à la file d’attente pour être réessayé ultérieurement.
Une fois que le Span est passé à appsignal.send(), tous les Hooks sont appliqués au Span dans l’ordre suivant :
- Décorateurs
- Arguments optionnels
tags ou namespace de appsignal.send()
- Surcharges
À propos de la file d’attente de relance
Si, pour une raison quelconque, l’envoi d’une erreur à l’API échoue (par exemple, si la connexion réseau ne fonctionne pas), l’objet Span auquel elle appartient est placé dans la file d’attente de relance. Par défaut, les requêtes sont réessayées 5 fois avec un backoff exponentiel. Si la requête réussit, le Span correspondant est retiré de la file d’attente. Une fois la limite de relances atteinte, tous les Spans restants dans la file d’attente sont supprimés.
Aucune mise en cache n’est actuellement implémentée pour la file d’attente de relance, ce qui signifie que si un
Span se trouve dans la file d’attente lorsque l’utilisateur quitte votre application,
ce Span sera également supprimé.
