Package com.aembot.lib.tracing

Class Tracer

java.lang.Object
com.aembot.lib.tracing.Tracer
public final class Tracer extends Object
Lightweight tracing system for measuring function execution times. Uses a circular buffer of pre-allocated loops to avoid GC during robot loop.

Usage: 


 // In robotPeriodic():
 Tracer.beginLoop();
 // ... robot code (traced via @Traced annotations)
 Tracer.endLoop();

 // Export when disabled:
 Tracer.exportToJson("/U/logs/trace.json");

  • Field Details

    • DEFAULT_CATEGORY

      public static final String DEFAULT_CATEGORY
      Default category used when none is specified
      See Also:

  • Method Details

    • getCategoryIndex

      public static byte getCategoryIndex(String category)
      Get or register a category index. Returns existing index if category already registered. Uses HashMap for O(1) lookup. Public for use by interceptors that cache the index.
      Parameters:
      category - The category name
      Returns:
      The byte index for this category

    • beginLoop

      public static void beginLoop()
      Begin a new trace loop. Call this at the start of robotPeriodic().

      This advances the circular buffer and resets the current loop.

    • endLoop

      public static void endLoop()
      End the current trace loop. Call this at the end of robotPeriodic().

      Records the loop end time.

    • trace

      public static TraceScope trace(String name)
      Create a trace scope for a function. Use with try-with-resources.

      Usage: 

      
 try (var t = Tracer.trace("MyClass.myMethod")) {
     // Method body - automatically timed
 }
      Parameters:
      name - The name of the function/operation being traced
      Returns:
      A TraceScope that will automatically end the span when closed

    • trace

      public static TraceScope trace(String name, String category)
      Create a trace scope for a function with a category. Use with try-with-resources.

      Usage: 

      
 try (var t = Tracer.trace("periodic", "Drivetrain")) {
     // Method body - automatically timed and categorized
 }
      Parameters:
      name - The name of the function/operation being traced
      category - The category/subsystem (e.g., "Drivetrain", "Vision")
      Returns:
      A TraceScope that will automatically end the span when closed

    • beginSpan

      public static int beginSpan(String name)
      Begin a trace span for a function call.
      Parameters:
      name - The name of the function/operation being traced
      Returns:
      The span index (pass to endSpan), or -1 if tracing is disabled/full

    • beginSpan

      public static int beginSpan(String name, String category)
      Begin a trace span for a function call with a category.
      Parameters:
      name - The name of the function/operation being traced
      category - The category/subsystem (e.g., "Drivetrain", "Vision")
      Returns:
      The span index (pass to endSpan), or -1 if tracing is disabled/full

    • beginSpan

      public static int beginSpan(String name, byte categoryIndex)
      Begin a trace span with a pre-resolved category index. Faster than string category lookup. Use this from interceptors that cache the category index at first call.
      Parameters:
      name - The name of the function/operation being traced
      categoryIndex - The category index (from getCategoryIndex)
      Returns:
      The span index (pass to endSpan), or -1 if tracing is disabled/full

    • endSpan

      public static void endSpan(int spanIndex)
      End a trace span.
      Parameters:
      spanIndex - The index returned by beginSpan

    • isEnabled

      public static boolean isEnabled()
      Check if tracing is enabled

    • setEnabled

      public static void setEnabled(boolean enable)
      Enable or disable tracing. Disable for competition to eliminate all overhead.
      Parameters:
      enable - Whether to enable tracing

    • getCurrentLoop

      public static TraceLoop getCurrentLoop()
      Get the current loop being written to

    • getLoops

      public static TraceLoop[] getLoops()
      Get all loops in the buffer

    • getBufferSize

      public static int getBufferSize()
      Get the buffer size

    • getLoopIndex

      public static int getLoopIndex()
      Get the current loop index in the circular buffer

    • getTotalLoopCount

      public static int getTotalLoopCount()
      Get total number of loops recorded

    • getCategories

      public static List<String> getCategories()
      Get the category list (for export)

    • getThreadNames

      public static Map<Long,String> getThreadNames()
      Get the thread name cache (for export)

    • exportToJson

      public static void exportToJson(String path)
      Export traces to Chrome Tracing JSON format.
      Parameters:
      path - The file path to write to

    • exportRecentToJson

      public static void exportRecentToJson(String path, int numLoops)
      Export the most recent N loops to Chrome Tracing JSON format.
      Parameters:
      path - The file path to write to
      numLoops - Number of recent loops to export