Public API

The public API of the Elastic APM Java agent lets you customize and manually create spans and transactions, as well as track errors.

The first step in getting started with the API is to declare a dependency to the API:

pom.xml.

<dependency>
    <groupId>co.elastic.apm</groupId>
    <artifactId>apm-agent-api</artifactId>
    <version>${elastic-apm.version}</version>
</dependency>

build.gradle.

compile "co.elastic.apm:apm-agent-api:$elasticApmVersion"

Replace the version placeholders with the latest version from maven central:

The tracer gives you access to the currently active transaction and span. It can also be used to track an exception.

To use the API, you can just invoke the static methods on the class co.elastic.apm.api.ElasticApm.

Returns the currently active transaction. See Transaction API on how to customize the current transaction.

If there is no current transaction, this method will return a noop transaction, which means that you never have to check for null values.

import co.elastic.apm.api.ElasticApm;
import co.elastic.apm.api.Transaction;

Transaction transaction = ElasticApm.currentTransaction();

Returns the currently active span or transaction. See Span API on how to customize the current span.

If there is no current span, this method will return a noop span, which means that you never have to check for null values.

Note that even if this method is returning a noop span, you can still capture exceptions on it. These exceptions will not have a link to a Span or a Transaction.

import co.elastic.apm.api.ElasticApm;
import co.elastic.apm.api.Span;

Span span = ElasticApm.currentSpan();

Use this method to create a custom transaction.

Note that the agent will do this for you automatically when ever your application receives an incoming HTTP request. You only need to use this method to create custom transactions.

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

Transaction transaction = ElasticApm.startTransaction();
try {
    transaction.setName("MyController#myAction");
    transaction.setType(Transaction.TYPE_REQUEST);
    // do your thing...
} catch (Exception e) {
    transaction.captureException(e);
    throw e;
} finally {
    transaction.end();
}

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. A transaction is the first Span of a service, and is also known under the term entry span.

See Transaction currentTransaction() on how to get a reference of the current transaction.

Transaction is a sub-type of Span. So it has all the methods a Span offers plus additional ones.

Override the name of the current transaction. For supported frameworks, the transaction name is determined automatically, and can be overridden using this method.

Example:

transaction.setName("My Transaction");

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

Example:

transaction.setType(Transaction.TYPE_REQUEST);

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.

transaction.setTag("foo", "bar");

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.

transaction.setUser(user.getId(), user.getEmail(), user.getUsername());

Captures an exception and reports it to the APM server.

Returns the id of this transaction (never null)

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

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

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

Span span = parent.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();
}

End tracking the transaction. Should be called e.g. at the end of a request or when ending a background task. Example:

transaction.end();

A span contains information about a specific code path, executed as part of a transaction.

If for example a database query happens within a recorded transaction, a span representing this database query may be created. In such a case the name of the span will contain information about the query itself, and the type will hold information about the database type.

See Span currentSpan() on how to get a reference of the current span.

Override the name of the current span.

Example:

span.setName("SELECT FROM customer");

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

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.

span.setTag("foo", "bar");

Captures an exception and reports it to the APM server.

Returns the id of this span (never null)

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

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

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

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

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