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.activeSpan()).
Span	start() Returns a newly-started Span.
Scope	startActive(boolean finishSpanOnClose) Deprecated. use start() and ScopeManager.activate(Span span) instead. Returns a newly started and activated Scope. SpanBuilder#startActive() is a shorthand for tracer.scopeManager().activate(spanBuilder.start()). The returned Scope supports try-with-resources, but using this method is discouraged as the Span reference could be easily lost, and reporting errors on Span through this method becomes impossible: try (Scope scope = tracer.buildSpan("...").startActive(true)) { // (Do work) scope.span().setTag( ... ); // etc, etc } catch (Exception e) { // Not possible to report errors, as // the span reference has been lost, // and span has been already finished too. } It is recommended to use start() with a subsequent call to ScopeManager.activate(Span) Span span = tracer.buildSpan("...").start(); try (Scope scope = tracer.activateSpan(span)) { } catch (Exception e) { span.log(...); // Report any errors properly. } finally { span.finish(); // Optionally close the Span. }
Span	startManual() Deprecated. use start() instead.
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.
<T> Tracer.SpanBuilder	withTag(Tag<T> tag, T value) Same as AbstractTag#set(Span, T), 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.activeSpan() 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.activeSpan() SpanContext when either startActive(boolean) or start() 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.activeSpan()).

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.

withTag

<T> Tracer.SpanBuilder withTag(Tag<T> tag,
                               T value)

Same as AbstractTag#set(Span, T), 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.

startManual

@Deprecated
Span startManual()

Deprecated. use start() instead.

start

Span start()

Returns a newly-started Span.

If

• the Tracer's ScopeManager.activeSpan() 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.activeSpan()'s SpanContext when either start() or startActive(boolean) is invoked.

Returns:

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

startActive

@Deprecated
Scope startActive(boolean finishSpanOnClose)

Deprecated. use start() and ScopeManager.activate(Span span) instead. Returns a newly started and activated Scope.

SpanBuilder#startActive() is a shorthand for tracer.scopeManager().activate(spanBuilder.start()). The returned Scope supports try-with-resources, but using this method is discouraged as the Span reference could be easily lost, and reporting errors on Span through this method becomes impossible:

     try (Scope scope = tracer.buildSpan("...").startActive(true)) {
         // (Do work)
         scope.span().setTag( ... );  // etc, etc
     } catch (Exception e) {
         // Not possible to report errors, as
         // the span reference has been lost,
         // and span has been already finished too.
     }
 

It is recommended to use start() with a subsequent call to ScopeManager.activate(Span)

     Span span = tracer.buildSpan("...").start();
     try (Scope scope = tracer.activateSpan(span)) {
     } catch (Exception e) {
         span.log(...); // Report any errors properly.
     } finally {
         span.finish(); // Optionally close the Span.
     }
 

Returns:

a Scope, already registered via the ScopeManager

See Also:

ScopeManager, Scope