Class CPUSampler
java.lang.Object
com.oracle.truffle.tools.profiler.CPUSampler
- All Implemented Interfaces:
Closeable
,AutoCloseable
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
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
Wrapper for information on how many times an element was seen on the stack. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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) FindsCPUSampler
associated with given engine.Map
<com.oracle.truffle.api.TruffleContext, CPUSamplerData> getData()
Deprecated.in 24.1.0.Get per-context profiling data.com.oracle.truffle.api.instrumentation.SourceSectionFilter
long
int
boolean
hasData()
boolean
boolean
boolean
boolean
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 thefilter
for the sampler.void
setGatherAsyncStackTrace
(boolean asyncStackTrace) Sets whether or not to try to gather async stack trace information for each sample.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.Sample all threads and gather their current stack trace entries with a default time out.takeSample
(long timeout, TimeUnit timeoutUnit) Sample all threads and gather their current stack trace entries.
-
Method Details
-
find
FindsCPUSampler
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 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. Iftrue
code executed during context initialization is included in the general profile instead of grouping it into a single entry by default. Iffalse
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 thefilter
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.in 24.1.0. Contexts are no longer stored permanently. UsegetDataList()
to get all sampler data.Get per-context profiling data. The profiling data is an unmodifiable map fromTruffleContext
toCPUSamplerData
. It is collected based on the configuration of theCPUSampler
(e.g.setFilter(SourceSectionFilter)
,setPeriod(long)
, etc.) and collecting can be controlled by thesetCollecting(boolean)
. The collected data can be cleared from the cpusampler usingclearData()
- Returns:
- a map from
TruffleContext
toCPUSamplerData
. 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 usinggetDataList()
. - Since:
- 21.3.0
-
getDataList
Get per-context profiling data. Context objects are not stored, the profiling data is an unmodifiable list ofCPUSamplerData
. It is collected based on the configuration of theCPUSampler
(e.g.setFilter(SourceSectionFilter)
,setPeriod(long)
, etc.) and collecting can be controlled by thesetCollecting(boolean)
. The collected data can be cleared from the cpusampler usingclearData()
- 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 interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- 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
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
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
-