How to Run

Once you've installed the client into a directory you need to run agent on the JVM that you want to profile. You can then either use the Gui Client or the Commandline Client in order to view the output of the profiler.

The Agent

To run the jvmti agent:

java -agentpath:/path/to/location/liblagent.so=interval=7,logPath=/path/to/output/log.hpl <normal-java-commandline>

Note: "agentpath" does not equal "agentlib"

Additional options:

Option	Type	Notes	Default
intervalMin	int	Wait at least this many milliseconds between samples	?
intervalMax	int	Wait no longer than this many milliseconds between samples	?
interval	int	Sets both intervalMin and intervalMax to the same value with one parameter. Consider a prime number to avoid over-sampling periodically-running methods (e.g., that run every 10 microseconds)	?
logPath	string	A file path indicating where the collected data should be written	?
start	boolean	"0": Do not profile on initialization (wait for dynamic call to start profiling). "1": Begin profiling as soon as possible.	1
host	string	local hostname or IP address to bind to for the "remote control" interface	?
port	int	local TCP port number to listen on for the "remote control" interface	?
maxFrames	int	Max number of stack frames to capture per trace	?

Remote control

Note: Remote control interface is not available on macOS and FreeBSD

A TCP socket interface has been added to the agent that enables you to start or stop profiling on demand from outside of the JVM where the agent is running, as well as to query the profiling status. To enable this feature, you must specify both the host and port agent options.

You can then connect to the endpoint using a TCP client like telnet or netcat to issue commands. The available commands are:

• start
• stop
• status (which also prints out the log file path)
• get <ParamName>
• set <ParamName> <ParamValue1> ... <ParamValueN>

<ParamName> is any of intervalMin, intervalMax, interval (requires 2 arguments for set), maxFrames or logPath.

For example: echo status | nc localhost 18080 (assuming host option was set to localhost and port was set to 18080)

Note: because there is no authentication for this interface you should probably either specify a loopback address (e.g. localhost or 127.0.0.1) or specify another address that is not publicly accessible.

The Gui Client

To start the Gui you use:

./gui

On Linux you will need to install javafx first. It comes bundled with Oracle Java, but not with OpenJDK. On Debian/Ubuntu systems install the 'openjfx' package.

The Commandline Client

See How to use the Commandline Client