Package io.opentelemetry.instrumentation.api.tracer

Class BaseTracer

  • Direct Known Subclasses:
    DatabaseClientTracer, HttpClientTracer, HttpServerTracer, RpcClientTracer, RpcServerTracer
    public abstract class BaseTracer
extends Object
    Base class for all instrumentation specific tracer implementations.

    Tracers should not use Span directly in their public APIs: ideally all lifecycle methods (ex. start/end methods) should return/accept Context. By convention, Context should be passed to all methods as the first parameter.

    The BaseTracer offers several startSpan() utility methods for creating bare spans without any attributes. If you want to provide some additional attributes on span start please consider writing your own specific startSpan() method in your tracer.

    A Context returned by any startSpan() method will always contain a new span. If there is a need to suppress span creation shouldStartSpan(Context, SpanKind) should be called before startSpan().

    When constructing Spans tracers should set all attributes available during construction on a SpanBuilder instead of a Span. This way SpanProcessors are able to see those attributes in the onStart() method and can freely read/modify them.

    • Constructor Summary

      Constructors 
      Constructor Description
      BaseTracer()
      Deprecated.
      always pass an OpenTelemetry instance.
      BaseTracer​(io.opentelemetry.api.OpenTelemetry openTelemetry)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void end​(io.opentelemetry.context.Context context)
      Ends the execution of a span stored in the passed context.
      void end​(io.opentelemetry.context.Context context, long endTimeNanos)
      Ends the execution of a span stored in the passed context.
      void endExceptionally​(io.opentelemetry.context.Context context, Throwable throwable)
      Records the throwable in the span stored in the passed context and marks the end of the span's execution.
      void endExceptionally​(io.opentelemetry.context.Context context, Throwable throwable, long endTimeNanos)
      Records the throwable in the span stored in the passed context and marks the end of the span's execution.
      <C> io.opentelemetry.context.Context extract​(C carrier, io.opentelemetry.context.propagation.TextMapGetter<C> getter)
      Extracts a Context from carrier using the propagator embedded in this tracer.
      <C> void inject​(io.opentelemetry.context.Context context, C carrier, io.opentelemetry.context.propagation.TextMapSetter<C> setter)
      Injects context data into carrier using the propagator embedded in this tracer.
      void onException​(io.opentelemetry.context.Context context, Throwable throwable)
      Records the throwable in the span stored in the passed context and sets the span's status to StatusCode.ERROR.
      boolean shouldStartSpan​(io.opentelemetry.context.Context context, io.opentelemetry.api.trace.SpanKind proposedKind)
      Returns true if a new span of the proposedKind should be suppressed.
      static String spanNameForClass​(Class<?> clazz)
      This method is used to generate an acceptable span (operation) name based on a given class reference.
      static String spanNameForMethod​(Class<?> clazz, @Nullable Method method)
      This method is used to generate an acceptable span (operation) name based on a given method reference.
      static String spanNameForMethod​(Class<?> cl, String methodName)
      This method is used to generate an acceptable span (operation) name based on a given method reference.
      static String spanNameForMethod​(Method method)
      This method is used to generate an acceptable span (operation) name based on a given method reference.
      io.opentelemetry.context.Context startSpan​(io.opentelemetry.context.Context parentContext, String spanName, io.opentelemetry.api.trace.SpanKind kind)
      Returns a Context inheriting from parentContext that contains a new span with name spanName and kind kind.
      io.opentelemetry.context.Context startSpan​(String spanName)
      Returns a Context inheriting from Context.current() that contains a new span with name spanName and kind SpanKind.INTERNAL.
      io.opentelemetry.context.Context startSpan​(String spanName, io.opentelemetry.api.trace.SpanKind kind)
      Returns a Context inheriting from Context.current() that contains a new span with name spanName and kind kind.

    • Constructor Detail

      • BaseTracer

        @Deprecated
public BaseTracer()
        Deprecated.
        always pass an OpenTelemetry instance.
        Instead of using this always pass an OpenTelemetry instance; javaagent tracers should explicitly pass GlobalOpenTelemetry.get() to the constructor.

      • BaseTracer

        public BaseTracer​(io.opentelemetry.api.OpenTelemetry openTelemetry)

    • Method Detail

      • shouldStartSpan

        public final boolean shouldStartSpan​(io.opentelemetry.context.Context context,
                                     io.opentelemetry.api.trace.SpanKind proposedKind)
        Returns true if a new span of the proposedKind should be suppressed.

        If the passed context contains a SpanKind.SERVER span the instrumentation must not create another SERVER span. The same is true for a SpanKind.CLIENT span: if one CLIENT span is already present in the passed context then another one must not be started.

        See Also:
        withClientSpan(Context, Span), withServerSpan(Context, Span)

      • startSpan

        public io.opentelemetry.context.Context startSpan​(String spanName)
        Returns a Context inheriting from Context.current() that contains a new span with name spanName and kind SpanKind.INTERNAL.

      • startSpan

        public io.opentelemetry.context.Context startSpan​(String spanName,
                                                  io.opentelemetry.api.trace.SpanKind kind)
        Returns a Context inheriting from Context.current() that contains a new span with name spanName and kind kind.

      • startSpan

        public io.opentelemetry.context.Context startSpan​(io.opentelemetry.context.Context parentContext,
                                                  String spanName,
                                                  io.opentelemetry.api.trace.SpanKind kind)
        Returns a Context inheriting from parentContext that contains a new span with name spanName and kind kind.

      • spanNameForMethod

        public static String spanNameForMethod​(Method method)
        This method is used to generate an acceptable span (operation) name based on a given method reference. Anonymous classes are named based on their parent.

      • spanNameForMethod

        public static String spanNameForMethod​(Class<?> clazz,
                                       @Nullable Method method)
        This method is used to generate an acceptable span (operation) name based on a given method reference. Anonymous classes are named based on their parent.

      • spanNameForMethod

        public static String spanNameForMethod​(Class<?> cl,
                                       String methodName)
        This method is used to generate an acceptable span (operation) name based on a given method reference. Anonymous classes are named based on their parent.

      • spanNameForClass

        public static String spanNameForClass​(Class<?> clazz)
        This method is used to generate an acceptable span (operation) name based on a given class reference. Anonymous classes are named based on their parent.

      • end

        public void end​(io.opentelemetry.context.Context context)
        Ends the execution of a span stored in the passed context.

      • end

        public void end​(io.opentelemetry.context.Context context,
                long endTimeNanos)
        Ends the execution of a span stored in the passed context.
        Parameters:
        endTimeNanos - Explicit nanoseconds timestamp from the epoch.

      • endExceptionally

        public void endExceptionally​(io.opentelemetry.context.Context context,
                             Throwable throwable)
        Records the throwable in the span stored in the passed context and marks the end of the span's execution.
        See Also:
        onException(Context, Throwable), end(Context)

      • endExceptionally

        public void endExceptionally​(io.opentelemetry.context.Context context,
                             Throwable throwable,
                             long endTimeNanos)
        Records the throwable in the span stored in the passed context and marks the end of the span's execution.
        Parameters:
        endTimeNanos - Explicit nanoseconds timestamp from the epoch.
        See Also:
        onException(Context, Throwable), end(Context, long)

      • onException

        public void onException​(io.opentelemetry.context.Context context,
                        Throwable throwable)
        Records the throwable in the span stored in the passed context and sets the span's status to StatusCode.ERROR. The throwable is unwrapped (unwrapThrowable(Throwable)) before being added to the span.

      • extract

        public <C> io.opentelemetry.context.Context extract​(C carrier,
                                                    io.opentelemetry.context.propagation.TextMapGetter<C> getter)
        Extracts a Context from carrier using the propagator embedded in this tracer. This method can be used to propagate Context passed from upstream services.
        See Also:
        TextMapPropagator.extract(Context, Object, TextMapGetter)

      • inject

        public <C> void inject​(io.opentelemetry.context.Context context,
                       C carrier,
                       io.opentelemetry.context.propagation.TextMapSetter<C> setter)
        Injects context data into carrier using the propagator embedded in this tracer. This method can be used to propagate passed context to downstream services.
        See Also:
        TextMapPropagator.inject(Context, Object, TextMapSetter)