Skip to main content
Jump to: navigation, search

JVMTI Profiler Hack Guide


TPTP profiling contains two basic frameworks. One of them is Martini Framework, another one is Data Collection Framework. Martini Framework is used to get profiling data from runtime Virtual Machine (such as JVM). The collected profiling data will be sent to TPTP Client by Data Collection Framework.

Martini Framework is composed of three parts: The first part is Martini Infrastructure, which includes Profiling Kernel componet, Event Manager, Instrumentation Manager, Martini Profiling Interface, External Control Agent etc. The second part is Profilers, which currently contains several Java Profilers (Call Graph Profiler, Heap Profiler, Thread Profiler and ProbekitAgent). The third part is External Module (JPIAgent is currently implemented for Java profiling).

Data Collection Framework is composed of Data Collection Client (such as Eclipse workbench), Agent Controller and Agent(An application that exposes its services throught the agent controller). More information about Data Collection Framework, please refer Eclipse Help "Working with the Agent Controller". 

In current TPTP, Martini ACCollector is implemented as an agent of Data Collection Framework. The ACCollector interacts with Martini JPIAgent. The collected profiling data will be sent to Data Collection Client by this chain:

VM ==> Martini Framework (Martini Infrastructure => Profilers => JPIAgent) ==> DataCollection Framework (ACCollector => Agent Controller => TPTP Data Collection Client).

We will describe Martini Framework design briefly. As we mentioned above, three parts (Martini Infrastructure, Profilers and External Module) will be focused on.

Martini Framework Infrastructure

Architecture Overview

Martini Runtime is built on top of JVM. The JVM interface component is implemented as the interface between JVM and Martini Runtime by calling JVMTI/JVMPI. It’s responsible for data conversion and interface conversion and also provides rich functionality to inspect JVM state and control the execution of applications such as iterating heap. JVMTI event will be converted to internal event type and passed to Event Manger.

Event Manger component is responsible for dispatching event. Events can be sent from External components (EC, profilers) and internal components.

Martini Framework is instrumentation based profiling framework. It can record method enter/exit event, thread event and heap allocation event. Instead of generating event using JVMTI/JVMPI, Martini framework using bytecode instrumentation technology to generate execution, thread and heap event. Instrumentation Manger is responsible for managing the instrumentation process and it calls instrumentation adaptors to instrument bytecode with specific functionality.

Components of Martini Framework Infrastructure includes Profiling Module, Instrumentation Engine, Instrumentation Adaptors, Profiling Boot Loader and Martini OS Abstraction. For current Java profiling, there implementation components are as below:

  • Profiling Module ==== JPI
  • Instrumentation Engine  ==== JIE
  • Instrumentation Adaptors ==== CGAdaptor, HeapAdaptor and ThreadAdaptor
  • Profiling Boot Loader  ==== JPIBootLoader
  • Martini OS Abstraction ==== MartiniOSA

Martini Profiling Module

Profiling Module is the key component in Martini Framework. It provides with Martini Profiling Interface (MPI) for profilers and External Control Interface for External Module. 

Martini Profiling Interface

The martini profiling interface is an interface for managed runtime profiling tools. It’s defined to suit a wide-range of virtual machines, such as Java Virtual Machine. Its main goal is to allow using the same tool with different managed-runtime environments.

MPI is a declarative, event-based interface, offering a variety of well-defined events and data request operations. Some of the events may be optionally restricted to specific selective criteria, such as specific classes rather than all, reducing the overhead and the amount of data generated.

External Control Interface

The Martini External Control Interface is designed to allow Profiler front-ends to interact with their MPI back-end modules by sending "control" messages that will be dispatched to the MPI back-end modules as MPI events. To interact with MPI clients, a tool implements an "External Control" module which is loaded into the virtual machine process together with the MPI client it needs to control. This External Control module serves as a bridge between the tool's front-end process and the MPI client back-end and enables the front-end to send certain MPI events to the MPI client.

Instrumentation Engine

It use instrumentation adaptor interface to complete instrumentation tasks such as Java Byte Code Instrumentation. It also provides a Instrumentation Engine interface for profilers.

Instrumentation Adaptors

Instrumentation Adaptors provide a declarative interface for obtaining notifications by using instrumentation. There are three adptors in Martini. They are CGAdaptor (Call Graph Adaptor), HeapAdaptor and ThreadAdaptor.

Profiling Boot Loader

Boot Loader is used to load libraries needed when profiling. Actually it is the implementation of VM Agent interface. For example, JPI boot loader implement the JVMTI interface Agent_OnLoad. 

*Note: There are several kinds of Agents in current TPTP for Java profiling:

  • JVMTI agent implements JVMTI interface to interact with JVM. As we mentioned above, JPIBootLoader is used as JVMTI agent for Java in TPTP.
  • Data Collection Agent is used in Data Collection Framework to interact with Agent Controller. So "Agent" in "Agent Contoller" means the component in Data Collection Framework.
  • JPIAgent is an agent interacting with Martini profiling interface. It is an external module implementation for Java profiling.

Martini OS Abstraction

Since TPTP runs on different operating systems. The component Martini OS Abstraction (MartiniOSA) provides an abstraction layer between OS-related functions and profiling components. These functions include file management and thread sychronization etc.


Profilers are used to do concrete profiling work. For example, Call Graph profiler is used for execution time and call tree analysis. Profilers can be paused when profiling. They are also able to attached or detached. There are four kinds of Java profilers in TPTP: 

  • CG (Call Graph) Profiler
  • Heap Profiler
  • Thread Profiler
  • ProbekitAgent

External Module

External Module acts as a "bridge" between the front-end and the Martini runtime. JPIAgent is an External Module implementation for Java profiling. It is loaded by Martini into the JVM address space. It uses predefined callback functions to generate Martini External Control commands, which are dispatched as MPI events to interested profilers.

A data collection agent is also implemented with JPIAgent. It is ACCollector that interacts with Agent Controller.

Martini Framework Components Summary

All martini Framework related components are included in tptp/platform/org.eclipe.tptp.platform.jvmti.runtime. Here is a summary of 13 components in current TPTP JVMTI runtime mentioned:

  • JPI
  • JIE
  • CGAdaptor
  • HeapAdaptor
  • ThreadAdaptor
  • JPIBootLoader
  • MartiniOSA
  • CGProf
  • HeapProf
  • ThreadProf
  • ProbekitAgent
  • JPIAgent
  • ACCollector

Back to TPTP wiki page

Back to the top