Package co.elastic.apm.api

Class ElasticApm

  • public class ElasticApm
extends java.lang.Object
    This class is the main entry point of the public API for the Elastic APM agent.

    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");

    • Method Detail

      • startTransaction

        @Nonnull
public static Transaction startTransaction()
        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 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.

        Returns:
        the started transaction.

      • startTransactionWithRemoteParent

        @Nonnull
public static Transaction startTransactionWithRemoteParent​(HeaderExtractor headerExtractor)
        Similar to startTransaction() but creates this transaction as the child of a remote parent.

        Example: 

         // Hook into a callback provided by the framework that is called on incoming requests
 public Response onIncomingRequest(Request request) throws Exception {
     // creates a transaction representing the server-side handling of the request
     Transaction transaction = ElasticApm.startTransactionWithRemoteParent(key -> request.getHeader(key));
     try (final Scope scope = transaction.activate()) {
         String name = "a useful name like ClassName#methodName where the request is handled";
         transaction.setName(name);
         transaction.setType(Transaction.TYPE_REQUEST);
         return request.handle();
     } catch (Exception e) {
         transaction.captureException(e);
         throw e;
     } finally {
         transaction.end();
     }
 }

        Note: If the protocol supports multi-value headers, use startTransactionWithRemoteParent(HeaderExtractor, HeadersExtractor)

        Parameters:
        headerExtractor - a function which receives a header name and returns the fist header with that name
        Returns:
        the started transaction
        Since:
        1.3.0

      • startTransactionWithRemoteParent

        @Nonnull
public static Transaction startTransactionWithRemoteParent​(HeaderExtractor headerExtractor,
                                                           HeadersExtractor headersExtractor)
        Similar to startTransaction() but creates this transaction as the child of a remote parent.

        Example: 

         // Hook into a callback provided by the framework that is called on incoming requests
 public Response onIncomingRequest(Request request) throws Exception {
     // creates a transaction representing the server-side handling of the request
     Transaction transaction = ElasticApm.startTransactionWithRemoteParent(request::getHeader, request::getHeaders);
     try (final Scope scope = transaction.activate()) {
         String name = "a useful name like ClassName#methodName where the request is handled";
         transaction.setName(name);
         transaction.setType(Transaction.TYPE_REQUEST);
         return request.handle();
     } catch (Exception e) {
         transaction.captureException(e);
         throw e;
     } finally {
         transaction.end();
     }
 }

        Note: If the protocol does not support multi-value headers, use startTransactionWithRemoteParent(HeaderExtractor)

        Parameters:
        headerExtractor - a function which receives a header name and returns the fist header with that name
        headersExtractor - a function which receives a header name and returns all headers with that name
        Returns:
        the started transaction
        Since:
        1.3.0

      • currentTransaction

        @Nonnull
public static Transaction currentTransaction()
        Returns the currently running 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.

        NOTE: Transactions created via startTransaction() can not be retrieved by calling this method. See Transaction.activate() on how to achieve that.

        Returns:
        The currently running transaction, or a noop transaction (never null).

      • currentSpan

        @Nonnull
public static Span currentSpan()
        Returns the currently active span or transaction.

        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.

        Returns:
        The currently active span, or transaction, or a noop span (never null).

      • captureException

        @Deprecated
public static void captureException​(@Nullable
                                    java.lang.Throwable e)
        Deprecated.
        use currentSpan().captureException(Throwable) instead
        Captures an exception and reports it to the APM server.
        Parameters:
        e - the exception to record