Class OpenTelemetryTracer

java.lang.Object
com.azure.core.tracing.opentelemetry.OpenTelemetryTracer
All Implemented Interfaces:
Tracer

public class OpenTelemetryTracer extends Object implements Tracer
Basic tracing implementation class for use with REST and AMQP Service Clients to create Span and in-process context propagation. Singleton OpenTelemetry tracer capable of starting and exporting spans.

This helper class supports W3C distributed tracing protocol and injects SpanContext into the outgoing HTTP and AMQP requests.

  • Constructor Details

    • OpenTelemetryTracer

      public OpenTelemetryTracer()
      Creates new OpenTelemetryTracer using default global tracer - GlobalOpenTelemetry.getTracer(String)
  • Method Details

    • start

      public Context start(String spanName, 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()
       Context traceContext = tracer.start("keyvault.setsecret", Context.NONE);
       System.out.printf("OpenTelemetry Context with started `keyvault.setsecret` span: %s%n",
           traceContext.getData(PARENT_TRACE_CONTEXT_KEY).get());
       
      Specified by:
      start in interface Tracer
      Parameters:
      spanName - 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.
    • start

      public Context start(String spanName, 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 updatedClientSpanContext = tracer.start("keyvault.setsecret", options, traceContext);
       System.out.printf("OpenTelemetry Context with started `keyvault.setsecret` span: %s%n",
           updatedClientSpanContext.getData(PARENT_TRACE_CONTEXT_KEY).get());
       
      Specified by:
      start in interface Tracer
      Parameters:
      spanName - 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.
    • start

      public Context start(String spanName, Context context, ProcessKind processKind)
      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

       // pass request metadata to the calling method
       Context sendContext = new Context(ENTITY_PATH_KEY, "entity-path").addData(HOST_NAME_KEY, "hostname");
      
       // start a new tracing span with explicit parent, sets the request attributes on the span and sets the span
       // kind to client when process kind SEND
       Context updatedSendContext = tracer.start("eventhubs.send", sendContext, ProcessKind.SEND);
       System.out.printf("OpenTelemetry Context with started `eventhubs.send` span: %s%n",
           updatedSendContext.getData(PARENT_TRACE_CONTEXT_KEY).get());
       

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

       String diagnosticIdKey = "Diagnostic-Id";
       // start a new tracing span with explicit parent, sets the diagnostic Id (traceparent headers) on the current
       // context when process kind MESSAGE
       Context updatedReceiveContext = tracer.start("EventHubs.receive", traceContext,
           ProcessKind.MESSAGE);
       System.out.printf("Diagnostic Id: %s%n", updatedReceiveContext.getData(diagnosticIdKey).get());
       

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

       String spanImplContext = "span-context";
       // start a new tracing span with remote parent and uses current context to return a scope
       // when process kind PROCESS
       Context processContext = new Context(PARENT_TRACE_CONTEXT_KEY, "<OpenTelemetry-context>")
           .addData(spanImplContext, "<user-current-span-context>");
       Context updatedProcessContext = tracer.start("EventHubs.process", processContext,
           ProcessKind.PROCESS);
       System.out.printf("Scope: %s%n", updatedProcessContext.getData("scope").get());
       
      Specified by:
      start in interface Tracer
      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.
    • end

      public void end(int responseCode, Throwable throwable, Context 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

       // context containing the span to end
       String openTelemetrySpanKey = "openTelemetry-span";
       Context traceContext = new Context(PARENT_TRACE_CONTEXT_KEY, "<user-current-span>");
      
       // completes the tracing span with the passed response status code
       tracer.end(200, null, traceContext);
       
      Specified by:
      end in interface Tracer
      Parameters:
      responseCode - Response status code if the span is in an HTTP call context.
      throwable - Throwable that happened during the span or null if no exception occurred.
      context - Additional metadata that is passed through the call stack.
    • setAttribute

      public 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.
      Specified by:
      setAttribute in interface Tracer
      Parameters:
      key - Name of the metadata.
      value - Value of the metadata.
      context - Additional metadata that is passed through the call stack.
    • setSpanName

      public Context setSpanName(String spanName, Context context)
      Sets the name for spans that are created.

      Code samples

      Retrieve the span name of the returned span

       // Sets future span name - it will be used when span will be started on this context
       Context contextWithName = tracer.setSpanName("keyvault.setsecret", Context.NONE);
       Context traceContext = tracer.start("placeholder", contextWithName);
      
       System.out.printf("OpenTelemetry Context with started `keyvault.setsecret` span: %s%n",
           traceContext.getData(PARENT_TRACE_CONTEXT_KEY).get());
       
      Specified by:
      setSpanName in interface Tracer
      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.
    • end

      public void end(String statusMessage, Throwable throwable, Context context)
      Completes the current tracing span for AMQP calls.

      Code samples

      Completes the tracing span with the corresponding OpenTelemetry status for the given status message

       // context containing the current trace context to end
       // completes the tracing span with the passed status message
       tracer.end("success", null, traceContext);
       
      Specified by:
      end in interface Tracer
      Parameters:
      statusMessage - The error or success message that occurred during the call, or null if no error occurred.
      throwable - Throwable that happened during the span or null if no exception occurred.
      context - Additional metadata that is passed through the call stack.
    • addLink

      public void addLink(Context context)
      Description copied from interface: Tracer
      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

       // start a new tracing span with given name and parent context implicitly propagated
       // in io.opentelemetry.context.Context.current()
       Context spanContext = tracer.start("test.method", Context.NONE, ProcessKind.MESSAGE);
      
       // Adds a link between multiple span's using the span context information of the Span
       // For each event processed, add a link with the created spanContext
       tracer.addLink(spanContext);
       
      Specified by:
      addLink in interface Tracer
      Parameters:
      context - Additional metadata that is passed through the call stack.
    • extractContext

      public Context extractContext(String diagnosticId, Context context)
      Extracts the span's context as Context from upstream.

      Code samples

      Extracts the corresponding span context information from a valid diagnostic id

       // Extracts the span context information from the passed diagnostic Id that can be used for linking spans.
       String spanImplContext = "span-context";
       Context spanContext = tracer.extractContext("valid-diagnostic-id", Context.NONE);
       System.out.printf("Span context of the current tracing span: %s%n", spanContext.getData(spanImplContext).get());
       
      Specified by:
      extractContext in interface Tracer
      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.
    • getSharedSpanBuilder

      public Context getSharedSpanBuilder(String spanName, Context context)
      Returns a span builder with the provided name in Context.

      Code samples

      Returns a builder with the provided span name.

       // Returns a span builder with the provided name
       Context spanContext = tracer.getSharedSpanBuilder("message-span", Context.NONE);
       System.out.printf("Builder of current span being built: %s%n", spanContext.getData(SPAN_BUILDER_KEY).get());
       
      Specified by:
      getSharedSpanBuilder in interface Tracer
      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.
    • makeSpanCurrent

      public AutoCloseable makeSpanCurrent(Context context)
      Makes span current. Implementations may put it on ThreadLocal. Make sure to always use try-with-resource statement with makeSpanCurrent
      Specified by:
      makeSpanCurrent in interface Tracer
      Parameters:
      context - Context with span.

      Code samples

      Starts a tracing span, makes it current and ends it

       // Starts a span, makes it current and then stops it.
       Context traceContext = tracer.start("EventHubs.process", Context.NONE);
      
       // Make sure to always use try-with-resource statement with makeSpanCurrent
       try (AutoCloseable ignored = tracer.makeSpanCurrent(traceContext)) {
           System.out.println("doing some work...");
       } catch (Throwable throwable) {
           tracer.end("Failure", throwable, traceContext);
       } finally {
           tracer.end("OK", null, traceContext);
       }
      
       
      Returns:
      Closeable that should be closed in the same thread with try-with-resource statement.
    • addEvent

      public void addEvent(String eventName, Map<String,Object> traceEventAttributes, OffsetDateTime timestamp)
      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.

      Specified by:
      addEvent in interface Tracer
      Parameters:
      eventName - the name of the event.
      traceEventAttributes - the additional attributes to be set for the event.
      timestamp - The instant, in UTC, at which the event will be associated to the span.
    • addEvent

      public void addEvent(String eventName, Map<String,Object> traceEventAttributes, 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.

      Specified by:
      addEvent in interface Tracer
      Parameters:
      eventName - the name of the event.
      traceEventAttributes - 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.