com.oracle.truffle.tools.profiler

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 instrumentation framework.

The sampler keeps a shadow stack during execution. This shadow stack is sampled at regular intervals, i.e. 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.getThreadToNodesMap().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.Mode Describes the different modes in which the CPU sampler can operate.
static class	CPUSampler.Payload Wrapper for information on how many times an element was seen on the shadow stack.

Method Summary

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.
com.oracle.truffle.api.instrumentation.SourceSectionFilter	getFilter()
long	getPeriod()
Collection<ProfilerNode<CPUSampler.Payload>>	getRootNodes() Merges all the 'per thread' profiles into one set of nodes and returns it.
long	getSampleCount()
int	getStackLimit()
Map<Thread,Collection<ProfilerNode<CPUSampler.Payload>>>	getThreadToNodesMap()
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	setDelaySamplingUntilNonInternalLangInit(boolean delaySamplingUntilNonInternalLangInit) Sets the option to delay sampling until a non-internal language is initialized.
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	setMode(CPUSampler.Mode mode) Sets the mode for the sampler.
void	setPeriod(long samplePeriod) Sets the sampling period i.e.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, 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

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

isCollecting

public boolean isCollecting()

Returns:

whether or not the sampler is currently collecting data.

Since:

0.30

setMode

public void setMode(CPUSampler.Mode mode)

Sets the mode for the sampler.

Parameters:

mode - the new mode for the sampler.

Since:

0.30

setPeriod

public void setPeriod(long samplePeriod)

Sets the sampling period i.e. the time between two samples of the shadow stack are taken.

Parameters:

samplePeriod - the new sampling period.

Since:

0.30

getPeriod

public long getPeriod()

Returns:

the sampling period i.e. the time between two samples of the shadow stack are taken.

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

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 new size of the shadow stack

Since:

0.30

getStackLimit

public int getStackLimit()

Returns:

size of the shadow stack

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

setDelaySamplingUntilNonInternalLangInit

public void setDelaySamplingUntilNonInternalLangInit(boolean delaySamplingUntilNonInternalLangInit)

Sets the option to delay sampling until a non-internal language is initialized. Useful to avoid internal language initialisation code in the samples.

Parameters:

delaySamplingUntilNonInternalLangInit - Enable or disable this option.

Since:

0.31

getFilter

public com.oracle.truffle.api.instrumentation.SourceSectionFilter getFilter()

Returns:

The filter describing which part of the source code to sample

Since:

0.30

getSampleCount

public long getSampleCount()

Returns:

Total number of samples taken during execution

Since:

0.30

hasStackOverflowed

public boolean hasStackOverflowed()

Returns:

was the shadow stack size insufficient for the execution.

Since:

0.30

getRootNodes

public Collection<ProfilerNode<CPUSampler.Payload>> getRootNodes()

Merges all the 'per thread' profiles into one set of nodes and returns it.

Returns:

The roots of the trees representing the profile of the execution.

Since:

0.30

getThreadToNodesMap

public Map<Thread,Collection<ProfilerNode<CPUSampler.Payload>>> getThreadToNodesMap()

Returns:

The roots of the trees representing the profile of the execution per thread.

Since:

19.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. 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.

Since:

19.0