Home Features Download Plugins Documentation | Issues Feedback Sources

Sources Support

Starting from VisualVM 2.1, navigating to the source code using the Go to Source action is supported in various views like Sampler/Profiler and Heap Viewer, using a defined external sources viewer and provided source roots.

Opening Java classes and methods is fully supported, with some exceptions for specific language constructs like lambdas or anonymous classes. There's an experimental support for displaying methods/functions of GraalVM guest languages in Polyglot Sampler | CPU.

For the previous VisualVM releases down to VisualVM 2.0.4, the VisualVM-GoToSource plugin is available. It can be installed using Tools | Plugins, Available Plugins tab.

Features

The following features are available since VisualVM 2.1:

  • Go to Source action in context menu of Java views: Sampler/Profiler live results & snapshots, Heap Viewer, JFR Sampler
  • Experimental: Go to Source action in context menu of Polyglot Sampler | CPU (tested for JavaScript, Ruby, R, Python)
  • User-provided source roots - directories and archives, customizable subfolders, customizable encoding
  • User-defined sources viewer - registered in the OS or custom command to launch an external editor/IDE
  • Command line parameters to configure the source roots and sources viewer externally

Limitations

These are the known limitations of the current implementation:

  • Java:
    • Go to Source action not available for stack traces / thread dumps
    • Go to Source not working for lambdas
    • Go to Source not working for anonymous classes used as parameters
    • Go to Source not working for anonymous classes extending Enums (ENUM_ITEM {})
    • Go to Source not resolving methods by their signature (opens first occurrence by name)
    • Go to Source not working for non-public toplevel classes (java.awt.FocusManager in java.awt.Window)
    • Go to Source not working for elements with unicode codes in name (class About vs. class A\u0062out)
  • GraalVM guest languages:
    • Go to Source not available in Polyglot Sampler | Memory and Heap Viewer - guest language view
    • Go to Source only working for methods/functions displaying the source file and line number

Configuration

The sources support must be configured to provide the desired functionality. Open Tools | Options (VisualVM | Preferences... on macOS) and switch to the Sources section to define location of the source code and the tool to display the sources.

Configuring Source Roots

  1. Use the "+" button to add new source roots
  2. Select single or multiple directories or archives (.zip, .jar) containing the sources
  3. Specify sources location within the source roots:
    • Selected root(s): selected directories immediately contain the sources
    • Subdirectories: list of (common) subdirectories of the selected directories containing the sources
    • Custom subpaths: manually defined subpaths relative to the selected directories, separated by the path separator appropriate for the host OS - enter *modules* to search the selected directories for modular sources (JDK 9+)
    • Sources encoding can be optionally customized for the defined source roots if needed

Configuring Source Viewer

  • Registered Viewer option opens sources using the tool registered in the host OS as the default viewer or editor for the source file type. Opening sources on a concrete line is not supported.
  • External Viewer option invokes the provided command to open the source code. Use the "▼" button to select one of the templates defined for the most popular IDEs and text editors, or to customize the command by inserting available parameters. Use the "..." button to select filesystem path to the editor/IDE binary.

Command Line API

The following command line parameters are available to define the source roots and viewer externally:

  • --source-roots parameter defines the source roots to be searched for the sources by VisualVM. Individual source roots are separated by the path separator appropriate for the host OS.

    By default, source roots are treated as immediately containing the sources and using the UTF-8 encoding. Each source root entry can be customized to define subfolders containing the sources and/or a non-default encoding: source_root[subpaths=subpath1:subpath2][encoding=encoding_name]

    Example:
    Windows: --source-roots="C:\sources\root1;c:\sources\root2[subpaths=src:test\src]"
    Linux/Mac: --source-roots="/home/user/src/root1[encoding=UTF-16]:/home/user/src/root2"

  • --source-viewer parameter defines the command to be executed when the Go To Source action is invoked in VisualVM.

    Example:
    Windows: --source-viewer="C:\NetBeans\bin\netbeans {file}:{line}"
    Linux/Mac: --source-viewer="/usr/bin/gedit +{line} {file}"
  • --source-config parameter (preferred) allows to define the --source-roots and --source-viewer parameters in a single step using a configuration file. The file can be created using the Properties.store(Writer, String) method. The Writer instance must be configured to use the UTF-8 encoding. The Properties instance contains "source-roots" and/or "source-viewer" String keys with String values similar to the respective parameter values.

    Example:
    Windows: --source-config="C:\Temp\source-config.properties"
    Linux/Mac: --source-config="/tmp/source-config.properties"

The --source-roots and --source-viewer parameters can be used either individually or both at the same time. The --source-config parameter must be used exclusively without the other two parameters.

To clear the settings defined using the command line API and restore the original user-defined configuration, either restart VisualVM or use the --source-roots and/or --source-viewer, or the --source-config parameter with empty values.

Note: Parameter values cannot contain space, quote, and double quote. Use the following encoding for these characters:

  • space -> %20
  • quote -> %27
  • double quote -> %22

Version History

VisualVM 2.1 (Jul 20, 2021): Go to Source support in core tool, introduced *modules* flag, support for encoded parameters.

Plugin v. 1.1 (Oct 15, 2020): Added the --source-config parameter.

Plugin v. 1.0 (Aug 18, 2020): Initial release.