Class HistogramInstructionTracer

java.lang.Object

com.oracle.truffle.api.bytecode.debug.HistogramInstructionTracer

All Implemented Interfaces:

InstructionTracer

public final class HistogramInstructionTracer
extends Object
implements InstructionTracer

Instruction tracer that records per-opcode execution counts and optionally aggregates them into hierarchical histograms by user defined group clauses.

The tracer is optimized for the no-filter, no-group case. In that mode the hot path avoids boundary calls and can be partially evaluated. When grouping or filtering is enabled, a small LRU cache avoids repeated evaluation of the grouping and filtering functions for the same BytecodeNode, current thread, and compilation tier.

Thread safety: increments are performed via atomic counters and are safe under concurrent execution. Histogram creation is a snapshot that can be performed concurrently with counting. For interval semantics, prefer getHistogramAndReset() over mixing getHistogram() with reset().

Basic usage

The example below shows how to attach a HistogramInstructionTracer directly to a generated bytecode root, execute code, then collect and print a histogram snapshot.

var root = MyRootNodeGen.BYTECODE.create(language, BytecodeConfig.DEFAULT, b -> {
    b.beginRoot();
    b.beginReturn();
    b.emitLoadArgument(0);
    b.endReturn();
    b.endRoot();
}).getNode(0);

// Create and attach the histogram tracer to the root.
var tracer = HistogramInstructionTracer.newBuilder().build(MyRootNodeGen.BYTECODE);
root.getRootNodes().addInstructionTracer(tracer);

// Execute your program as usual.
Object result = root.getCallTarget().call(42);

// Take a consistent snapshot and reset counters for the next interval.
var histogram = tracer.getHistogramAndReset();

// Inspect or print the histogram.
long total = histogram.getInstructionsExecuted();
histogram.print(System.out);

// Detach the tracer when done.
root.getRootNodes().removeInstructionTracer(tracer);

Since:

25.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	HistogramInstructionTracer.Builder	Builder for HistogramInstructionTracer.
static interface	HistogramInstructionTracer.GroupClause	A grouping function that maps a BytecodeNode, the current Thread, and the compilation tier to an arbitrary grouping key.
static final class	HistogramInstructionTracer.Histogram	Represents a hierarchical histogram that can group instruction counts by arbitrary attributes.

Nested classes/interfaces inherited from interface InstructionTracer

InstructionTracer.InstructionAccess

Method Summary

Modifier and Type	Method	Description
String	dumpHistogram()	Renders the current histogram snapshot into a string using printHistogram(PrintStream).
BytecodeDescriptor<?,?,?>	getExclusiveBytecodeDescriptor()	Returns the BytecodeDescriptor that this tracer is attached to.
HistogramInstructionTracer.Histogram	getHistogram()	Creates a hierarchical histogram snapshot of the recorded counters without resetting them.
HistogramInstructionTracer.Histogram	getHistogramAndReset()	Creates a hierarchical histogram snapshot of the recorded counters and atomically resets the underlying counters to zero.
static HistogramInstructionTracer.Builder	newBuilder()	Returns a builder for HistogramInstructionTracer that allows configuring a filter and one or more grouping clauses.
void	onInstructionEnter(InstructionTracer.InstructionAccess access, BytecodeNode bytecode, int bytecodeIndex, Frame frame)	Records the execution of an instruction.
void	printHistogram(PrintStream out)	Prints the current histogram snapshot to the given PrintStream.
void	reset()	Resets all counters to zero and discards previously recorded data.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

onInstructionEnter

public void onInstructionEnter(InstructionTracer.InstructionAccess access,
 BytecodeNode bytecode,
 int bytecodeIndex,
 Frame frame)

Records the execution of an instruction. This method is not intended to be called directly, but by the bytecode DSL framework as part of instruction tracing.

Specified by:

onInstructionEnter in interface InstructionTracer

Parameters:

access - accessor to query information about the current instruction, valid only during this call

bytecode - the BytecodeNode currently being interpreted

bytecodeIndex - the bytecode index (BCI) of the instruction to be executed

frame - the current frame for the root being interpreted

Since:

25.1

getExclusiveBytecodeDescriptor

public BytecodeDescriptor<?,?,?> getExclusiveBytecodeDescriptor()

Returns the BytecodeDescriptor that this tracer is attached to.

Specified by:

getExclusiveBytecodeDescriptor in interface InstructionTracer

Returns:

the descriptor used to resolve instruction metadata and opcodes

getHistogram

public HistogramInstructionTracer.Histogram getHistogram()

Creates a hierarchical histogram snapshot of the recorded counters without resetting them.

Use this to inspect cumulative counts. If you need interval semantics, prefer getHistogramAndReset().

Returns:

a HistogramInstructionTracer.Histogram view of the current counters, possibly grouped

Since:

25.1

getHistogramAndReset

public HistogramInstructionTracer.Histogram getHistogramAndReset()

Creates a hierarchical histogram snapshot of the recorded counters and atomically resets the underlying counters to zero.

Use this to obtain interval counts in long running applications. The reset is performed atomically per-counter, increments that occur after the swap will be visible in the next interval.

Returns:

a HistogramInstructionTracer.Histogram view of the counts since the previous reset

Since:

25.1

dumpHistogram

public String dumpHistogram()

Renders the current histogram snapshot into a string using printHistogram(PrintStream).

Returns:

a human readable histogram table as UTF-8 text

Since:

25.1

See Also:

• HistogramInstructionTracer.Histogram.dump()

printHistogram

public void printHistogram(PrintStream out)

Prints the current histogram snapshot to the given PrintStream.

The output is a single table with aligned numeric columns. Groups, if present, are printed as indented pseudo rows followed by their leaves.

Parameters:

out - the stream to print to

Since:

25.1

See Also:

• HistogramInstructionTracer.Histogram.print(PrintStream)

reset

public void reset()

Resets all counters to zero and discards previously recorded data.

Do not mix this with getHistogram() if you need interval correctness, use getHistogramAndReset() instead.

Since:

25.1

newBuilder

public static HistogramInstructionTracer.Builder newBuilder()

Returns a builder for HistogramInstructionTracer that allows configuring a filter and one or more grouping clauses.

Returns:

a new builder instance

Since:

25.1