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.

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

Installing the Java Agent

Just add the gin-agent-1.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
• 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.
• collect - the collection interval in minutes, defaults to 5 minutes. The collection interval is the time period over which samples are aggregated to create each individual profile in the archive.
• batch - the number of profiles to gather in each created archive, defaults to 12 (which represents an hour of profiles at the default collection interval of 5 minutes)
• port - the port to start listening for command interface connections, if not supplied the command interface is not started and the agent will always start profiling immediately
• start - if present the profiler will start profiling immediately even when a command interface is started, by default the agent will not start profiling immediately if the command interface is started
• upload - the upload authentication key, if not supplied the profiles will not be uploaded
• url - the upload url, defaults to …
• 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-1.x.x.jar=output=/tmp,sample=250,collect=30,batch=48,quiet,port=12345,start

Runs the profiler with a sampling rate of 250 ms, creating a new profile every 30 minutes and batching 48 profiles into each archive.
Archives are saved to /tmp. The agent is run in quiet mode. The command interface is started, listening on port 12345. The agent will begin profiling immediately.

Command Interface

For long running applications it can be useful to manually start, stop and reconfigure the profiler without having to restart the entire java application. Therefore the Gin agent supports a command interface which can optionally be started by providing a port number for the command interface to listen on.

Once the command interface is started an interactive command interface session can be started by connecting to the command interface port with a telnet client. Once connected you will see a command prompt where you can issue commands to the Gin agent.

Commands

Supported commands are:

• help - display help text
• exit - to exit the command interface
• start - start the profiler
• stop - stop the profiler
• restart - stop and then restart the profiler
• status - display the current status of the profiler
• sample=value - set the sampling interval in milliseconds, sensible values range from 20 ms to 1000 ms
• collect=value - set the collection interval in minutes, typical values range from 5 minutes to 60 minutes
• batch=value - set the number of profiles to store in a single archive
• output=directory path - set the directory to write the archives to, an empty value uses the current directory