Live Application Information

STS4 automatically detects JVM processes for running Spring applications on your local machine.

When a running app is detected, STS 4 automatically shows hints by highlighting sections of source code with a light green background. Hovering over the highlights with the mouse pointer, data from the running app is displayed in a popup.

For some types of information, STS 4 may also show a 'quick summary' as a codelens. Codelenses are only supported in Eclipse and Vscode at the moment, not in atom. For Eclipse this has to be enabled via Preferences >> Language Servers >> Spring Language Servers >> Spring Boot Language Server.

If there are multiple instances of the app running on your machine, the live data from all those instances will show up in the hover information.

Application Requirements for Spring Boot projects

Live information is scraped from running apps using JMX to connect to Spring Boot Actuator Endpoints. This means that spring-boot-actuator must be added as a dependency to your application and enabled. The easiest way to accomplish this is to add the spring-boot-actuator-starter dependency to your application's pom.xml or build.gradle as explained here.

Spring Boot 2.2 and beyond

The JMX versions of the actuator endpoints (which the tooling uses under the hood to retrieve live data from the running applications) is not enabled by default anymore since Spring Boot 2.2. In order to allow Spring Tools 4 to continue to visualize live data from the running applications, you need to start the boot app with -Dspring.jmx.enabled=true in order to activate the JMX endpoints.

(New in 4.2.0) The Eclipse-based distributions of the Spring Tools 4 provide specific launch configurations when running Spring Boot apps that enable this setting automatically. So when starting your Spring Boot app from within Eclipse using a Spring Boot launch config, you don't need to do anything manually.

Application Requirements for non-Boot Spring projects (new in 4.1.1)

As of version 4.1.1, the Spring Tools 4 can gather live hover informations for regular, non-Boot Spring applications as well. To allow the tools to connect to those running applications and gather live bean information from them, you need to start those Spring apps with a specific system preference being set in your launch configuration: -Dspring.liveBeansView.mbeanDomain.

In case you run your Spring app in a local Tomcat, you need to set this VM argument in the launch configuration of the Tomcat server.

Please not that this feature for non-Boot Spring applications is limited to bean definitions and their wirings (see below for more details). Other live hover information (like request mappings, conditions, etc.) are not supported yet. Also projects need to use at least Spring 4.3 or beyond.

Managing Live Data Connections to Local Processes

As of STS 4.4.1 there is a minimal UI provided by both Eclipse and Vscode Spring Boot support to allow a user to explicitly connect / refresh / disconnect to running processes on the local machine.

In previous versions the spring boot language server would automatically try to scrape connect to any JVM processes it could see.

As of STS 4.4.1 this is now only the case for processes that are launched directly from the Spring Boot Dashboard in Eclipse. Furthermore, this automatation can also be disabled via a Eclipse preference under "Window >> Preferences >> Language Server >> Spring Boot Language Server":

For processes launched outside of the control of the Boot Dashboard there is now a minimal UI that allows the user to explicitly select a process to connect to it; disconnect from already connected processes; or refresh the data from a connected process.

In Eclipse this UI can be invoked using the 'Quick Access' search box:

Type the word live in the box and the relevant commands will be revealed:

Live Information Details

This section provides an overview of the different types of live information that are currently supported and how each of them can be accessed from the editor.

Live Request Mappings

Live Request Mappings information is displayed for a running Spring Boot application. Live Request Mappings data is fetched from the application process. The data is mapped onto the Request Mappings definitions in the source code. A typical Request Mapping definition is the @RequestMapping annotation. Such spots in the source code are highlighted with the light green background.

Hovering over such place in the source code displays Live Request Mapping information hover which shows the following:

• List of Live Request Mapping URLs defined by the Request Mapping definitions (hyper-links)
• Process information from which Live Request Mappings data has been fetched from

Code Lens is displayed on a dedicated line right above the green highlight in the source code. The Live Request Mapping URLs are displayed in a single line. Clicking on a URL opens this URL in the browser.

Both the hover and the Code Lens support multiple running Boot apps.

Live Bean Information

Live Beans information is displayed for a running Spring Boot application. Live Beans data is fetched from the application process. The data is mapped right onto the source code. Namely at the source code pieces where beans are injected or defined. Typically such places in the source code are Spring annotations but there are other places such as Component constructors, Spring Data repositories etc. These spots in the source code are highlighted with light green background.

Hovers

Live Beans hover is displayed when hovering over green highlights in the source code where beans are injected or defined. Typical Live Bean hover displays the following:

• List of beans current bean is injected into. Short summary list of beans in a single line followed by the detailed beans list
• List of beans wired into the current bean. Short summary list of beans in a single line followed by the detailed beans list
• Process information from which Live Beans data has been fetched from

Detailed list of beans provides for each bean the following:

• Bean ID
• Bean Java type (hyper-link)
• Resource defining the bean (hyper-link)

The hover can display Live Beans information for more than one running app as you can see below:

Code Lenses

Code Lens is displayed on a dedicated line right above the green highlight in the source code. The Live Bean information displayed by the Code Lens is a short one line summary list of wired in beans and injected into beans for the current bean.

Conditional Beans Information

Live conditional information is shown for running Spring Boot applications, if the conditions are matched at runtime. As with other live information, the @ConditionalOn... is highlighted in green when that conditional information is available.

Hovering over the highlighted conditional will display:

• Conditional matching information
• Process information from where the Live Conditional information was fetched

Live Active Profiles Information

Hovering over a @Profile will show which profiles are currently active in running boot applications. Additionally, the names of the profiles inside the annotation parameters will be highlighted, dependending on whether that specific profile is active.

Remote Applications

TLDR; If an app is deployed to cloudfoundry using the STS 4 Eclipse Spring Boot Dashboard, there is an option to enable JMX at the bottom of the deployment dialog:

Once the app is depployed. Live hovers will work automaticlly for that remotely deployed application.

Details

Live information is scraped from actuator-enabled apps using JMX. For local apps a JMX connection can be established automatically and doesn't require any special actions to enable JMX.

However, for remote apps the tools cannot automatically discover the process nor enable JMX support on the remote JVM. So besides needing to have actuator enabled (this is the same as for local apps) there are some additional requirements for remote apps:

• JMX must be explicitly enabled on the remote JVM when it is launched. This is done by setting certain system properties.
• The remote host and port on which the remote JMX service is running must be made accessible from the local machine somehow.
• The Editor must be explicitly configured to know where to find the remote JMX service.

There are two ways to satisfy these additional requirements. An easy automatic way (this only works for apps deployed directly from the workspace to cloudfoundry); and a more involved, manual way.

Automatic: App Deployed from Boot Dashboard

When deploying an app to Cloudfoundry there is an option near the bottom of the Deployment Dialog where you can enable JMX.

This makes live hover information work for the remote application.

What happens under the hood:

• JMX is enabled on the deployed application by setting additional system properties via the JAVA_OPTS environment variable.
• When the app has fully started a local SSH tunnel is created, proxying the JMX service on a local port.
• The editor is configured with a JMX url pointing to that local port.

This makes live hover information work for the remote application.

Manual

You can also set this up manually. This may, for example, be necessary if you don't deploy your application directly from the workspace but use a CI/CD pipeline for deployment. Here we explain the process for an app deployed to Cloudfoundry, but in principle this process can also be adapted to any actuator-enabled spring-boot app, running anywhere.

Step 1: Enabling JMX.

This can be accomplished by adding system properties via the JAVA_OPTS environment variable. For example you could add this to your cf manifest.yml:

env:
  JAVA_OPTS: > 
    -Dcom.sun.management.jmxremote.ssl=false
    -Dcom.sun.management.jmxremote.authenticate=false 
    -Dcom.sun.management.jmxremote.port=33333 
    -Dcom.sun.management.jmxremote.rmi.port=33333 
    -Djava.rmi.server.hostname=localhost 
    -Dcom.sun.management.jmxremote.local.only=false

Step 2: Creating an SSH tunnel

You can use the CF CLI to create a tunnel to the deployed app. For example:

$ cf ssh my-app-name -L 33333:localhost:33333

This will create an SSH session and open a bash prompt connected to the remote app. As long as this session is left open, JMX for that app can now be accessed on the local port (33333 in the example).

Note: Due to some JMX implementation details, you must use the same local and remote port numbers (both are 33333 in the example). If you attempt to change the local port without also changing the remote port to the same number, then it will not be possible to establish a JMX connection over the resulting SSH tunnel.

You can verify your tunnel is setup correctly by attempting to connect to the remote JVM with jconsole using this command jconsole localhost:33333.

Step 3: Configure the Editor

The final step differs slightly depending on the Editor you are using (Eclipse / Vscode / Atom). But each of the editors are configured by pasting an identical json snippet into a specific setting. The snippet should look something like the following:

[
    {
        "jmxurl" : "service:jmx:rmi://localhost:33333/jndi/rmi://localhost:33333/jmxrmi",
        "host" : "my-app-host-for-http.cfapps.io"
    }
]

Note that the snippet is a json list, so you can configure more than one remote app at the same time.

For Eclipse, paste this snippet into Preferences >> Language Servers >> Spring Language Servers >> Spring Boot Language Server >> Remote Boot Apps.

For Vscode, enter it as the value for the configuration key boot-java.remote-apps (in either user or workspace settings).

For Atom, enter it as the value in Atom's Config JSON for property "remote-apps" inside the object value of "boot-java" property

Completely Disabling this Feature

A background thread is used to periodically scrape running processes for live information. This could negatively affect your machine's performance. This feature can be completely disabled:

• Eclipse/Spring Tool Suite 4: via the preferences Language Servers -> Spring Language Server -> Spring Boot Language Server

• Vscode: Open User Settings command and search for: boot-java.boot-hints.on.

• Atom: boot-hints under boot-java in Atom's Config JSON.