Package com.helix.profiler.flamegraph

Class FlameGraphAggregator

java.lang.Object
com.helix.profiler.flamegraph.FlameGraphAggregator
All Implemented Interfaces:
ProfileEventListener, AutoCloseable
public class FlameGraphAggregator extends Object implements ProfileEventListener, AutoCloseable
In-memory folded stack trace aggregation engine that transforms execution and allocation samples from internal profilers, thread dumps, and JDK Flight Recorder (JFR) into hierarchical flame graph call trees.

Supports dynamic switching between CPU execution samples (MetricType.CPU_TIME) and Heap memory allocation bytes (MetricType.ALLOCATION_BYTES). Outputs folded stack data strictly matching Brendan Gregg's FlameGraph specification.

  • Constructor Details

    • FlameGraphAggregator

      public FlameGraphAggregator()

  • Method Details

    • setMetric

      public void setMetric(MetricType metricType)
      Dynamically sets the active metric dimension.

    • setActiveMetric

      public void setActiveMetric(MetricType metricType)

    • getMetric

      public MetricType getMetric()
      Gets the currently active metric dimension.

    • getRootNode

      public StackFrameNode getRootNode()
      Retrieves the root prefix trie node for the active metric.

    • getRootNode

      public StackFrameNode getRootNode(MetricType metricType)
      Retrieves the root prefix trie node for the specified metric.

    • addSample

      public void addSample(List<String> frames, long value)
      Adds a stack trace sample with the specified value to the active metric.
      Parameters:
      frames - ordered call stack frames (root caller at index 0, leaf callee at last index)
      value - weight/count or allocation bytes

    • addSample

      public void addSample(List<String> frames)
      Adds a single count stack trace sample to the active metric.

    • addSample

      public void addSample(MetricType metric, List<String> frames, long value)
      Adds a stack trace sample with the specified value to a target metric.
      Parameters:
      metric - target metric dimension
      frames - ordered call stack frames (root caller at index 0, leaf callee at last index)
      value - weight/count or allocation bytes

    • addSample

      public void addSample(StackTraceElement[] stackTrace, long value)
      Ingests a JVM StackTraceElement array into the active metric.

    • addSample

      public void addSample(MetricType metric, StackTraceElement[] stackTrace, long value)
      Ingests a JVM StackTraceElement array into the specified metric.

    • ingestThreadDump

      public void ingestThreadDump(Map<Thread,StackTraceElement[]> traces)
      Ingests a thread dump snapshot (e.g. from Thread.getAllStackTraces()).

    • ingestThreadDump

      public void ingestThreadDump(MetricType metric, Map<Thread,StackTraceElement[]> traces)
      Ingests a thread dump snapshot into the specified metric.

    • sampleAllThreads

      public void sampleAllThreads()
      Performs a one-shot sample of all live JVM threads and aggregates them into the active metric.

    • ingestJfr

      public void ingestJfr(Path jfrFile) throws IOException
      Ingests events from a JDK Flight Recorder (.jfr) recording file. Automatically extracts CPU samples (jdk.ExecutionSample) into MetricType.CPU_TIME and heap allocations (jdk.ObjectAllocation*) into MetricType.ALLOCATION_BYTES.
      Parameters:
      jfrFile - path to .jfr file
      Throws:
      IOException - if reading the file fails

    • ingestJfrEvent

      public void ingestJfrEvent(RecordedEvent event)
      Ingests a single JFR RecordedEvent, automatically detecting CPU vs allocation metrics.

    • addFoldedLine

      public void addFoldedLine(String line)
      Parses and aggregates a single Brendan Gregg folded stack trace line (e.g. "func1;func2;func3 42").

    • addFoldedLine

      public void addFoldedLine(MetricType metric, String line)
      Parses and aggregates a single Brendan Gregg folded stack trace line into the specified metric.

    • ingestFoldedText

      public void ingestFoldedText(String foldedText)
      Ingests a multiline block of Brendan Gregg folded stack data.

    • ingestFoldedText

      public void ingestFoldedText(MetricType metric, String foldedText)
      Ingests a multiline block of Brendan Gregg folded stack data for a specific metric.

    • ingestFoldedFile

      public void ingestFoldedFile(Path path) throws IOException
      Ingests folded stack data from a file.
      Throws:
      IOException

    • ingestFoldedFile

      public void ingestFoldedFile(MetricType metric, Path path) throws IOException
      Ingests folded stack data from a file for a specific metric.
      Throws:
      IOException

    • startThreadSampling

      public void startThreadSampling(long interval, TimeUnit unit)
      Starts an asynchronous background periodic thread sampling loop.
      Parameters:
      interval - interval between thread dump samples
      unit - time unit

    • stopThreadSampling

      public void stopThreadSampling()
      Stops the background thread sampling loop.

    • isThreadSamplingActive

      public boolean isThreadSamplingActive()

    • onEvent

      public void onEvent(ProfileEvent event)
      Description copied from interface: ProfileEventListener
      Called when a profiler event is emitted.
      Specified by:
      onEvent in interface ProfileEventListener
      Parameters:
      event - the profiler event

    • exportFolded

      public String exportFolded()
      Exports the aggregated stack traces for the active metric in Brendan Gregg folded format.
      Returns:
      newline-delimited folded stack lines ("frame1;frame2;frame3 42")

    • exportFolded

      public String exportFolded(MetricType metric)
      Exports the aggregated stack traces for the specified metric in Brendan Gregg folded format.

    • exportFolded

      public void exportFolded(Path destination) throws IOException
      Writes the folded stack traces for the active metric to the specified destination path.
      Throws:
      IOException

    • exportFolded

      public void exportFolded(MetricType metric, Path destination) throws IOException
      Writes the folded stack traces for the specified metric to the destination path.
      Throws:
      IOException

    • exportFolded

      public void exportFolded(MetricType metric, Writer writer) throws IOException
      Writes the folded stack traces to the provided Writer.
      Throws:
      IOException

    • getTotalSamples

      public long getTotalSamples()
      Returns total samples/value aggregated for the active metric.

    • getTotalSamples

      public long getTotalSamples(MetricType metric)
      Returns total samples/value aggregated for the specified metric.

    • getDistinctStacksCount

      public int getDistinctStacksCount()
      Returns the count of distinct call stack paths terminating with samples.

    • getDistinctStacksCount

      public int getDistinctStacksCount(MetricType metric)
      Returns the count of distinct call stack paths terminating with samples for the specified metric.

    • getMaxDepth

      public int getMaxDepth()
      Returns the maximum depth of the flame graph call tree for the active metric.

    • getMaxDepth

      public int getMaxDepth(MetricType metric)
      Returns the maximum depth of the flame graph call tree for the specified metric.

    • clear

      public void clear()
      Clears aggregated data for all metrics.

    • clear

      public void clear(MetricType metric)
      Clears aggregated data for the specified metric.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable