Constructing BugJail Agent option manually

To capture the execution of a program to BugJail, the only thing you need to do is start Java Virtual Machine with one additional option.

This article describes how to manually construct the BugJail Agent option string, allowing the use of all options and advanced configuration.

Alternatively, you can construct the option string using an included helper tool, called the Capturing Assistant (easy user-interface, but supports only the two most common configuration options currently)

The format of the JVM option string:

-javaagent:<agent_path>=<agent_options>

Step 1: Add -javaagent and BugJail Agent path

The BugJail Agent is located under the home directory of currently logged in user, in sub-directory ".BugJail", with the filename of "agent.jar"

Windows

The option string with BugJail Agent path, given via environment variables:

-javaagent:$HOMEDRIVE\$HOMEPATH\.BugJail\agent.jar

Note that the environment variables work in PowerShell, command prompt, and in about half of other situations, but if they don't, just replace the variables with the literal path to your home directory. On Windows, the literal path is usually shorter anyway.

Example - The option string with BugJail Agent path, given using a literal path.

-javaagent:C:\Users\Henri\.BugJail\agent.jar

Mac and Linux

The option string with BugJail Agent path, given via environment variables:

-javaagent:$HOME/.BugJail/agent.jar

Note that the $HOME environment variable works in shells and in about half of other situations, but if it doesn't, just replace the $HOME with the literal path to your home directory.

Note that in most situations the home directory tilde '~' won't work, so don't bother with that.

Example - The option string with BugJail Agent path, given using a literal path:

-javaagent:/home/henri/.BugJail/agent.jar

Step 2: Add BugJail Agent options

This is where things get conceptually bit tricky. From the JVM's point of view, the whole option string that we are constructing is just one option. To configure the BugJail Agent, we are effectively passing in BugJail level options as the last part of the JVM level option!

The options to BugJail Agent must be in practice a single string without white space, given after the agent path and equals sign ('='). Because whitespace is not allowed, the BugJail Agent options are instead delimited with a double dash '--'.

The format of the option string with multiple BugJail Agent options:

-javaagent:<agent_path>=--<agent_option_1>--<agent_option_n>

Furthermore, many BugJail Agent options accept a value or a list of values. The values are given after colon ':'. If a list of values is given, then the values of the list are delimited with a comma ',' or semicolon ';'.

The format of the option string with multiple BugJail Agent options, and with values to last option:

-javaagent:<agent_path>=--<agent_option_1>--<agent_option_n>:<value_1>,<value_n>

Example - The most common option string:

-javaagent:/home/henri/.BugJail/agent.jar=--snapshot:/home/henri/projects/stuff--primary:io.stuff**

Example - An option string with one option that has a list of values:

-javaagent:/home/henri/.BugJail/agent.jar=--primary:io.stuff**,org.stuff**,com.stuff**

See article BugJail Agent options reference for details of all possible capturing options.

See section Enabling BugJail capturing for instructions on how to use the constructed option string to capture program execution to BugJail.