Class CPUSampler

java.lang.Object
com.oracle.truffle.tools.profiler.CPUSampler
All Implemented Interfaces:
Closeable, AutoCloseable
public final class CPUSampler extends Object implements Closeable
Implementation of a sampling based profiler for Truffle languages built on top of the Truffle safepoints and iterateFrames().

The sampler samples the stack of each thread at regular intervals by using Truffle safepoints. The state of the stack is copied and saved into trees of nodes, which represent the profile of the execution.

Usage example: 

Context context = Context.create();

CPUSampler sampler = CPUSampler.find(context.getEngine());
sampler.setCollecting(true);
context.eval("...", "...");
sampler.setCollecting(false);
sampler.close();
// Read information about the roots of the tree per thread.
for (Collection<ProfilerNode<CPUSampler.Payload>> nodes
        : sampler.getDataList().iterator().next().threadData.values()) {
    for (ProfilerNode<CPUSampler.Payload> node : nodes) {
        final String rootName = node.getRootName();
        final int selfHitCount = node.getPayload().getSelfHitCount();
        // ...
    }
}
Since:
0.30

  • Method Details

    • find

      public static CPUSampler find(org.graalvm.polyglot.Engine engine)
      Finds CPUSampler associated with given engine.
      Since:
      19.0

    • isCollecting

      public boolean isCollecting()
      Returns:
      whether or not the sampler is currently collecting data.
      Since:
      0.30

    • setCollecting

      public void setCollecting(boolean collecting)
      Controls whether the sampler is collecting data or not.
      Parameters:
      collecting - the new state of the sampler.
      Since:
      0.30

    • getPeriod

      public long getPeriod()
      Returns:
      the sampling period i.e. the time between two samples of the stack are taken, in milliseconds.
      Since:
      0.30

    • setPeriod

      public void setPeriod(long samplePeriod)
      Sets the sampling period i.e. the time between two samples of the stack are taken, in milliseconds.
      Parameters:
      samplePeriod - the new sampling period.
      Since:
      0.30

    • setDelay

      public void setDelay(long delay)
      Sets the delay period i.e. the time that is allowed to pass between when the first sample would have been taken and when the sampler actually starts taking samples.
      Parameters:
      delay - the delay period.
      Since:
      0.30

    • getDelay

      public long getDelay()
      Gets the delay period.
      Returns:
      the delay period.
      Since:
      25.1
      See Also:

    • getStackLimit

      public int getStackLimit()
      Returns:
      the maximum amount of stack frames that are sampled.
      Since:
      0.30

    • setStackLimit

      public void setStackLimit(int stackLimit)
      Sets the maximum amount of stack frames that are sampled. Whether or not the stack grew more than the provided size during execution can be checked with hasStackOverflowed()
      Parameters:
      stackLimit - the maximum amount of stack frames that are sampled
      Since:
      0.30

    • setSampleContextInitialization

      public void setSampleContextInitialization(boolean enabled)
      Enables or disables the sampling of the time spent during context initialization. If true code executed during context initialization is included in the general profile instead of grouping it into a single entry by default. If false a single entry will be created that contains all time spent in initialization. This can be useful to avoid polluting the general application profile with sampled stack frames that only run during initialization.
      Since:
      21.3

    • getFilter

      public com.oracle.truffle.api.instrumentation.SourceSectionFilter getFilter()
      Returns:
      The filter describing which part of the source code to sample
      Since:
      0.30

    • setFilter

      public void setFilter(com.oracle.truffle.api.instrumentation.SourceSectionFilter filter)
      Sets the filter for the sampler. The sampler will only observe parts of the executed source code that is specified by the filter.
      Parameters:
      filter - The new filter describing which part of the source code to sample
      Since:
      0.30

    • hasStackOverflowed

      public boolean hasStackOverflowed()
      Returns:
      was the the maximum amount of stack frames that are sampled insufficient for the execution.
      Since:
      0.30

    • getData

      @Deprecated public Map<com.oracle.truffle.api.TruffleContext, CPUSamplerData> getData()
      Deprecated.
      in 24.1.0. Contexts are no longer stored permanently. Use getDataList() to get all sampler data.
      Get per-context profiling data. The profiling data is an unmodifiable map from TruffleContext to CPUSamplerData. It is collected based on the configuration of the CPUSampler (e.g. setFilter(SourceSectionFilter), setPeriod(long), etc.) and collecting can be controlled by the setCollecting(boolean). The collected data can be cleared from the cpusampler using clearData()
      Returns:
      a map from TruffleContext to CPUSamplerData. The contexts that were already collected are not in the returned map even though data was collected for them. All collected data can be obtained using getDataList().
      Since:
      21.3.0

    • getDataList

      public List<CPUSamplerData> getDataList()
      Get per-context profiling data. Context objects are not stored, the profiling data is an unmodifiable list of CPUSamplerData. It is collected based on the configuration of the CPUSampler (e.g. setFilter(SourceSectionFilter), setPeriod(long), etc.) and collecting can be controlled by the setCollecting(boolean). The collected data can be cleared from the cpusampler using clearData()
      Returns:
      a list of CPUSamplerData where each element corresponds to one context.
      Since:
      24.1.0

    • clearData

      public void clearData()
      Erases all the data gathered by the sampler and resets the sample count to 0.
      Since:
      0.30

    • hasData

      public boolean hasData()
      Returns:
      whether or not the sampler has collected any data so far.
      Since:
      0.30

    • close

      public void close()
      Closes the sampler for further use, deleting all the gathered data.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Since:
      0.30

    • isGatherSelfHitTimes

      public boolean isGatherSelfHitTimes()
      Returns:
      Whether or not timestamp information for the element at the top of the stack for each sample is gathered
      Since:
      0.30

    • setGatherSelfHitTimes

      public void setGatherSelfHitTimes(boolean gatherSelfHitTimes)
      Sets whether or not to gather timestamp information for the element at the top of the stack for each sample.
      Parameters:
      gatherSelfHitTimes - new value for whether or not to gather timestamps
      Since:
      0.30

    • isGatherAsyncStackTrace

      public boolean isGatherAsyncStackTrace()
      Returns:
      Whether or not async stack trace information for each sample is gathered.
      Since:
      24.1

    • setGatherAsyncStackTrace

      public void setGatherAsyncStackTrace(boolean asyncStackTrace)
      Sets whether or not to try to gather async stack trace information for each sample.
      Parameters:
      asyncStackTrace - new value for whether or not to include async stack trace elements
      Since:
      24.1

    • takeSample

      public Map<Thread, List<StackTraceEntry>> takeSample()
      Sample all threads and gather their current stack trace entries with a default time out. Short hand for: takeSample(this.getPeriod(), TimeUnit.MILLISECONDS).
      Since:
      19.0
      See Also:

    • takeSample

      public Map<Thread, List<StackTraceEntry>> takeSample(long timeout, TimeUnit timeoutUnit)
      Sample all threads and gather their current stack trace entries. The returned map and lists are unmodifiable and represent atomic snapshots of the stack at the time when this method was invoked. Only active threads are sampled. A thread is active if it has at least one entry on the stack. The sampling is initialized if this method is invoked for the first time or reinitialized if the configuration changes.

      If the given timeout is exceeded the sampling will be stopped. If a timeout occurs it may lead to an incomplete or empty result. For example, if only one thread times out the result of other threads may still be reported.

      Since:
      22.0

    • addProcessSampleListener

      public void addProcessSampleListener(CPUSampler.ProcessSampleListener listener)
      Registers a listener that is notified about the processing of sampling results.
      Parameters:
      listener - the listener to register; must not be null.
      Since:
      25.1