Span APIedit

A span measures the duration of a single event.

To get a Span object, you need to call apm.buildSpan().

To see an example of using custom spans, see the Custom Spans in Node.js article.

span.transactionedit

  • Type: Transaction

A reference to the parent transaction object.

All spans belongs to a transaction.

span.nameedit

  • Type: String
  • Default: unnamed

The name of the span. This can also be set via span.start().

span.typeedit

  • Type: String
  • Default: custom

The type of span. This can also be set via span.start().

The type is a hierarchical string used to group similar spans together. For instance, all spans of MySQL queries are given the type db.mysql.query.

In the above example db is considered the type prefix. Though there are no naming restrictions for this prefix, the following are standardized across all Elastic APM agents: app, db, cache, template, and ext.

span.start()edit

span.start([name][, type])

Start a span.

Arguments:

  • name - The name of the span (string). You can alternatively set this via span.name. Defaults to unnamed
  • type - The type of span (string). You can alternatively set this via span.type. Defaults to custom.code

When a span is started it will measure the time until span.end() or span.truncate() is called.

span.end()edit

span.end()

End the span. If the span has already ended, nothing happens.

A span that isn’t ended before the parent transaction ends will be truncated.

span.truncate()edit

span.truncate()

Truncates and ends the span. If the span is already ended or truncated, nothing happens.

A truncated span is a special type of ended span. It’s used to indicate that the measured event took longer than the duration recorded by the span.