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 
      Modifier Constructor Description
      protected BaseTracer()
      Deprecated.
      always pass an OpenTelemetry instance.
      protected BaseTracer​(io.opentelemetry.api.OpenTelemetry openTelemetry)  

    • Method Summary

      All Methods Instance Methods Abstract 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.
      protected abstract String getInstrumentationName()
      The name of the instrumentation library, not the name of the instrument*ed* library.
      protected String getVersion()
      The version of the instrumentation library - defaults to the value of JAR manifest attribute Implementation-Version.
      <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.
      protected io.opentelemetry.api.trace.SpanBuilder spanBuilder​(io.opentelemetry.context.Context parentContext, String spanName, io.opentelemetry.api.trace.SpanKind kind)
      Returns a SpanBuilder to create and start a new Span.
      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.
      protected Throwable unwrapThrowable​(Throwable throwable)
      Extracts the actual cause by unwrapping passed throwable from known wrapper exceptions, e.g ExecutionException.
      protected io.opentelemetry.context.Context withClientSpan​(io.opentelemetry.context.Context parentContext, io.opentelemetry.api.trace.Span span)
      Returns a Context containing the passed span marked as the current SpanKind.CLIENT span.
      protected io.opentelemetry.context.Context withConsumerSpan​(io.opentelemetry.context.Context parentContext, io.opentelemetry.api.trace.Span span)
      Returns a Context containing the passed span marked as the current SpanKind.CONSUMER span.
      protected io.opentelemetry.context.Context withServerSpan​(io.opentelemetry.context.Context parentContext, io.opentelemetry.api.trace.Span span)
      Returns a Context containing the passed span marked as the current SpanKind.SERVER span.

    • Constructor Detail

      • BaseTracer

        @Deprecated
protected 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

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

    • Method Detail

      • getInstrumentationName

        protected abstract String getInstrumentationName()
        The name of the instrumentation library, not the name of the instrument*ed* library. The value returned by this method should uniquely identify the instrumentation library so that during troubleshooting it's possible to pinpoint what tracer produced problematic telemetry.

        In this project we use a convention to encode the version of the instrument*ed* library into the instrumentation name, for example io.opentelemetry.apache-httpclient-4.0. This way, if there are different instrumentations for different library versions it's easy to find out which instrumentations produced the telemetry data.

        See Also:
        TracerProvider.get(String, String)

      • getVersion

        protected String getVersion()
        The version of the instrumentation library - defaults to the value of JAR manifest attribute Implementation-Version.

      • 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.

      • spanBuilder

        protected final io.opentelemetry.api.trace.SpanBuilder spanBuilder​(io.opentelemetry.context.Context parentContext,
                                                                   String spanName,
                                                                   io.opentelemetry.api.trace.SpanKind kind)
        Returns a SpanBuilder to create and start a new Span.

      • withClientSpan

        protected final io.opentelemetry.context.Context withClientSpan​(io.opentelemetry.context.Context parentContext,
                                                                io.opentelemetry.api.trace.Span span)
        Returns a Context containing the passed span marked as the current SpanKind.CLIENT span.
        See Also:
        shouldStartSpan(Context, SpanKind)

      • withServerSpan

        protected final io.opentelemetry.context.Context withServerSpan​(io.opentelemetry.context.Context parentContext,
                                                                io.opentelemetry.api.trace.Span span)
        Returns a Context containing the passed span marked as the current SpanKind.SERVER span.
        See Also:
        shouldStartSpan(Context, SpanKind)

      • withConsumerSpan

        protected final io.opentelemetry.context.Context withConsumerSpan​(io.opentelemetry.context.Context parentContext,
                                                                  io.opentelemetry.api.trace.Span span)
        Returns a Context containing the passed span marked as the current SpanKind.CONSUMER span.
        See Also:
        shouldStartSpan(Context, SpanKind)

      • 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.

      • unwrapThrowable

        protected Throwable unwrapThrowable​(Throwable throwable)
        Extracts the actual cause by unwrapping passed throwable from known wrapper exceptions, e.g ExecutionException.

      • 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)