Package com.azure.core.util.tracing

Interface Tracer

public interface Tracer
Contract that all tracers must implement to be pluggable into the SDK.
See Also:

  • Field Details

  • Method Details

    • start

      Context start(String methodName, Context context)
      Creates a new tracing span.

      The context will be checked for information about a parent span. If a parent span is found, the new span will be added as a child. Otherwise, the parent span will be created and added to the context and any downstream start() calls will use the created span as the parent.

      Code samples

      Starts a tracing span with provided method name and explicit parent span

       // start a new tracing span with given name and parent context implicitly propagated
 // in io.opentelemetry.context.Context.current()

 Throwable throwable = null;
 Context span = tracer.start("keyvault.setsecret", Context.NONE);
 try {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, span);
 }
      Parameters:
      methodName - Name of the method triggering the span creation.
      context - Additional metadata that is passed through the call stack.
      Returns:
      The updated Context object containing the returned span.
      Throws:
      NullPointerException - if methodName or context is null.

    • start

      default Context start(String methodName, StartSpanOptions options, Context context)
      Creates a new tracing span.

      The context will be checked for information about a parent span. If a parent span is found, the new span will be added as a child. Otherwise, the parent span will be created and added to the context and any downstream start() calls will use the created span as the parent.

      Code samples

      Starts a tracing span with provided method name and explicit parent span

       // start a new CLIENT tracing span with the given start options and explicit parent context
 StartSpanOptions options = new StartSpanOptions(SpanKind.CLIENT)
     .setAttribute("key", "value");
 Context spanFromOptions = tracer.start("keyvault.setsecret", options, Context.NONE);
 try {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, spanFromOptions);
 }
      Parameters:
      methodName - Name of the method triggering the span creation.
      options - span creation options.
      context - Additional metadata that is passed through the call stack.
      Returns:
      The updated Context object containing the returned span.
      Throws:
      NullPointerException - if options or context is null.

    • start

      @Deprecated default Context start(String spanName, Context context, ProcessKind processKind)
      Deprecated.
      use start(String, StartSpanOptions, Context) instead.
      Creates a new tracing span for AMQP calls.

      The context will be checked for information about a parent span. If a parent span is found, the new span will be added as a child. Otherwise, the parent span will be created and added to the context and any downstream start() calls will use the created span as the parent.

      Sets additional request attributes on the created span when processKind is ProcessKind.SEND.

      Returns the diagnostic Id and span context of the returned span when processKind is ProcessKind.MESSAGE.

      Creates a new tracing span with remote parent and returns that scope when the given when processKind is ProcessKind.PROCESS.

      Code samples

      Starts a tracing span with provided method name and AMQP operation SEND

      Parameters:
      spanName - Name of the method triggering the span creation.
      context - Additional metadata that is passed through the call stack.
      processKind - AMQP operation kind.
      Returns:
      The updated Context object containing the returned span.
      Throws:
      NullPointerException - if methodName or context or processKind is null.

    • end

      @Deprecated default void end(int responseCode, Throwable error, Context context)
      Deprecated.
      set specific attribute e.g. http_status_code explicitly and use end(String, Throwable, Context).
      Completes the current tracing span.

      Code samples

      Completes the tracing span present in the context, with the corresponding OpenTelemetry status for the given response status code

      Parameters:
      responseCode - Response status code if the span is in an HTTP call context.
      error - Throwable that happened during the span or null if no exception occurred.
      context - Additional metadata that is passed through the call stack.
      Throws:
      NullPointerException - if context is null.

    • end

      void end(String errorMessage, Throwable throwable, Context context)
      Completes span on the context.

      Code samples

      Completes the tracing span with unset status

       Context messageSpan = tracer.start("ServiceBus.message", new StartSpanOptions(SpanKind.PRODUCER), Context.NONE);
 tracer.end(null, null, messageSpan);

      Completes the tracing span with provided error message

       Context span = tracer.start("ServiceBus.send", new StartSpanOptions(SpanKind.CLIENT), Context.NONE);
 tracer.end("amqp:not-found", null, span);

      Completes the tracing span with provided exception

       Context sendSpan = tracer.start("ServiceBus.send", new StartSpanOptions(SpanKind.CLIENT), Context.NONE);
 try (AutoCloseable scope = tracer.makeSpanCurrent(sendSpan)) {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, sendSpan);
 }
      Parameters:
      errorMessage - The error message that occurred during the call, or null if no error. occurred. Any other non-null string indicates an error with description provided in errorMessage.
      throwable - Throwable that happened during the span or null if no exception occurred.
      context - Additional metadata that is passed through the call stack.
      Throws:
      NullPointerException - if context is null.

    • setAttribute

      void setAttribute(String key, String value, Context context)
      Adds metadata to the current span. If no span information is found in the context, then no metadata is added. 
       span = tracer.start("EventHubs.process", Context.NONE);
 tracer.setAttribute("bar", "baz", span);
      Parameters:
      key - Name of the metadata.
      value - Value of the metadata.
      context - Additional metadata that is passed through the call stack.
      Throws:
      NullPointerException - if key or value or context is null.

    • setAttribute

      default void setAttribute(String key, long value, Context context)
      Sets long attribute. 
       Context span = tracer.start("EventHubs.process", Context.NONE);
 tracer.setAttribute("foo", 42, span);
      Parameters:
      key - attribute name
      value - atteribute value
      context - tracing context

    • setAttribute

      default void setAttribute(String key, Object value, Context context)
      Sets an attribute on span. Adding duplicate attributes, update, or removal is discouraged, since underlying implementations behavior can vary.
      Parameters:
      key - attribute key.
      value - attribute value. Note that underlying tracer implementations limit supported value types. OpenTelemetry implementation supports following types:
      • String
      • int
      • double
      • boolean
      • long
      context - context containing span to which attribute is added.

    • setSpanName

      @Deprecated default Context setSpanName(String spanName, Context context)
      Deprecated.
      not needed.
      Sets the name for spans that are created.

      Code samples

      Retrieve the span name of the returned span

      Parameters:
      spanName - Name to give the next span.
      context - Additional metadata that is passed through the call stack.
      Returns:
      The updated Context object containing the name of the returned span.
      Throws:
      NullPointerException - if spanName or context is null.

    • addLink

      @Deprecated default void addLink(Context context)
      Deprecated.
      use StartSpanOptions.addLink(TracingLink) )}
      Provides a way to link multiple tracing spans. Used in batching operations to relate multiple requests under a single batch.

      Code samples

      Link multiple spans using their span context information

      Parameters:
      context - Additional metadata that is passed through the call stack.
      Throws:
      NullPointerException - if context is null.

    • extractContext

      @Deprecated default Context extractContext(String diagnosticId, Context context)
      Deprecated.
      use extractContext(Function)
      Extracts the span's context as Context from upstream.

      Code samples

      Extracts the corresponding span context information from a valid diagnostic id

      Parameters:
      diagnosticId - Unique identifier for the trace information of the span.
      context - Additional metadata that is passed through the call stack.
      Returns:
      The updated Context object containing the span context.
      Throws:
      NullPointerException - if diagnosticId or context is null.

    • extractContext

      default Context extractContext(Function<String,String> headerGetter)
      Extracts the span's context as Context from upstream.

      Code samples

      Extracts the corresponding span context information from a valid diagnostic id

       Context parentContext = tracer.extractContext(name -> {
     Object value = messageProperties.get(name);
     return value instanceof String ? (String) value : null;
 });

 StartSpanOptions remoteParentOptions = new StartSpanOptions(SpanKind.CONSUMER)
     .setRemoteParent(parentContext);

 Context spanWithRemoteParent = tracer.start("EventHubs.process", remoteParentOptions, Context.NONE);

 try (AutoCloseable scope = tracer.makeSpanCurrent(spanWithRemoteParent)) {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, spanWithRemoteParent);
 }
      Parameters:
      headerGetter - Unique identifier for the trace information of the span and todo.
      Returns:
      The updated Context object containing the span context.
      Throws:
      NullPointerException - if diagnosticId or context is null.

    • injectContext

      default void injectContext(BiConsumer<String,String> headerSetter, Context context)
      Injects tracing context. 
       Context httpSpan = tracer.start("HTTP GET", new StartSpanOptions(SpanKind.CLIENT), methodSpan);
 tracer.injectContext((headerName, headerValue) -> request.setHeader(headerName, headerValue), httpSpan);

 try (AutoCloseable scope = tracer.makeSpanCurrent(httpSpan)) {
     HttpResponse response = getResponse(request);
     httpResponseCode = response.getStatusCode();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(httpResponseCode, throwable, httpSpan);
 }
      Parameters:
      headerSetter - callback to set context with.
      context - trace context instance

    • getSharedSpanBuilder

      @Deprecated default Context getSharedSpanBuilder(String spanName, Context context)
      Deprecated.
      use StartSpanOptions.addLink(TracingLink) instead
      Returns a span builder with the provided name in Context.

      Code samples

      Returns a builder with the provided span name.

      Parameters:
      spanName - Name to give the span for the created builder.
      context - Additional metadata that is passed through the call stack.
      Returns:
      The updated Context object containing the span builder.
      Throws:
      NullPointerException - if context or spanName is null.

    • addEvent

      @Deprecated default void addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp)
      Deprecated.
      Use addEvent(String, Map, OffsetDateTime, Context)
      Adds an event to the current span with the provided timestamp and attributes.

      This API does not provide any normalization if provided timestamps are out of range of the current span timeline

      Supported attribute values include String, double, boolean, long, String [], double [], long []. Any other Object value type and null values will be silently ignored.

      Parameters:
      name - the name of the event.
      attributes - the additional attributes to be set for the event.
      timestamp - The instant, in UTC, at which the event will be associated to the span.
      Throws:
      NullPointerException - if eventName is null.

    • addEvent

      default void addEvent(String name, Map<String,Object> attributes, OffsetDateTime timestamp, Context context)
      Adds an event to the span present in the Context with the provided timestamp and attributes.

      This API does not provide any normalization if provided timestamps are out of range of the current span timeline

      Supported attribute values include String, double, boolean, long, String [], double [], long []. Any other Object value type and null values will be silently ignored.

       Context span = tracer.start("Cosmos.getItem", Context.NONE);
 tracer.addEvent("trying another endpoint", Collections.singletonMap("endpoint", "westus3"), OffsetDateTime.now(), span);
      Parameters:
      name - the name of the event.
      attributes - the additional attributes to be set for the event.
      timestamp - The instant, in UTC, at which the event will be associated to the span.
      context - the call metadata containing information of the span to which the event should be associated with.
      Throws:
      NullPointerException - if eventName is null.

    • makeSpanCurrent

      default AutoCloseable makeSpanCurrent(Context context)
      Makes span current. Implementations may put it on ThreadLocal. Make sure to always use try-with-resource statement with makeSpanCurrent
      Parameters:
      context - Context with span. 
       Context span = tracer.start("EventHubs.process", new StartSpanOptions(SpanKind.CONSUMER), Context.NONE);
 try (AutoCloseable scope = tracer.makeSpanCurrent(span)) {
     doWork();
 } catch (Throwable ex) {
     throwable = ex;
 } finally {
     tracer.end(null, throwable, span);
 }
      Returns:
      Closeable that should be closed in the same thread with try-with-resource statement.

    • isRecording

      default boolean isRecording(Context span)
      Checks if span is sampled in.
      Parameters:
      span - Span to check.
      Returns:
      true if span is recording, false otherwise.

    • isEnabled

      default boolean isEnabled()
      Checks if tracer is enabled. 
       if (!tracer.isEnabled()) {
     doWork();
 } else {
     Context span = tracer.start("span", Context.NONE);
     try {
         doWork();
     } catch (Throwable ex) {
         throwable = ex;
     } finally {
         tracer.end(null, throwable, span);
     }
 }
      Returns:
      true if tracer is enabled, false otherwise.