Package co.elastic.apm.api

Interface Span

All Known Subinterfaces:

Transaction

All Known Implementing Classes:

AbstractSpanImpl

public interface Span

A span contains information about a specific code path, executed as part of a Transaction.

If for example a database query happens within a recorded transaction, a span representing this database query may be created. In such a case the name of the span will contain information about the query itself, and the type will hold information about the database type.

Call ElasticApm.currentSpan() to get a reference of the current span.

Note: Calling any methods after end() has been called is illegal. You may only interact with spans when you have control over its lifecycle. For example, if a span is ended on another thread you must not add tags if there is a chance for a race between the end() and the addTag(String, String) method.

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.
Span	addTag(java.lang.String key, java.lang.String value)	A flat mapping of user-defined tags with string values.
void	captureException(java.lang.Throwable throwable)	Captures an exception and reports it to the APM server.
Span	createSpan()	Deprecated.
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	setName(java.lang.String name)	The name of the span.
Span	setType(java.lang.String type)	Deprecated.
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.

Method Detail

setName

@Nonnull
Span setName(java.lang.String name)

The name of the span.

Parameters:

name - the name of the span

setType

@Nonnull
@Deprecated
Span setType(java.lang.String type)

Deprecated.

NOTE: THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN VERSION 2.0. Instead, setting the span type can be done when starting a new span through startSpan(String, String, String).

Parameters:

type - the type of the span

addTag

@Nonnull
Span addTag(java.lang.String key,
            java.lang.String value)

A flat mapping of user-defined tags with string values.

Note: the tags are indexed in Elasticsearch so that they are searchable and aggregatable. By all means, you should avoid that user specified data, like URL parameters, is used as a tag key as it can lead to mapping explosions.

Parameters:

key - The tag key.

value - The tag value.

createSpan

@Nonnull
@Deprecated
Span createSpan()

Deprecated.

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

Returns:

the started span, never null

startSpan

@Nonnull
Span startSpan(java.lang.String type,
               @Nullable
               java.lang.String subtype,
               @Nullable
               java.lang.String action)

Start and return a new typed custom span as a child of this span.

It is important to call 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 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.

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
Span startSpan()

Start and return a new custom span with no type, as a child of this span.

It is important to call 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 activate() on how to achieve that.

Returns:

the started span, never null

end

void end()

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 startSpan().

captureException

void captureException(java.lang.Throwable throwable)

Captures an exception and reports it to the APM server.

Parameters:

throwable - the exception to report

getId

@Nonnull
java.lang.String getId()

Returns the id of this span (never null)

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

Returns:

the id of this span (never null)

getTraceId

@Nonnull
java.lang.String getTraceId()

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.

Returns:

the id of this span (never null)

activate

Scope activate()

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: activate() and Scope.close() have to be called on the same thread.

Returns:

a scope which has to be Scope.close()d

isSampled

boolean isSampled()

Returns true if this span is recorded and sent to the APM Server

Returns:

true if this span is recorded and sent to the APM Server

injectTraceHeaders

void injectTraceHeaders(HeaderInjector headerInjector)

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

Parameters:

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

Since:

1.3.0