io.opentracing

Interface ScopeManager

public interface ScopeManager

The ScopeManager interface abstracts both the activation of Span instances via activate(Span, boolean) and access to an active Span/Scope via active().

See Also:

Scope, Tracer.scopeManager()

Method Summary

Modifier and Type	Method and Description
Scope	activate(Span span) Set the specified Span as the active instance for the current context (usually a thread).
Scope	activate(Span span, boolean finishSpanOnClose) Deprecated. use activate(Span) instead. Set the specified Span as the active instance for the current context (usually a thread). Finishing the Span upon Scope.close() is discouraged, as reporting errors becomes impossible: try (Scope scope = tracer.scopeManager().activate(span, true)) { } catch (Exception e) { // Not possible to report errors, as // the span has been already finished. }
Scope	active() Return the currently active Scope which can be used to deactivate the currently active Span.
Span	activeSpan() Return the currently active Span.

Method Detail

activate

Scope activate(Span span)

Set the specified Span as the active instance for the current context (usually a thread).

The returned Scope represents the active state for the span. Once its active period is due, Scope.close() ought to be called. To ease this operation, Scope supports try-with-resources. Observe the span will not be automatically finished when Scope.close() is called.

This Scope instance can be accessed at any time through active(), in case it is not possible for the user to store it (when used through middleware or start/finish event hooks, for example). The corresponding Span can be accessed through activeSpan() likewise.

Usage:

     Span span = tracer.buildSpan("...").start();
     try (Scope scope = tracer.scopeManager().activate(span)) {
         span.setTag("...", "...");
         ...
     } catch (Exception e) {
         span.log(...);
     } finally {
         // Optionally finish the Span if the operation it represents
         // is logically completed at this point.
         span.finish();
     }
 

Parameters:

span - the Span that should become the activeSpan()

Returns:

a Scope instance to control the end of the active period for the Span. It is a programming error to neglect to call Scope.close() on the returned instance.

active

Scope active()

Return the currently active Scope which can be used to deactivate the currently active Span.

Observe that Scope is expected to be used only in the same thread where it was created, and thus should not be passed across threads.

Because both active() and activeSpan() reference the current active state, they both will be either null or non-null.

Returns:

the active scope, or null if none could be found.

activeSpan

Span activeSpan()

Return the currently active Span.

Because both active() and activeSpan() reference the current active state, they both will be either null or non-null.

Returns:

the active span, or null if none could be found.

activate

@Deprecated
Scope activate(Span span,
                           boolean finishSpanOnClose)

Deprecated. use activate(Span) instead. Set the specified Span as the active instance for the current context (usually a thread).

Finishing the Span upon Scope.close() is discouraged, as reporting errors becomes impossible:

     try (Scope scope = tracer.scopeManager().activate(span, true)) {
     } catch (Exception e) {
         // Not possible to report errors, as
         // the span has been already finished.
     }
 

Parameters:

span - the Span that should become the activeSpan()

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

Returns:

a Scope instance to control the end of the active period for the Span. It is a programming error to neglect to call Scope.close() on the returned instance.