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

# Criando e usando um Span

`Span` é o nome do objeto que usamos para capturar dados sobre um erro e seu contexto ao redor. Ele foi projetado para ser semelhante, mas não exatamente igual, ao Span da especificação padrão [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification).

## Criando um novo `Span`

Um `Span` pode ser criado chamando `appsignal.createSpan()`, que inicializa um novo objeto `Span` com quaisquer opções padrão passadas quando o objeto `Appsignal` foi inicializado.

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

O método `createSpan()` também pode receber uma função como parâmetro, permitindo que você defina os dados do `Span` ao mesmo tempo em que ele é criado.

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

`Span`s não podem ser aninhados, nem múltiplos `Span`s podem ser passados para `appsignal.send()` de uma só vez. Recomendamos usar `Promise.all` para operações `send` concorrentes.

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

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

## Atualizando um `Span`

Depois que um `Span` é criado, você pode começar a adicionar dados a ele usando métodos no objeto `Span`:

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

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

Cada método que modifica o `Span` retorna `this`, permitindo que você encadeie os métodos:

<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)`

Define a `action` do `Span` atual. A `action` nunca deve ser uma string vazia — pode ser `undefined` ou uma string não vazia. O nome de uma action é usado para identificar a localização de um determinado erro de amostra e problemas de performance.

### `span.setNamespace(name: string)`

Define o `namespace` do `Span` atual. Namespaces são uma forma de agrupar incidentes de erro, incidentes de performance e métricas de host na sua aplicação.

### `span.setError(error: Error | object)`

Define o `error` do `Span` atual. O objeto `Error` tem as propriedades `name`, `message` e `backtrace`. Certifique-se de usar somente algo que descreva o tipo do erro como `name`. O AppSignal agrupa os erros com base nesse nome. Você pode colocar o que quiser em `message`.

Quando um objeto `Error` é passado para o método `setError`, a propriedade `stack` é normalizada e transformada em um array de strings, com cada string representando uma linha do stacktrace. Por consistência com nossas outras integrações, `stack` é renomeado para `backtrace`.

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

Adiciona `tags` ao `Span` atual. As `tags` atuais serão mescladas com o objeto `tags` passado como parâmetro.

### `span.setParams(params: object)`

Adiciona `params` ao `Span` atual. Os `params` atuais serão mesclados com o objeto `params` passado como parâmetro.

<Warning>
  Se você estiver usando uma versão anterior à 1.3.28, o objeto `params` não deve
  conter objetos aninhados.
</Warning>

### `span.serialize()`

Retorna o conteúdo de um `Span` como um objeto.

## Enviando um `Span` ao AppSignal

Quando você terminar de adicionar dados ao `Span`, ele pode ser passado para `appsignal.send()` para ser enviado à nossa API.

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

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

O método `send()` é diferente do método `sendError()` pois permite que um `Span` seja passado como parâmetro, sendo enviado imediatamente para a API ou, em caso de erro de rede, adicionado à fila para ser reenviado mais tarde.

Uma vez que o `Span` é passado para `appsignal.send()`, quaisquer [Hooks](/front-end/hooks) são aplicados ao `Span` na seguinte ordem:

* Decorators
* Argumentos opcionais `tags` ou `namespace` para `appsignal.send()`
* Overrides

### Sobre a fila de reenvio

Se, por qualquer motivo, o envio de um erro para a API falhar (por exemplo, se a conexão de rede não estiver funcionando), o objeto `Span` ao qual ele pertence é colocado na fila de reenvio. Por padrão, as requisições são reenviadas **5 vezes** com backoff exponencial. Se a requisição for bem-sucedida, o `Span` correspondente é removido da fila. Quando o limite de reenvios for atingido, quaisquer `Span`s restantes na fila são descartados.

<Warning>
  Atualmente, nenhum cache é implementado para a fila de reenvio, o que significa que se um
  `Span` estiver na fila quando o usuário sair da sua aplicação,
  esse `Span` também será descartado.
</Warning>