Package co.elastic.apm.api

Class AbstractSpanImpl

java.lang.Object

co.elastic.apm.api.AbstractSpanImpl

All Implemented Interfaces:

Span

public abstract class AbstractSpanImpl
extends java.lang.Object
implements Span

Field Summary

Fields

Modifier and Type	Field	Description
protected java.lang.Object	span

Method Summary

Modifier and Type	Method	Description
Scope	activate()	Makes this span the active span on the current thread until Scope.close() has been called.
void	captureException(java.lang.Throwable throwable)	Captures an exception and reports it to the APM server.
Span	createSpan()	NOTE: THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN VERSION 2.0.
void	end()	Ends the span and schedules it to be reported to the APM Server.
java.lang.String	getId()	Returns the id of this span (never null)
java.lang.String	getTraceId()	Returns the id of this trace (never null)
void	injectTraceHeaders(HeaderInjector headerInjector)	Allows for manual propagation of the tracing headers.
boolean	isSampled()	Returns true if this span is recorded and sent to the APM Server
Span	startSpan()	Start and return a new custom span with no type, as a child of this span.
Span	startSpan(java.lang.String type, java.lang.String subtype, java.lang.String action)	Start and return a new typed custom span as a child of this span.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface co.elastic.apm.api.Span

addTag, setName, setType

Field Detail

span

@Nonnull
protected final java.lang.Object span

Method Detail

createSpan

@Nonnull
public Span createSpan()

Description copied from interface: Span

NOTE: THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN VERSION 2.0. Instead, start a new span through Span.startSpan() or Span.startSpan(String, String, String).

Specified by:

createSpan in interface Span

Returns:

the started span, never null

startSpan

@Nonnull
public Span startSpan(java.lang.String type,
                      @Nullable
                      java.lang.String subtype,
                      @Nullable
                      java.lang.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 give 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

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

captureException

public void captureException(java.lang.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

getId

@Nonnull
public java.lang.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 java.lang.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:

 span.injectTraceHeaders(request::addHeader);
 

Specified by:

injectTraceHeaders in interface Span

Parameters:

headerInjector - tells the agent how to inject a header into the request object