The timestamp of the transaction. If the transaction timestamp is not provided (the default behaviour), it will be set by the apm-server (v6.3+). You can, however, set the timestamp on the client (using new Date().toISOString()), but you should be aware that the timestamp will reflect the client’s local time which might not always be accurate.

`transaction.startSpan([name][, type][, options])`

edit

const span = transaction.startSpan('My custom span')

Start and return a new custom span associated with this transaction.

Arguments:

name - The name of the span (string). Defaults to unnamed
type - The type of span (string). Defaults to custom
options - The following options are supported:
- blocking - Blocks the associated transaction from ending until this span is ended. Blocked spans automatically create an internal task. Defaults to false.
- parentId - Parent id associated with the new span. Defaults to current transaction id
- sync - Denotes if the span is synchronous or asynchronous.

When a span is started it will measure the time until span.end() is called. Blocked spans allow users to control the early closing of managed transactions in some cases.

See also the Span API docs for details on how to use custom spans.

`transaction.block(flag)`

edit

transaction.block(true)

Blocks the currently running auto-instrumented or custom transactions from getting automatically closed once the associated spans are ended.

Arguments:

flag - Boolean. Defaults to false.

Most of the time, users shouldn’t need to block the running transaction as the agent tries to account for all of the async network activity and capture the required information. The block API is useful when you think auto instrumented code misses important activity and prematurely ends a transaction. An example of this might be a page that contains lots of asynchronous tasks that cannot be automatically instrumented, like web workers.

// get the current active autoinstrumented transaction (page-load, route-change, etc.)
const activeTransaction = apm.getCurrentTransaction()

if (activeTransaction) {
  activeTransaction.block(true)
}

// Perform some more async tasks and unblock it
activeTransaction.block(false)

One can also achieve a similar action by creating blocked spans. Check the managed transactions guide to learn more.

`transaction.addLabels()`

edit

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

Add several labels on the transaction. If an error happens during the transaction, it will also get tagged with the same labels.

Labels are key/value pairs that are indexed by Elasticsearch and therefore searchable (as opposed to data set via apm.setCustomContext()).

Before using custom labels, ensure you understand the different types of metadata that are available.

Arguments:

name - Any string. All periods (.), asterisks (*), and double quotation marks (") will be replaced by underscores (_), as those characters have special meaning in Elasticsearch
value - Any string, boolean, or number. All other data types will be converted to a string before being sent to the APM Server.

Avoid defining too many user-specified tags. Defining too many unique fields in an index is a condition that can lead to a mapping explosion.

`transaction.end()`

edit

transaction.end()

Ends the transaction. Calling transaction.end on an active transaction ends all of the underlying spans and marks them as truncated. If the transaction has already ended, nothing happens.

`transaction.mark(key)`

edit

transaction.mark(key)

Marks the current point in time relative to the start of the transaction. Use this method to mark significant events that happen while the transaction is active.

Arguments:

key - Any string. All periods (.), asterisks (*), and double quotation marks (") will be replaced by underscores (_), as those characters have special meaning in Elasticsearch

« Agent API Span API »