io.opentracing

Interface Tracer.SpanBuilder

Enclosing interface:

Tracer

public static interface Tracer.SpanBuilder

Method Summary

Modifier and Type	Method and Description
Tracer.SpanBuilder	addReference(String referenceType, SpanContext referencedContext) Add a reference from the Span being built to a distinct (usually parent) Span.
Tracer.SpanBuilder	asChildOf(Span parent) A shorthand for addReference(References.CHILD_OF, parent.context()).
Tracer.SpanBuilder	asChildOf(SpanContext parent) A shorthand for addReference(References.CHILD_OF, parent).
Tracer.SpanBuilder	ignoreActiveSpan() Do not create an implicit References.CHILD_OF reference to the ScopeManager.active()).
Span	start() Deprecated. use startManual() or startActive() instead.
Scope	startActive() Returns a newly started and activated Scope.
Scope	startActive(boolean finishSpanOnClose) Returns a newly started and activated Scope.
Span	startManual() Like startActive(), but the returned Span has not been registered via the ScopeManager.
Tracer.SpanBuilder	withStartTimestamp(long microseconds) Specify a timestamp of when the Span was started, represented in microseconds since epoch.
Tracer.SpanBuilder	withTag(String key, boolean value) Same as Span.setTag(String, boolean), but for the span being built.
Tracer.SpanBuilder	withTag(String key, Number value) Same as Span.setTag(String, Number), but for the span being built.
Tracer.SpanBuilder	withTag(String key, String value) Same as Span.setTag(String, String), but for the span being built.

Method Detail

asChildOf

Tracer.SpanBuilder asChildOf(SpanContext parent)

A shorthand for addReference(References.CHILD_OF, parent).

If parent==null, this is a noop.

asChildOf

Tracer.SpanBuilder asChildOf(Span parent)

A shorthand for addReference(References.CHILD_OF, parent.context()).

If parent==null, this is a noop.

addReference

Tracer.SpanBuilder addReference(String referenceType,
                                SpanContext referencedContext)

Add a reference from the Span being built to a distinct (usually parent) Span. May be called multiple times to represent multiple such References.

If

• the Tracer's ScopeManager.active() is not null, and
• no explicit references are added via addReference(java.lang.String, io.opentracing.SpanContext), and
• ignoreActiveSpan() is not invoked,

... then an inferred References.CHILD_OF reference is created to the ScopeManager.active() SpanContext when either startActive() or startManual() is invoked.

Parameters:

referenceType - the reference type, typically one of the constants defined in References

referencedContext - the SpanContext being referenced; e.g., for a References.CHILD_OF referenceType, the referencedContext is the parent. If referencedContext==null, the call to addReference(java.lang.String, io.opentracing.SpanContext) is a noop.

See Also:

References

ignoreActiveSpan

Tracer.SpanBuilder ignoreActiveSpan()

Do not create an implicit References.CHILD_OF reference to the ScopeManager.active()).

withTag

Tracer.SpanBuilder withTag(String key,
                           String value)

Same as Span.setTag(String, String), but for the span being built.

withTag

Tracer.SpanBuilder withTag(String key,
                           boolean value)

Same as Span.setTag(String, boolean), but for the span being built.

withTag

Tracer.SpanBuilder withTag(String key,
                           Number value)

Same as Span.setTag(String, Number), but for the span being built.

withStartTimestamp

Tracer.SpanBuilder withStartTimestamp(long microseconds)

Specify a timestamp of when the Span was started, represented in microseconds since epoch.

startActive

Scope startActive()

Returns a newly started and activated Scope.

The returned Scope supports try-with-resources. For example:

     try (Scope scope = tracer.buildSpan("...").startActive()) {
         // (Do work)
         scope.span().setTag( ... );  // etc, etc
     }
     // Span finishes automatically when the Scope is closed,
     // following the default behavior of ScopeManager.activate(Span)
 

For detailed information, see startActive(boolean)

Note: startActive() is a shorthand for tracer.scopeManager().activate(spanBuilder.startManual()).

Returns:

a Scope, already registered via the ScopeManager

See Also:

ScopeManager, Scope, startActive(boolean)

startActive

Scope startActive(boolean finishSpanOnClose)

Returns a newly started and activated Scope.

The returned Scope supports try-with-resources. For example:

     try (Scope scope = tracer.buildSpan("...").startActive(false)) {
         // (Do work)
         scope.span().setTag( ... );  // etc, etc
     }
     // Span does not finish automatically when the Scope is closed as
     // 'finishOnClose' is false
 

If

• the Tracer's ScopeManager.active() is not null, and
• no explicit references are added via addReference(java.lang.String, io.opentracing.SpanContext), and
• ignoreActiveSpan() is not invoked,

... then an inferred References.CHILD_OF reference is created to the ScopeManager.active()'s SpanContext when either startManual() or startActive() is invoked.

Note: startActive(boolean) is a shorthand for tracer.scopeManager().activate(spanBuilder.startManual(), finishSpanOnClose).

Parameters:

finishSpanOnClose - whether span should automatically be finished when Scope.close() is called

Returns:

a Scope, already registered via the ScopeManager

See Also:

ScopeManager, Scope

startManual

Span startManual()

Like startActive(), but the returned Span has not been registered via the ScopeManager.

Returns:

the newly-started Span instance, which has *not* been automatically registered via the ScopeManager

See Also:

startActive()

start

@Deprecated
Span start()

Deprecated. use startManual() or startActive() instead.