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

Transaction API

edit

Transaction API

edit

A transaction groups multiple spans in a logical group.

To get a Transaction object, you need to call apm.startTransaction().

To see an example of using custom transactions, see the Custom Transactions in Node.js article.

transaction.name

edit

Added in: v0.1.0

The name of the transaction.

Can be used to set or overwrite the name of the transaction (visible in the performance monitoring breakdown). If you don’t have access to the current transaction, you can also set the name using apm.setTransactionName().

Transactions with the same name and type are grouped together.

transaction.type

edit

Added in: v0.1.0

The type of the transaction.

There’s a special type called request which is used by the agent for the transactions automatically created when an incoming HTTP request is detected.

transaction.traceparent

edit

Added in: v2.9.0

Get the serialized traceparent string of the transaction.

transaction.result

edit

Added in: v0.1.0

A string describing the result of the transaction. This is typically the HTTP status code, or e.g. "success" or "failure" for a background task.

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

edit

Added in: v2.0.0

  • name <string> The name of the span. You can alternatively set this via span.name. Default: unnamed
  • type <string> The type of span. You can alternatively set this via span.type. Default: custom

  • options - The following options are supported:

    • startTime <number> The time when the span started. 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

Start and return a new custom span associated with this transaction. When a span is started it will measure the time until span.end() is called.

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

transaction.setTag(name, value)

edit

Deprecated in 2.10.0.

Replaced by transaction.setLabel(name, value)

Added in: v0.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 transaction. You can set multiple tags on the same transaction. If an error happens during the transaction, it will also get tagged with the same tags.

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

transaction.setLabel(name, value)

edit

Added in: v0.1.0

Renamed from transaction.setTag() to transaction.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 transaction. You can set multiple labels on the same transaction. If an error happens during the transaction, it will also get tagged with the same labels.

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

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

edit

Deprecated in 2.10.0.

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

Added in: v1.5.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 transaction. You can add tags multiple times. If an error happens during the transaction, it will also get tagged with the same tags.

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

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

edit

Added in: v1.5.0

Renamed from transaction.addTags() to transaction.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 transaction. You can add labels multiple times. 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()).

transaction.ensureParentId()

edit

Added in: v2.0.0

If the transaction does not already have a parent id, calling this method generates a new parent id, sets it as the parent id of this transaction, and returns it as a <string>.

This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load with the transaction of the backend service. If your backend service generates the HTML page dynamically, initializing the JavaScript RUM agent with the value of this method allows analyzing the time spent in the browser vs in the backend services.

To enable the JavaScript RUM agent, add a snippet similar to this to the body of your HTML page, preferably before other JavaScript libraries:

elasticApm.init({
  serviceName: 'my-frontend-app', // Name of your frontend app
  serverUrl: 'https://example.com:8200', // APM Server host
  pageLoadTraceId: '${transaction.traceId}',
  pageLoadSpanId: '${transaction.ensureParentId()}',
  pageLoadSampled: ${transaction.sampled}
})

See the JavaScript RUM agent documentation for more information.

transaction.ids

edit

Added in: v2.17.0

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

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

transaction.toString()

edit

Added in: v2.17.0

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

"trace.id=abc123 transaction.id=abc123"

transaction.end([result][, endTime])

edit

Added in: v0.1.0

  • result <string> Describes the result of the transaction. This is typically the HTTP status code, or e.g. "success" or "failure" for a background task
  • endTime <number> The time when the transaction 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

Ends the transaction. If the transaction has already ended, nothing happens.

Alternatively you can call apm.endTransaction() to end the active transaction.

« Agent API Span API »