Span API
editSpan
API
editA 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
editAdded in: v0.1.0
- Type: Transaction
A reference to the parent transaction object.
All spans belong to a transaction.
span.name
editAdded in: v0.1.0
-
<string>
Default:unnamed
The name of the span.
This can also be set via apm.startSpan()
.
span.type
editAdded in: v0.1.0
Split components into type
, subtype
and action
in: v3.0.0
-
<string>
Default:custom
The type of span.
This can also be set via apm.startSpan()
.
The type is used to group similar spans together.
For instance,
all spans of MySQL queries are given the type db
,
with a subtype of mysql
and an action of query
.
In the above example, db
is considered the type.
Though there are no naming restrictions for the type,
the following are standardized across all Elastic APM agents:
app
, db
, cache
, template
, and ext
.
span.subtype
editAdded in: v0.1.0
-
<string>
Default:custom
The subtype of the span.
This can also be set via apm.startSpan()
.
The subtype is typically the name of a module or library.
For example,
MySQL queries have a subtype of mysql
.
span.action
editAdded in: v0.1.0
-
<string>
Default:custom
The action of the span.
This can also be set via apm.startSpan()
.
The action is typically a specific function name or a general description of specific functionality.
For example,
a database query would generally have an action of query
.
span.setLabel(name, value[, stringify = true])
editAdded in: v2.1.0
Renamed from span.setTag()
to span.setLabel()
: v2.10.0
Added stringify
argument in: v3.11.0
-
name
<string>
Any periods (.
), asterisks (*
), or double quotation marks ("
) will be replaced by underscores (_
), as those characters have special meaning in Elasticsearch -
value
<string>
|<number>
|<boolean>
-
stringify
<boolean>
Defaults totrue
. When true, if a non-stringvalue
is given, it is 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.addLabels({ [name]: value }[, stringify = true])
editAdded in: v2.1.0
Renamed from span.addTags()
to span.addLabels()
: v2.10.0
Added stringify
argument in: v3.11.0
Add several labels on the span. You can add labels multiple times.
span.ids
editAdded 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()
[v3.23.0]
Deprecated in v3.23.0.
editAdded in: v2.17.0
Deprecated in: v3.23.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"
Relying on the format of span.toString()
has been deprecated and may
change in v4 of the agent. Prefer the use of span.ids
or
apm.currentTraceIds
. The v3 format may be reproduced
via:
const { stringify } = require('querystring') console.log( stringify(span.ids, ' ', '=')) )
span.end([endTime])
editAdded 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.
span.outcome
editAdded in: v3.12.0
The Node.js agent automatically sets an outcome
property on spans. This property will be one of three values:
-
success
: Indicates the span’s operation was a success. -
failure
: Indicates the span’s operation was not a success. -
unknown
: Indicates the agent was unable to determine whether the span’s operation was a success or not. Anunknown
outcome removes a transaction from error rate considerations.
What constitutes a success or failure will depend on the span type.
For the general case, a span’s outcome is considered a failure if the Node.js agent captures an error during the execution of the work a span represents.
However, for exit spans that represent an HTTP request, the outcome
is based on the status code of the HTTP response. A status code less than 400
is considered a success. A status code greater or equal to 400
is considered a failure.
span.setOutcome(outcome)
editAdded in: v3.12.0
-
outcome
<string>
The setOutcome
method allows an end user to override the Node.js agent’s default setting of a span’s outcome
property. The setOutcome
method accepts a string of either success
, failure
, or unknown
, and will force the agent to report this value for a specific span.
span.setServiceTarget(type, name)
editAdded in: v3.39.0
Manually set the service.target.type
and service.target.name
fields that identify a downstream service. They are used for Service Maps and Dependencies in the Kibana APM app. The values are only used for "exit" spans — spans representing outgoing communication, marked with exitSpan: true
at span creation.
If false-y values (e.g. null
) are given for both type
and name
, then service.target
will explicitly be excluded from this span. This may impact Service Maps and other Kibana APM app reporting for this service.
If this method is not called, the service target values are inferred from other span fields (spec).
service.target.*
fields are ignored for APM Server before v8.3.