Class Spans

java.lang.Object
codes.grow.packages.tempo.tracing.Spans

public final class Spans extends Object
Span helpers on top of the OpenTelemetry API. Without an explicit tracer or propagators they use Tracing.openTelemetry().

 Order order = Spans.withSpan("load-order", () -> repository.load(id));
 Spans.addEvent("cache-miss");
 Map<String, String> headers = new HashMap<>();
 Spans.inject(headers);
 
  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    Adds an event to the current span.
    static void
    addEvent(String name, Map<String,?> attributes)
    Adds an event with attributes to the current span.
    static io.opentelemetry.api.trace.Span
    The current span (an invalid no-op span when none is active).
    Span id of the current span.
    Trace id of the current span.
    static io.opentelemetry.context.Context
    Extracts a context from a string map (keys match case-insensitively).
    static io.opentelemetry.context.Context
    extract(Map<String,String> carrier, io.opentelemetry.context.propagation.ContextPropagators propagators)
    Extracts with explicit propagators.
    static io.opentelemetry.context.Context
    Extracts a context from a multi-valued header map (names match case-insensitively).
    static io.opentelemetry.context.Context
    extractHeaders(Map<String,List<String>> headers, io.opentelemetry.context.propagation.ContextPropagators propagators)
    Extracts from a multi-valued header map with explicit propagators.
    static List<String>
    fields(io.opentelemetry.context.propagation.ContextPropagators propagators)
    Names of the propagation fields of the given propagators.
    static Map<String,String>
    headersFor(io.opentelemetry.context.propagation.ContextPropagators propagators)
    The headers a request should carry for the current context.
    static void
    inject(io.opentelemetry.context.Context context, Map<String,String> carrier, io.opentelemetry.context.propagation.ContextPropagators propagators)
    Injects a context with explicit propagators.
    static void
    inject(Map<String,String> carrier)
    Injects the current context into a string map (for example message headers).
    static void
    injectHeaders(io.opentelemetry.context.Context context, Map<String,List<String>> headers, io.opentelemetry.context.propagation.ContextPropagators propagators)
    Injects a context into a multi-valued header map with explicit propagators.
    static void
    Injects the current context into a multi-valued header map (as used by java.net.http.HttpHeaders or servlet APIs); existing propagation headers are replaced.
    static void
    Records an exception event on the current span (status unchanged).
    static void
    setError(io.opentelemetry.api.trace.Span span, Throwable error)
    Records the exception and sets status ERROR on span.
    static void
    setError(String message)
    Sets status ERROR with a message on the current span.
    static void
    Records the exception and sets status ERROR on the current span.
    static io.opentelemetry.api.trace.Span
    start(String name, SpanOptions options)
    Starts (but does not end or activate) a span with options.
    static Map<String,String>
    Log correlation fields of the current span (trace_id, span_id; snake_case on purpose, the log field convention).
    static io.opentelemetry.api.trace.Tracer
    The tracer the helpers use by default.
    static <E extends Throwable>
    void
    withSpan(String name, SpanOptions options, ThrowingRunnable<E> fn)
    Runs fn in a new span with options.
    static <T, E extends Throwable>
    T
    withSpan(String name, SpanOptions options, ThrowingSupplier<T,E> fn)
    Runs fn in a new span with options.
    static <E extends Throwable>
    void
    Runs fn in a new internal span.
    static <T, E extends Throwable>
    T
    Runs fn in a new internal span that is current while it runs.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • tracer

      public static io.opentelemetry.api.trace.Tracer tracer()
      The tracer the helpers use by default.
      Returns:
      tracer of Tracing.openTelemetry()
    • withSpan

      public static <T, E extends Throwable> T withSpan(String name, ThrowingSupplier<T,E> fn) throws E
      Runs fn in a new internal span that is current while it runs. The span ends when fn returns; an exception is recorded, sets status ERROR and is rethrown.
      Type Parameters:
      T - result type
      E - exception type
      Parameters:
      name - span name
      fn - work
      Returns:
      the result of fn
      Throws:
      E - what fn throws
    • withSpan

      public static <T, E extends Throwable> T withSpan(String name, SpanOptions options, ThrowingSupplier<T,E> fn) throws E
      Runs fn in a new span with options.
      Type Parameters:
      T - result type
      E - exception type
      Parameters:
      name - span name
      options - attributes, kind, links, tracer, parent
      fn - work
      Returns:
      the result of fn
      Throws:
      E - what fn throws
    • withSpan

      public static <E extends Throwable> void withSpan(String name, ThrowingRunnable<E> fn) throws E
      Runs fn in a new internal span.
      Type Parameters:
      E - exception type
      Parameters:
      name - span name
      fn - work
      Throws:
      E - what fn throws
    • withSpan

      public static <E extends Throwable> void withSpan(String name, SpanOptions options, ThrowingRunnable<E> fn) throws E
      Runs fn in a new span with options.
      Type Parameters:
      E - exception type
      Parameters:
      name - span name
      options - options
      fn - work
      Throws:
      E - what fn throws
    • start

      public static io.opentelemetry.api.trace.Span start(String name, SpanOptions options)
      Starts (but does not end or activate) a span with options.
      Parameters:
      name - span name
      options - options
      Returns:
      started span
    • currentSpan

      public static io.opentelemetry.api.trace.Span currentSpan()
      The current span (an invalid no-op span when none is active).
      Returns:
      span
    • currentTraceId

      public static Optional<String> currentTraceId()
      Trace id of the current span.
      Returns:
      32 lower-hex characters, or empty when no valid span is active
    • currentSpanId

      public static Optional<String> currentSpanId()
      Span id of the current span.
      Returns:
      16 lower-hex characters, or empty when no valid span is active
    • addEvent

      public static void addEvent(String name)
      Adds an event to the current span.
      Parameters:
      name - event name
    • addEvent

      public static void addEvent(String name, Map<String,?> attributes)
      Adds an event with attributes to the current span.
      Parameters:
      name - event name
      attributes - attribute values
    • recordException

      public static void recordException(Throwable error)
      Records an exception event on the current span (status unchanged).
      Parameters:
      error - exception
    • setError

      public static void setError(Throwable error)
      Records the exception and sets status ERROR on the current span.
      Parameters:
      error - exception
    • setError

      public static void setError(String message)
      Sets status ERROR with a message on the current span.
      Parameters:
      message - status description
    • setError

      public static void setError(io.opentelemetry.api.trace.Span span, Throwable error)
      Records the exception and sets status ERROR on span.
      Parameters:
      span - span
      error - exception
    • inject

      public static void inject(Map<String,String> carrier)
      Injects the current context into a string map (for example message headers).
      Parameters:
      carrier - mutable map
    • inject

      public static void inject(io.opentelemetry.context.Context context, Map<String,String> carrier, io.opentelemetry.context.propagation.ContextPropagators propagators)
      Injects a context with explicit propagators.
      Parameters:
      context - context
      carrier - mutable map
      propagators - propagators
    • extract

      public static io.opentelemetry.context.Context extract(Map<String,String> carrier)
      Extracts a context from a string map (keys match case-insensitively).
      Parameters:
      carrier - map
      Returns:
      context (the current context plus the extracted span context and baggage)
    • extract

      public static io.opentelemetry.context.Context extract(Map<String,String> carrier, io.opentelemetry.context.propagation.ContextPropagators propagators)
      Extracts with explicit propagators.
      Parameters:
      carrier - map
      propagators - propagators
      Returns:
      context
    • injectHeaders

      public static void injectHeaders(Map<String,List<String>> headers)
      Injects the current context into a multi-valued header map (as used by java.net.http.HttpHeaders or servlet APIs); existing propagation headers are replaced.
      Parameters:
      headers - mutable header map
    • injectHeaders

      public static void injectHeaders(io.opentelemetry.context.Context context, Map<String,List<String>> headers, io.opentelemetry.context.propagation.ContextPropagators propagators)
      Injects a context into a multi-valued header map with explicit propagators.
      Parameters:
      context - context
      headers - mutable header map
      propagators - propagators
    • extractHeaders

      public static io.opentelemetry.context.Context extractHeaders(Map<String,List<String>> headers)
      Extracts a context from a multi-valued header map (names match case-insensitively).
      Parameters:
      headers - header map
      Returns:
      context
    • extractHeaders

      public static io.opentelemetry.context.Context extractHeaders(Map<String,List<String>> headers, io.opentelemetry.context.propagation.ContextPropagators propagators)
      Extracts from a multi-valued header map with explicit propagators.
      Parameters:
      headers - header map
      propagators - propagators
      Returns:
      context
    • headersFor

      public static Map<String,String> headersFor(io.opentelemetry.context.propagation.ContextPropagators propagators)
      The headers a request should carry for the current context.
      Parameters:
      propagators - propagators
      Returns:
      header name to value
    • traceFields

      public static Map<String,String> traceFields()
      Log correlation fields of the current span (trace_id, span_id; snake_case on purpose, the log field convention).
      Returns:
      fields (empty when no valid span is active)
    • fields

      public static List<String> fields(io.opentelemetry.context.propagation.ContextPropagators propagators)
      Names of the propagation fields of the given propagators.
      Parameters:
      propagators - propagators
      Returns:
      header names