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.
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.
const span = appsignal.createSpan();
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.
const span = appsignal.createSpan((span) => {
return span.setTags({
tag: "value",
});
});
Spans não podem ser aninhados, nem múltiplos Spans podem ser passados para appsignal.send() de uma só vez. Recomendamos usar Promise.all para operações send concorrentes.
const span1 = appsignal.createSpan();
const span2 = appsignal.createSpan();
Promise.all([appsignal.send(span1), appsignal.send(span2)]);
Atualizando um Span
Depois que um Span é criado, você pode começar a adicionar dados a ele usando métodos no objeto Span:
const span = appsignal.createSpan();
span.setTags({ tag: "value" });
console.log(span.serialize().tags); // { tag: "value" }
Span retorna this, permitindo que você encadeie os métodos:
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)
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.
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.
Se você estiver usando uma versão anterior à 1.3.28, o objeto params não deve
conter objetos aninhados.
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.
const span = appsignal.createSpan((span) => {
return span.setError(new Error("test error"));
});
appsignal.send(span);
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 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 Spans restantes na fila são descartados.
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.
