Trace APIedit

A trace measures the duration of a single event.

To get a Trace object, you need to call apm.buildTrace().

To see an example of using custom traces, see the Custom Traces in Node.js article.

trace.transactionedit

  • Type: Transaction

A reference to the parent transaction object.

All traces belongs to a transaction.

trace.nameedit

  • Type: String
  • Default: unnamed

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

trace.typeedit

  • Type: String
  • Default: custom

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

The type is a hierarchical string used to group similar traces together. For instance, all traces 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.

trace.start()edit

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

Start a trace.

Arguments:

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

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

trace.end()edit

trace.end()

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

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

trace.truncate()edit

trace.truncate()

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

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