io.opencensus.contrib.agent.bootstrap

Class TraceTrampoline

java.lang.Object

io.opencensus.contrib.agent.bootstrap.TraceTrampoline

public final class TraceTrampoline
extends Object

TraceTrampoline provides methods for creating and manipulating trace spans from instrumented bytecode.

TraceTrampoline avoids tight coupling with the concrete trace API through the TraceStrategy interface.

Both TraceTrampoline and TraceStrategy are loaded by the bootstrap classloader so that they can be used from classes loaded by the bootstrap classloader. A concrete implementation of TraceStrategy will be loaded by the system classloader. This allows for using the same trace API as the instrumented application.

TraceTrampoline is implemented as a static class to allow for easy and fast use from instrumented bytecode. We cannot use dependency injection for the instrumented bytecode.

Since:

0.9

Method Summary

Modifier and Type	Method and Description
static void	endScope(Closeable scope, Throwable throwable) Ends the current span with a status derived from the given (optional) Throwable, and closes the given scope.
static void	setTraceStrategy(TraceStrategy traceStrategy) Sets the concrete strategy for creating and manipulating trace spans.
static Closeable	startScopedSpan(String spanName) Starts a new span and sets it as the current span.

Methods inherited from class java.lang.Object

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

Method Detail

setTraceStrategy

public static void setTraceStrategy(TraceStrategy traceStrategy)

Sets the concrete strategy for creating and manipulating trace spans.

NB: The agent is responsible for setting the trace strategy once before any other method of this class is called.

Parameters:

traceStrategy - the concrete strategy for creating and manipulating trace spans

Since:

0.9

startScopedSpan

@MustBeClosed
public static Closeable startScopedSpan(String spanName)

Starts a new span and sets it as the current span.

Enters the scope of code where the newly created Span is in the current Context, and returns an object that represents that scope. When the returned object is closed, the scope is exited, the previous Context is restored, and the newly created Span is ended using Span.end(io.opencensus.trace.EndSpanOptions).

Callers must eventually close the returned object to avoid leaking the Context.

Supports the try-with-resource idiom.

NB: The return type of this method is intentionally Closeable and not the more specific Scope because the latter would not be visible from classes loaded by the bootstrap classloader.

Parameters:

spanName - the name of the returned Span

Returns:

an object that defines a scope where the newly created Span will be set to the current Context

Since:

0.9

See Also:

Tracer.spanBuilder(String), SpanBuilder.startScopedSpan()

endScope

public static void endScope(Closeable scope,
                            @Nullable
                            Throwable throwable)

Ends the current span with a status derived from the given (optional) Throwable, and closes the given scope.

Parameters:

scope - an object representing the scope

throwable - an optional Throwable

Since:

0.9