public class ElasticApm
extends java.lang.Object
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 this class.
Use this API to set a custom transaction name, for example:
ElasticApm.currentTransaction().setName("SuchController#muchMethod");
Modifier and Type | Method | Description |
---|---|---|
static void |
captureException(java.lang.Throwable e) |
Deprecated.
use
currentSpan() .captureException(Throwable) instead |
static Span |
currentSpan() |
Returns the currently active span or transaction.
|
static Transaction |
currentTransaction() |
Returns the currently running transaction.
|
static Transaction |
startTransaction() |
Use this method to create a custom transaction.
|
static Transaction |
startTransactionWithRemoteParent(HeaderExtractor headerExtractor) |
Similar to
startTransaction() but creates this transaction as the child of a remote parent. |
static Transaction |
startTransactionWithRemoteParent(HeaderExtractor headerExtractor,
HeadersExtractor headersExtractor) |
Similar to
startTransaction() but creates this transaction as the child of a remote parent. |
@Nonnull public static Transaction startTransaction()
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 Transaction.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(); }
Note: Transactions created via this method can not be retrieved by calling currentSpan()
or currentTransaction()
.
See Transaction.activate()
on how to achieve that.
@Nonnull public static Transaction startTransactionWithRemoteParent(HeaderExtractor headerExtractor)
startTransaction()
but creates this transaction as the child of a remote parent.
Example:
Transaction transaction = ElasticApm.startTransactionWithRemoteParent(request::getHeader);
Note: If the protocol supports multi-value headers, use startTransactionWithRemoteParent(HeaderExtractor, HeadersExtractor)
headerExtractor
- a function which receives a header name and returns the fist header with that name@Nonnull public static Transaction startTransactionWithRemoteParent(HeaderExtractor headerExtractor, HeadersExtractor headersExtractor)
startTransaction()
but creates this transaction as the child of a remote parent.
Example:
Transaction transaction = ElasticApm.startTransactionWithRemoteParent(request::getHeader, request::getHeaders);
Note: If the protocol does not support multi-value headers, use startTransactionWithRemoteParent(HeaderExtractor)
headerExtractor
- a function which receives a header name and returns the fist header with that nameheadersExtractor
- a function which receives a header name and returns all headers with that name@Nonnull public static Transaction currentTransaction()
If there is no current transaction, this method will return a noop transaction,
which means that you never have to check for null
values.
NOTE: Transactions created via startTransaction()
can not be retrieved by calling this method.
See Transaction.activate()
on how to achieve that.
null
).@Nonnull public static Span currentSpan()
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.
NOTE: Transactions created via Span.startSpan()
or via Span.startSpan(String, String, String)
can not be retrieved
by calling this method.
See Span.activate()
on how to achieve that.
null
).@Deprecated public static void captureException(@Nullable java.lang.Throwable e)
currentSpan()
.captureException(Throwable)
insteade
- the exception to recordCopyright © 2018–2019 Elastic Inc.. All rights reserved.