Class Span

java.lang.Object
one.profiler.Span
public class Span extends Object
Records latency spans into the async-profiler JFR recording.

A span is a [start, end] time interval on the current thread, labeled with a tag (e.g. an operation or endpoint name). Spans are written into the same JFR file as the profiling samples, so the profile can later be filtered by span duration or tag. When async-profiler is not loaded or no JFR session is running, all methods are cheap no-ops.

  • Method Details

    • start

      public static long start()
      Marks the start of a span on the current thread.
      Returns:
      a start timestamp to pass to end(long, String) / endIfProfiled(long, String), or 0 if async-profiler is not loaded

    • end

      public static void end(long startTime, String tag)
      Ends a span opened with start() and records it with the given tag.
      Parameters:
      startTime - the value returned by start()
      tag - an arbitrary label, or null

    • endIfProfiled

      public static void endIfProfiled(long startTime, String tag)
      Like end(long, String), but records the span only if at least one profiling sample was taken on this thread while it was open. Useful for very frequent spans: those enclosing no sample add nothing to the profile and are skipped without entering native code.
      Parameters:
      startTime - the value returned by start()
      tag - an arbitrary label, or null

    • emit

      public static void emit(long startTime, long endTime, String tag)
      Records a span with explicit start and end timestamps obtained from Recording.timestamp() or converted from another clock using Recording.clockFrequency().
      Parameters:
      tag - an arbitrary label, or null

    • emitIfProfiled

      public static void emitIfProfiled(long startTime, long endTime, String tag)
      Like emit(long, long, String), but records the span only if a profiling sample was taken on this thread within [startTime, endTime].
      Parameters:
      tag - an arbitrary label, or null