Package co.elastic.apm.api

Class ElasticApm

java.lang.Object
co.elastic.apm.api.ElasticApm
public class ElasticApm extends 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 Details

    • 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 Throwable e)
      Deprecated.
      use currentSpan().captureException(Throwable) instead
      Captures an exception and reports it to the APM server.
      Parameters:
      e - the exception to record

    • setServiceInfoForClassLoader

      public static void setServiceInfoForClassLoader(@Nullable ClassLoader classLoader, @Nullable String serviceName, @Nullable String serviceVersion)
      Associates a class loader with a service name and version.

      The association is used to overwrite the autodetected service name and version when a transaction is started.

      NOTE: If the class loader already is associated with a service name and version, the existing information will not be overwritten.

      Parameters:
      classLoader - the class loader which should be associated with the given service name and version
      serviceName - the service name
      serviceVersion - the service version

    • getConfig

      public static <T> T getConfig(String key, Class<T> type)
      Returns the current value of a config option (regardless of however and whenever that option was (re)set)

      This applies to dynamically updated values too, so for example "transaction_sample_rate" can be dynamically reset (eg by executing System.setProperty("elastic.apm.transaction_sample_rate", "0.6") or changing the "transaction_sample_rate" in the property file or from fleet UI) and calling getConfig("transaction_sample_rate") would provide the current value

      If an invalid key is passed as the first argument, or if the incorrect type for the key is passed as the second argument, the method will throw an IllegalArgumentException

      Note the value returned can be null if the "public-api" set of instrumentations has not been applied and also if the agent hasn't finished initializing

      Parameters:
      key - the string option
      type - the type of the option (String, Long, Integer, etc)
      Returns:
      The current value for the option, per the option type (String, Long, Integer, etc)
      Since:
      1.37.0

    • setConfig

      public static void setConfig(String key, String value)
      Convenience method that just calls System.setProperty("elastic.apm."+key, value);

      Note there is a delay between executing the update and it taking effect. The corresponding getConfig(String, Class) ()} will only report the new value after it has taken effect. Note also that only dynamic options can be updated, other updates will simply be ignored.

      Parameters:
      key - the string option
      value - the value for that option. No validation is applied here, so invalid values for an option will be ignored by the configuration system
      Since:
      1.37.0