Logo of AppSignal

Menu
Documentation navigation

Creating and Using a Span

A Span is the name of the object that we use to capture data about an error and its surrounding context. It is designed to be similar to, but not exactly like, the Span from the OpenTelemetry standard specification.

Creating a new Span

A Span can be created by calling appsignal.createSpan(), which initializes a new Span object with any default options that you passed when the Appsignal object was initialized.

1
const span = appsignal.createSpan()

The createSpan() method can also take a function as a parameter, allowing you to define the Span's data as the same time as it is created.

1
2
3
4
5
const span = appsignal.createSpan((span) => {
  return span.setTags({
    tag: "value"
  })
})

Spans cannot be nested, nor can multiple Spans be passed to appsignal.send() at once. We recommend using Promise.all for concurrent send operations.

1
2
3
4
5
6
7
const span1 = appsignal.createSpan()
const span2 = appsignal.createSpan()

Promise.all([
  appsignal.send(span1),
  appsignal.send(span2)
])

Updating a Span

After a Span is created, you can begin adding data to it using methods on the Span object:

1
2
3
4
const span = appsignal.createSpan()
span.setTags({ tag: "value" })

console.log(span.serialize().tags) // { tag: "value" }

Each method that modifies the Span returns this, allowing you to chain methods together:

1
2
3
4
5
6
7
8
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)

Sets the action of the current Span. The action must never be an empty string - it can be either undefined or a non-empty string. An action name is used to identify the location of a certain sample error and performance issues.

span.setNamespace(name: string)

Sets the namespace of the current Span. Namespaces are a way to group error incidents, performance incidents, and host metrics in your app.

span.setError(error: Error | object)

Sets the error of the current Span. When an Error object is passed to the setError method, the stack property is normalised and transformed into an array of strings, with each string representing a line in the stacktrace. For consistency with our other integrations, stack is renamed to backtrace.

span.setTags(tags: object)

Adds tags to the current Span. The current tags will be merged with the tags object passed as a parameter.

span.setParams(params: object)

Adds params to the current Span. The current params will be merged with the params object passed as a parameter. The params object must not contain any nested objects.

span.serialize()

Returns the contents of a Span as an object.

Sending a Span to AppSignal

When you're finished adding data to the Span, it can then be passed to appsignal.send() to be pushed to our API.

1
2
3
4
5
const span = appsignal.createSpan((span) => {
  return span.setError(new Error("test error"))
})

appsignal.send(span)

The send() method is different to the sendError() method as it allows a Span to be passed as a parameter, which is either pushed immediately to the API, or in the case of a network error, added to the queue to be retried later.

Once the Span is passed to appsignal.send(), any Hooks are applied to the Span in the following order:

  • Decorators
  • Optional tags or namespace arguments to appsignal.send()
  • Overrides

We'd like to set cookies, read why.