BugJail Agent options reference

This article is the reference for BugJail Agent options.

See article Constructing BugJail Agent option string manually for instructions on how to combine the options described in this article to a single '-javaagent' option string.

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

Legend

The option values in this article use the following syntax:

Options 

Source Capturing Options

--snapshotSourcePath:<source_project_root>

Path to the root of the source project.

The path can be absolute, or relative to the working directory from where you start JVM.

Tip: If you start JVM from IDE (with default settings) then the working directory will usually be the root of your project, and you can just give relative path of '.' (single dot).

If not specified, then source code is not captured, and the source-level debugging feature will be unavailable (but runtime capturing based features, such as Call Tree and Value panels continue to work).

Modules, source roots and directories under the given path will be scanned recursively for source files. This means that you can specify a path to the root of the project (e.g. /home/me/projects/myproject) instead of path to source root (e.g. /home/me/projects/myproject/somemodule/src/main/java).

After scanning, BugJail takes a differential snapshot copy of all found source files. This enables you to later debug against the exact source code revisions at the time of capturing, instead of the current source code revisions at the time of debugging.

--project:<project_name>

Name of the source project.

If not specified, then the name is computed from the value of the --snapshotSourcePath option by replacing special characters with underscores.

This option is used for differential source code capture. When you start capturing with BugJail Agent, it first checks if source code has been captured previously for the same <project_name>. If it has, then only the delta is captured.

This option has two uses:

1. If you relocate a project to a different directory, then the automatically calculated project name also changes, thus breaking the differential source capturing and causing one full source capture, wasting some disk space.
2. If you constantly switch between branches, then the differential source capture may be large after each branch switch, and it may be more disk-space efficient to use a separate <project_name> for each branch (i.e. two full source snapshots, but then very small differential source captures).

Runtime Capturing Options

--primaryClassNames:<class_pattern_1>[,class_pattern_n...]

Class name patterns that you are primarily interested in capturing.

Tip: this is usually the code you / your company are developing and can be easily given as top-level package name followed by '**' (double asterisk), e.g. "com.mycompany**".

If not specified, then everything will be marked as 'primary' by default (except JDK classes and a few problematic special cases).

The 'primary' classes will be always fully captured, e.g.. every method entry and exit, every field write to instances of the class etc. 

The remaining classes will be marked as 'secondary', which means that method calls from 'primary' to 'secondary' classes are captured, but internal calls within or between "secondary" classes are not.

Note: If this option is not specified, then almost everything will be fully captured, including the internals of application servers and every library dependency, often resulting in billions of captured events and slow performance.

--secondaryClassNames:<class_pattern_1>[,class_pattern_n...]

Class name patterns that you are interested in capturing only when they are used by or visible from "primary" classes.

If not specified AND --primaryClassNames IS specified, then everything else except the 'primary' classes becomes 'secondary' by default.

If not specified AND --primaryClassNames IS NOT specified, then this defaults to: "java**", "javax**", "javafx**", "scala**", "sun**", "com.sun**", "jdk**" and everything else becoes 'primary'.

The 'secondary' classes will be captured only when they interact with 'primary' classes: method calls from 'primary' to 'secondary' classes are captured, but internal calls within or between 'secondary' classes are not.

--ignoreClassNames:<class_pattern_1>[,class_pattern_n...]

Class name patterns that should be always ignored.

If not specified, this defaults to a couple of special cases used by BugJail: "java.nio.HeapByteBuffer", "java.nio.DirectByteBuffer", "sun.misc.Cleaner", "java.util.UUID", plus BugJail itself (i.e. preventing BugJail from capturing BugJail).

The 'ignored' classes are never captured, even when they interact with 'primary' classes: method calls to 'ignored' classes do not show in the Call Tree -panel, and instances of 'ignored' classes that are passed as an argument to a captured class show in the UI as red <IGNORED>.

The 'ignored' classes, however, are transformed (instrumented). Even if a class itself is 'ignored', the things that it does to OTHER classes, such as field writes, thrown exceptions and started threads ARE captured!

--notransformClassNames:<class_pattern_1>[,class_pattern_n...]

Class name patterns that should not be transformed (instrumented).

If not specified, this defaults to a list of special cases that fail to transform even if attempted, or that cause serious explosions: "java.lang.Object", "java.lang.Class", "java.lang.Enum", "java.lang.String", "java.lang.Thread", "java.lang.Throwable", "sun.misc.Unsafe", "sun.reflect**", "java.io.PrintWriter", "java.io.StringWriter".

The 'notransform' classes are captured on a best-effort basis: method calls to 'notransform' classes are visible in Call Tree -panel and instances of 'notransform' classes that are passed as an argument to a captured class show correctly in Call Tree -pael, but field and array element values in Value -panel are mostly broken.

--retransformClassNames:<class_pattern_1>[,class_pattern_n...]

Class name patterns of classes that were loaded by JVM before BugJail Agent had the change to enable class file transformations and which should be transformed as soon as possible.

If not specified, this defaults to all generally interesting classes that get loaded early (e.g. HashMap).

--nanosecondPrecision:[true|false|yes|no]

Toggle between nanosecond and millisecond capturing precision.

If not specified, or if specified with a value of "false" or "no", then millisecond precision is used.

If specified without a value, or with a value of "true" or "yes", then nanosecond precision is used.