Span APIedit

A span measures the duration of a single event. When a span is created it will measure the time until span.end() is called.

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

  • Type: Transaction

A reference to the parent transaction object.

All spans belong to a transaction.

span.nameedit

  • Type: String
  • Default: unnamed

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

span.typeedit

  • 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.setTag()edit

span.setTag(name, value)

Set a tag on the span. You can set multiple tags on the same span.

Arguments:

  • name - Any string. Periods (.), asterisks (*), and double quotation marks (") will be replaced by underscores (_), as those characters have special meaning in Elasticsearch
  • value - Any string. If a non-string data type is given, it’s converted to a string before being sent to the APM Server

span.addTags()edit

apm.addTags({ [name]: value })

Add several tags on the span. You can add tags multiple times.

Arguments:

  • tags - An object containing key/value pairs each representing tag name and tag value:

    • name - Any string. Any periods (.), asterisks (*), or double quotation marks (") will be replaced by underscores (_), as those characters have special meaning in Elasticsearch
    • value - Any string. If a non-string data type is given, it’s converted to a string before being sent to the APM Server

span.end()edit

span.end([endTime])

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

Arguments:

  • endTime - The time when the span ended. Must be a Unix Time Stamp representing the number of milliseconds since January 1, 1970, 00:00:00 UTC. Sub-millisecond precision can be achieved using decimals. If not provided, the current time will be used