> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Créer et utiliser un Span

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](https://github.com/open-telemetry/opentelemetry-specification).

## 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`.

<CodeGroup>
  ```js JavaScript theme={null}
  const span = appsignal.createSpan();
  ```
</CodeGroup>

La méthode `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éé.

<CodeGroup>
  ```js JavaScript theme={null}
  const span = appsignal.createSpan((span) => {
    return span.setTags({
      tag: "value",
    });
  });
  ```
</CodeGroup>

Les `Span`s ne peuvent pas être imbriqués, et plusieurs `Span`s ne peuvent pas être passés à `appsignal.send()` en même temps. Nous recommandons d'utiliser `Promise.all` pour les opérations `send` concurrentes.

<CodeGroup>
  ```js JavaScript theme={null}
  const span1 = appsignal.createSpan();
  const span2 = appsignal.createSpan();

  Promise.all([appsignal.send(span1), appsignal.send(span2)]);
  ```
</CodeGroup>

## 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` :

<CodeGroup>
  ```js JavaScript theme={null}
  const span = appsignal.createSpan();
  span.setTags({ tag: "value" });

  console.log(span.serialize().tags); // { tag: "value" }
  ```
</CodeGroup>

Chaque méthode qui modifie le `Span` renvoie `this`, vous permettant de chaîner les méthodes ensemble :

<CodeGroup>
  ```js JavaScript theme={null}
  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: [...] }
  ```
</CodeGroup>

### `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`.

### `span.setTags(tags: object)`

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.

<Warning>
  Si vous utilisez une version antérieure à 1.3.28, l'objet `params` ne doit pas
  contenir d'objets imbriqués.
</Warning>

### `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.

<CodeGroup>
  ```js JavaScript theme={null}
  const span = appsignal.createSpan((span) => {
    return span.setError(new Error("test error"));
  });

  appsignal.send(span);
  ```
</CodeGroup>

La méthode `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](/front-end/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 `Span`s restants dans la file d'attente sont supprimés.

<Warning>
  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é.
</Warning>