Package co.elastic.apm.api

Interface Transaction

All Superinterfaces:

Span

public interface Transaction
extends Span

A transaction is the data captured by an agent representing an event occurring in a monitored service and groups multiple spans in a logical group.

To get a reference to the current transaction, call ElasticApm.currentTransaction().

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	TYPE_REQUEST

Method Summary

Modifier and Type	Method	Description
Scope	activate()	Makes this transaction the active transaction on the current thread until Scope.close() has been called.
Transaction	addTag(java.lang.String key, java.lang.String value)	A flat mapping of user-defined tags with string values.
Span	createSpan()	Deprecated.
void	end()	End tracking the transaction.
java.lang.String	ensureParentId()	If the transaction does not have a parent-ID yet, calling this method generates a new ID, sets it as the parent-ID of this transaction, and returns it as a `String`.
java.lang.String	getId()	Returns the id of this transaction (never null)
Transaction	setName(java.lang.String name)	Override the name of the current transaction.
Transaction	setResult(java.lang.String result)	A string describing the result of the transaction.
Transaction	setType(java.lang.String type)	The type of the transaction.
Transaction	setUser(java.lang.String id, java.lang.String email, java.lang.String username)	Call this to enrich collected performance data and errors with information about the user/client.

Methods inherited from interface co.elastic.apm.api.Span

captureException, getTraceId, injectTraceHeaders, isSampled, startSpan, startSpan

Field Detail

TYPE_REQUEST

static final java.lang.String TYPE_REQUEST

See Also:

Constant Field Values

Method Detail

setName

@Nonnull
Transaction setName(java.lang.String name)

Override the name of the current transaction.

For supported frameworks, the transaction name is determined automatically, and can be overridden using this function.

Specified by:

setName in interface Span

Parameters:

name - A string describing name of the transaction.

setType

@Nonnull
Transaction setType(java.lang.String type)

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.

Specified by:

setType in interface Span

Parameters:

type - The type of the transaction.

addTag

@Nonnull
Transaction addTag(java.lang.String key,
                   java.lang.String value)

Description copied from interface: Span

A flat mapping of user-defined tags with string values.

Note: the tags are indexed in Elasticsearch so that they are searchable and aggregatable. By all means, you should avoid that user specified data, like URL parameters, is used as a tag key as it can lead to mapping explosions.

Specified by:

addTag in interface Span

Parameters:

key - The tag key.

value - The tag value.

setUser

Transaction setUser(java.lang.String id,
                    java.lang.String email,
                    java.lang.String username)

Call this to enrich collected performance data and errors with information about the user/client.

This method can be called at any point during the request/response life cycle (i.e. while a transaction is active). The given context will be added to the active transaction.

If an error is captured, the context from the active transaction is used as context for the captured error.

Parameters:

id - The user's id or null, if not applicable.

email - The user's email address or null, if not applicable.

username - The user's name or null, if not applicable.

setResult

Transaction setResult(java.lang.String result)

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

Parameters:

result - a string describing the result of the transaction

end

void end()

End tracking the transaction.

Should be called e.g. at the end of a request or when ending a background task.

Specified by:

end in interface Span

createSpan

@Nonnull
@Deprecated
Span createSpan()

Deprecated.

NOTE: THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN VERSION 2.0. Instead, start a new span through Span.startSpan() or Span.startSpan(String, String, String).

Specified by:

createSpan in interface Span

Returns:

the started span, never null

getId

@Nonnull
java.lang.String getId()

Returns the id of this transaction (never null)

If this transaction represents a noop, this method returns an empty string.

Specified by:

getId in interface Span

Returns:

the id of this transaction (never null)

ensureParentId

@Nonnull
java.lang.String ensureParentId()

If the transaction does not have a parent-ID yet, calling this method generates a new 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 when using an HTML templating language like Freemarker, add ElasticApm.currentTransaction() with the key "transaction" to the model.

Also, add a snippet similar to this to the body of your HTML pages, preferably before other JS libraries:

 <script src="elastic-apm-js-base/dist/bundles/elastic-apm-js-base.umd.min.js"></script>
 <script>
   elasticApm.init({
     serviceName: "service-name",
     serverUrl: "http://localhost:8200",
     pageLoadTraceId: "${transaction.traceId}",
     pageLoadSpanId: "${transaction.ensureParentId()}",
     pageLoadSampled: ${transaction.sampled}
   })
 </script>
 

See the JavaScript RUM agent documentation for more information.

Returns:

the parent-ID for this transaction. Updates the transaction to use a new parent-ID if it has previously been unset.

activate

Scope activate()

Makes this transaction the active transaction on the current thread until Scope.close() has been called.

Scopes should only be used in try-with-resource statements in order to make sure the Scope.close() method is called in all circumstances. Failing to close a scope can lead to memory leaks and corrupts the parent-child relationships.

This method should always be used within a try-with-resources statement:

 Transaction transaction = ElasticApm.startTransaction();
 // within the try block the transaction is available on the current thread via ElasticApm.currentTransaction()
 // this is also true for methods called within the try block
 try (final Scope scope = transaction.activate()) {
     transaction.setName("MyController#myAction");
     transaction.setType(Transaction.TYPE_REQUEST);
     // do your thing...
 } catch (Exception e) {
     transaction.captureException(e);
     throw e;
 } finally {
     transaction.end();
 }
 

Note: activate() and Scope.close() have to be called on the same thread.

Specified by:

activate in interface Span

Returns:

a scope which has to be Scope.close()d