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.getData().values().iterator().next().threadData.values()) {
    for (ProfilerNode<CPUSampler.Payload> node : nodes) {
        final String rootName = node.getRootName();
        final int selfHitCount = node.getPayload().getSelfHitCount();
        // ...
    }
}

Since:: 0.30

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class CPUSampler.Payload
Wrapper for information on how many times an element was seen on the stack.

Nested Classes
Modifier and Type	Class and Description
`static class`	`CPUSampler.Payload` Wrapper for information on how many times an element was seen on the stack.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearData()` Erases all the data gathered by the sampler and resets the sample count to 0.
`void`	`close()` Closes the sampler for further use, deleting all the gathered data.
`static CPUSampler`	`find(org.graalvm.polyglot.Engine engine)` Finds `CPUSampler` associated with given engine.
`Map<com.oracle.truffle.api.TruffleContext,CPUSamplerData>`	`getData()` Get per-context profiling data.
`com.oracle.truffle.api.instrumentation.SourceSectionFilter`	`getFilter()`
`long`	`getPeriod()`
`int`	`getStackLimit()`
`boolean`	`hasData()`
`boolean`	`hasStackOverflowed()`
`boolean`	`isCollecting()`
`boolean`	`isGatherSelfHitTimes()`
`void`	`setCollecting(boolean collecting)` Controls whether the sampler is collecting data or not.
`void`	`setDelay(long delay)` Sets the delay period i.e.
`void`	`setFilter(com.oracle.truffle.api.instrumentation.SourceSectionFilter filter)` Sets the `filter` for the sampler.
`void`	`setGatherSelfHitTimes(boolean gatherSelfHitTimes)` Sets whether or not to gather timestamp information for the element at the top of the stack for each sample.
`void`	`setPeriod(long samplePeriod)` Sets the sampling period i.e.
`void`	`setSampleContextInitialization(boolean enabled)` Enables or disables the sampling of the time spent during context initialization.
`void`	`setStackLimit(int stackLimit)` Sets the maximum amount of stack frames that are sampled.
`Map<Thread,List<StackTraceEntry>>`	`takeSample()` Sample all threads and gather their current stack trace entries with a default time out.
`Map<Thread,List<StackTraceEntry>>`	`takeSample(long timeout, TimeUnit timeoutUnit)` Sample all threads and gather their current stack trace entries.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - 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
  - 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 CPUSampler.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
```
public Map<com.oracle.truffle.api.TruffleContext,CPUSamplerData> getData()
```
    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. CPUSampler.setFilter(SourceSectionFilter), CPUSampler.setPeriod(long), etc.) and collecting can be controlled by the CPUSampler.setCollecting(boolean). The collected data can be cleared from the cpusampler using CPUSampler.clearData()
    
    Returns:
    
    a map from TruffleContext to CPUSamplerData.
    
    Since:
    
    21.3.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 Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    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
  - 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:
    
    CPUSampler.takeSample(long, TimeUnit)
  - 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

Class CPUSampler

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

find

isCollecting

setCollecting

getPeriod

setPeriod

setDelay

getStackLimit

setStackLimit

setSampleContextInitialization

getFilter

setFilter

hasStackOverflowed

getData

clearData

hasData

close

isGatherSelfHitTimes

setGatherSelfHitTimes

takeSample

takeSample