Span API

edit

A span measures the duration of a single event.

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

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

span.transaction

edit
  • Type: Transaction

A reference to the parent transaction object.

All spans belong to a transaction.

span.name

edit
  • Type: String
  • Default: unnamed

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

span.type

edit
  • Type: String
  • Default: custom

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

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

Deprecated in 1.1.0.

Span started automatically by apm.startSpan([name][, type])

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.