IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Transaction API Metrics »
Elastic Docs › ›API Reference

Span API

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Span API

edit

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

edit

Added in: v0.1.0

  • Type: Transaction

A reference to the parent transaction object.

All spans belong to a transaction.

span.name

edit

Added in: v0.1.0

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

span.type

edit

Added in: v0.1.0

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

edit

Added in: v2.9.0

Get the serialized traceparent string of the span.

span.setTag(name, value)

edit

Deprecated in 2.10.0.

Replaced by span.setLabel(name, value)

Added in: v2.1.0

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

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

span.setLabel(name, value)

edit

Added in: v2.1.0

Renamed from span.setTag() to span.setLabel(): v2.10.0

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

Set a label on the span. You can set multiple labels on the same span.

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

edit

Deprecated in 2.10.0.

Replaced by span.addLabels({ [name]: value })

Added in: v2.1.0

  • tags <Object> Contains key/value pairs:

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

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

span.addLabels({ [name]: value })

edit

Added in: v2.1.0

Renamed from span.addTags() to span.addLabels(): v2.10.0

  • labels <Object> Contains key/value pairs:

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

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

span.ids

edit

Added in: v2.17.0

Produces an object containing span.id and trace.id. This enables log correlation to APM traces with structured loggers.

{
  "trace.id": "abc123",
  "span.id": "abc123"
}

span.toString()

edit

Added in: v2.17.0

Produces a string representation of the span to inject in log messages. This enables log correlation to APM traces with text-only loggers.

"trace.id=abc123 span.id=abc123"

span.end([endTime])

edit

Added in: v0.1.0

  • endTime <number> 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

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

« Transaction API Metrics »