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.
Span	createSpan()	Start and return a new custom span as a child of this transaction.
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)
void	setName(java.lang.String name)	Override the name of the current transaction.
void	setType(java.lang.String type)	The type of the transaction.
void	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

addTag, captureException, getTraceId

Field Detail

TYPE_REQUEST

static final java.lang.String TYPE_REQUEST

See Also:

Constant Field Values

Method Detail

setName

void 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

void 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.

setUser

void 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.

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

Span createSpan()

Start and return a new custom span as a child of this transaction.

It is important to call Span.end() when the span has ended. A best practice is to use the span in a try-catch-finally block. Example:

 Span span = transaction.startSpan();
 try {
     span.setName("SELECT FROM customer");
     span.setType("db.mysql.query");
     // do your thing...
 } catch (Exception e) {
     ElasticApm.captureException(e);
     throw e;
 } finally {
     span.end();
 }
 

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>
   var elasticApm = initApm({
     serviceName: '',
     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