Gin Agent

The Gin agent runs in-process in the JVM as a Java Agent in order to capture low-impact performance snapshots while your system is running. These performance snapshots are saved in archives and periodically uploaded to the Gin cloud dashboard. 

The Gin agent is minimally invasive and pure Java (no native code) - it uses standard JVM provided mechanisms to sample running threads to capture runtime behaviour.

The Gin agent version 2 supports all JVMs from Java 8 to Java 25.

Installing the Java Agent

Download the latest version of the gin agent from here. 

Extract the agent jar from the downloaded zip file.

Add the gin-agent-2.X.X.jar as a javaagent to the command line used to launch your JVM:

 i.e. -javaagent:<path to gin-agent.jar>[=option1=value1[,optionN=valueN]]

Where the possible options are:

• output - the directory in which to save the created archive files, defaults to the location specified by java.io.tmpdir
• upload - the upload authentication key, if not supplied the profiles will not be uploaded
• sample - the sampling interval in milliseconds, defaults to 100 ms.  The sampling interval controls the frequency with which samples are taken from the process being monitored.  Typical useful values range from 20 ms to 1000 ms.
• quiet - runs the agent in quiet mode which suppresses the logging the profiler normally sends to System.err

Example:

-javaagent:/usr/local/opt/gin/gin-agent-2.x.x.jar=output=/tmp,upload=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,sample=100,quiet

Runs the profiler with a sampling rate of 100 ms.  Archives are saved to /tmp and then uploaded.  The agent is run in quiet mode.

In order to profile virtual threads on Java 21 or later you must also add the following argument to your Java command line:

--add-exports=java.base/jdk.internal.vm=ALL-UNNAMED

License 

The Gin agent is free (as in beer) and released under the Creative Commons Attribution-NoDerivatives 4.0 International License (CC BY-ND). This means you are free to use and share the agent as you wish but that:

• You may not distribute derivative works based upon the agent, and
• No warranties are given