JVMTM Tool Interface

Version 9.0


Heap Monitoring

Heap Monitoring functions:

Set Heap Sampling Rate

jvmtiError
SetHeapSamplingRate(jvmtiEnv* env,
            jint sampling_rate)
Generate a SampledObjectAlloc event when objects are allocated. Each thread keeps a counter of bytes allocated. The event will only be generated when that counter exceeds an average of sampling_rate since the last sample.
Setting sampling_rate to 0 will cause an event to be generated by each allocation supported by the system.
PhaseCallback SafePositionSince
may only be called during the OnLoad or the live phase No 15611
Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this function.
Capability Effect
can_generate_sampled_object_alloc_events Can generate sampled allocation events. If this capability is enabled then the heap sampling method SetHeapSamplingRate can be called and SampledObjectAlloc events can be generated.
Parameters
Name Type Description
sampling_ratejint The sampling rate in bytes. The sampler uses a statistical approach to generate an event, on average, once for every sampling_rate bytes of memory allocated by a given thread.
Passing 0 as a sampling rate generates a sample for every allocation.
Note: The overhead of this feature is directly correlated with the sampling rate. A high sampling rate, such as 1024 bytes, will incur a high overhead. A lower rate, such as 1024KB, will have a much lower overhead. Sampling should only be used with an understanding that it may impact performance.
Errors
This function returns either a universal error or one of the following errors
Error Description
JVMTI_ERROR_MUST_POSSESS_CAPABILITY The environment does not possess the capability can_generate_sampled_object_alloc_events. Use AddCapabilities.
JVMTI_ERROR_ILLEGAL_ARGUMENT sampling_rate is less than zero.


Sampled Object Allocation

void JNICALL
SampledObjectAlloc(jvmtiEnv *jvmti_env,
            JNIEnv* jni_env,
            jthread thread,
            jobject object,
            jclass object_klass,
            jlong size)
Sent when an allocated object is sampled. By default, the sampling rate is a geometric variable with a 512KB mean. Each thread tracks how many bytes it has allocated since it sent the last event. When the number of bytes exceeds the sampling rate, it will send another event. This implies that, on average, one object will be sampled every time a thread has allocated 512KB bytes since the last sample.
Note that this is a geometric variable: it will not sample every 512KB precisely. The goal of this is to ensure high quality sampling even if allocation is happening in a fixed pattern (i.e., the same set of objects are being allocated every 512KB).
If another sampling rate is required, the user can call SetHeapSamplingRate with a strictly positive integer value, representing the new sampling rate.
This event is sent once the sampled allocation has been performed. It provides the object, stack trace of the allocation, the thread allocating, the size of allocation, and the object's class.
A typical use case of this system is to determine where heap allocations originate. In conjunction with weak references and the function GetStackTrace, a user can track which objects were allocated from which stack trace, and which are still live during the execution of the program.
PhaseEvent TypeNumberEnablingSince
sent only during the live phase JVMTI_EVENT_SAMPLED_OBJECT_ALLOC86SetEventNotificationMode(JVMTI_ENABLE, JVMTI_EVENT_SAMPLED_OBJECT_ALLOC, NULL)11
Capabilities
Optional Functionality: might not be implemented for all virtual machines. The following capability (as returned by GetCapabilities) must be true to use this event.
Capability Effect
can_generate_sampled_object_alloc_events Can generate sampled allocation events. If this capability is enabled then the heap sampling method SetHeapSamplingRate can be called and SampledObjectAlloc events can be generated.
Parameters
Name Type Description
jni_env JNIEnv * The JNI environment of the event (current) thread.
threadjthread Thread allocating the object.
objectjobject JNI local reference to the object that was allocated.
object_klassjclass JNI local reference to the class of the object
sizejlong Size of the object (in bytes). See GetObjectSize.