Module co.elastic.apm.api
Package co.elastic.apm.api

Class AbstractSpanImpl

  • All Implemented Interfaces:
    Span
    public abstract class AbstractSpanImpl
extends Object
implements Span

    • Method Detail

      • startSpan

        @Nonnull
public Span startSpan​(String type,
                      @Nullable
                      String subtype,
                      @Nullable
                      String action)
        Description copied from interface: Span
        Start and return a new typed custom span as a child of this span.

        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 = parent.startSpan("db", "mysql", "query");
 try {
     span.setName("SELECT FROM customer");
     // do your thing...
 } catch (Exception e) {
     span.captureException(e);
     throw e;
 } finally {
     span.end();
 }

        NOTE: Spans created via this method can not be retrieved by calling ElasticApm.currentSpan(). See Span.activate() on how to achieve that.

        The type, subtype and action strings are used to group similar spans together, with increasing resolution. For instance, all DB spans are given the type `db`; all spans of MySQL queries are given the subtype `mysql` and all spans describing queries are given the action `query`.

        In the above example `db` is considered the general type. Though there are no naming restrictions for the general types, the following are standardized across all Elastic APM agents: `app`, `db`, `cache`, `template`, and `ext`.

        NOTE: '.' (dot) character is not allowed within type, subtype and action. Any such character will be replaced with a '_' (underscore) character.

        Specified by:
        startSpan in interface Span
        Parameters:
        type - The general type of the new span
        subtype - The subtype of the new span
        action - The action related to the new span
        Returns:
        the started span, never null

      • startSpan

        @Nonnull
public Span startSpan()
        Description copied from interface: Span
        Start and return a new custom span with no type, as a child of this span.

        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 = parent.startSpan();
 try {
     span.setName("SELECT FROM customer");
     // do your thing...
 } catch (Exception e) {
     span.captureException(e);
     throw e;
 } finally {
     span.end();
 }

        NOTE: Spans created via this method can not be retrieved by calling ElasticApm.currentSpan(). See Span.activate() on how to achieve that.

        Specified by:
        startSpan in interface Span
        Returns:
        the started span, never null

      • doSetStartTimestamp

        public void doSetStartTimestamp​(long epochMicros)

      • end

        public void end()
        Description copied from interface: Span
        Ends the span and schedules it to be reported to the APM Server. It is illegal to call any methods on a span instance which has already ended. This also includes this method and Span.startSpan().
        Specified by:
        end in interface Span

      • end

        public void end​(long epochMicros)
        Description copied from interface: Span
        Ends the span and schedules it to be reported to the APM Server. It is illegal to call any methods on a span instance which has already ended. This also includes this method and Span.startSpan().
        Specified by:
        end in interface Span
        Parameters:
        epochMicros - the timestamp of when this event ended, in microseconds (µs) since epoch

      • captureException

        public String captureException​(Throwable throwable)
        Description copied from interface: Span
        Captures an exception and reports it to the APM server.
        Specified by:
        captureException in interface Span
        Parameters:
        throwable - the exception to report
        Returns:
        the id of reported error

      • getId

        @Nonnull
public String getId()
        Description copied from interface: Span
        Returns the id of this span (never null)

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

        Specified by:
        getId in interface Span
        Returns:
        the id of this span (never null)

      • getTraceId

        @Nonnull
public String getTraceId()
        Description copied from interface: Span
        Returns the id of this trace (never null)

        The trace-ID is consistent across all transactions and spans which belong to the same logical trace, even for spans which happened in another service (given this service is also monitored by Elastic APM).

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

        Specified by:
        getTraceId in interface Span
        Returns:
        the id of this span (never null)

      • activate

        public Scope activate()
        Description copied from interface: Span
        Makes this span the active span 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: 

         Span span = parent.startSpan();
 // within the try block the span is available on the current thread via ElasticApm.currentSpan()
 // this is also true for methods called within the try block
 try (final Scope scope = span.activate()) {
     span.setName("SELECT FROM customer");
     span.setType("db.mysql.query");
     // do your thing...
 } catch (Exception e) {
     span.captureException(e);
     throw e;
 } finally {
     span.end();
 }

        Note: Span.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

      • isSampled

        public boolean isSampled()
        Description copied from interface: Span
        Returns true if this span is recorded and sent to the APM Server
        Specified by:
        isSampled in interface Span
        Returns:
        true if this span is recorded and sent to the APM Server

      • injectTraceHeaders

        public void injectTraceHeaders​(HeaderInjector headerInjector)
        Description copied from interface: Span
        Allows for manual propagation of the tracing headers.

        If you want to manually instrument an RPC framework which is not already supported by the auto-instrumentation capabilities of the agent, you can use this method to inject the required tracing headers into the header section of that framework's request object.

        Example: 

         // Hook into a callback provided by the RPC framework that is called on outgoing requests
 public Response onOutgoingRequest(Request request) throws Exception {
     // creates a span representing the external call
     Span span = ElasticApm.currentSpan()
             .startSpan("external", "http", null)
             .setName(request.getMethod() + " " + request.getHost());
     try (final Scope scope = transaction.activate()) {
         span.injectTraceHeaders((name, value) -> request.addHeader(name, value));
         return request.execute();
     } catch (Exception e) {
         span.captureException(e);
         throw e;
     } finally {
         span.end();
     }
 }
        Specified by:
        injectTraceHeaders in interface Span
        Parameters:
        headerInjector - tells the agent how to inject a header into the request object