TUTORIAL: Using Spring Boot Actuator Integrations With Pivotal Cloud Foundry 1.11

Adding Actuator to your Spring Boot application deployed on Pivotal Cloud Foundry gets you the following production-ready features:

• Health Check column & expanded information in Instances section
• git commit id indicator, navigable to your git repo
• Summary git info under Settings tab (also navigable to repo)
• Runtime adjustment of logging levels, exposed via Actuator endpoints
• Heap Dump*
• View Trace*
• View Threads, dump/download for further analysis*

* New in Pivotal Cloud Foundry 1.11

Let's take a quick walkthrough to see how easy it is to bring the power of Actuator to your Spring Boot apps on Pivotal Cloud Foundry 1.11.

NOTE: For this article, we assume a basic familiarity with creating Spring Boot applications and deploying applications to PCF. For more information on either, please refer to the Getting Started documentation for Spring Boot and Pivotal Cloud Foundry (or Pivotal Web Services).

Adding Actuator basic functionality

To add Actuator to your Spring Boot application, simply include the following dependency in your app's Maven POM file:

Or add this to your build.gradle file if using Gradle:

Doing only this, then rebuilding and redeploying your updated application to Pivotal Cloud Foundry 1.11 gets you the following additional integrations:

• Pivotal Cloud Foundry provides a visual indicator (icon) that your application is Spring Boot Actuator-enabled with the Spring Boot icon next to your application's name (Figure 1). 
• Pivotal Cloud Foundry includes an App Health column in the Instances section with a top-level indication of your application's state (Figure 1), along with detailed information you can see by expanding an instance (Figure 2). 
• From your application's Logs tab, the Pivotal Cloud Foundry+Actuator integration enables you to both review logs and configure logging levels dynamically, with zero downtime. Need to increase your app’s logging level(s) to Debug or Trace temporarily for troubleshooting? Simply select Logging Levels and move the appropriate slider to the desired setting. From this window, you can also filter the loggers displayed to quickly isolate and adjust the relevant logger quickly and painlessly (Figure 3). 

Figure 1: Spring Boot icon, App Health column on application page

Figure 2: Instance expanded to view Health Check details on application page

Figure 3: Configure application logging levels on the fly

Code commit information

Going a bit further, let's expose information about the code that went into this particular build and see how we can review diffs from the prior commit. This is an excellent way to quickly review which changes may have introduced a regression or otherwise unexpected behavior between deployments.

To expose basic git repository and build information via Spring Boot Actuator on Pivotal Cloud Foundry, we do the following.

Simply add the following to your Maven POM:

If using Gradle, these are the equivalent entries to add to build.gradle:

springBoot  {
    buildInfo()
}

plugins {
    id "com.gorylenko.gradle-git-properties" version "1.4.6"
}

To expose more than just the basic git commit and build information (recommended), add the following entry to your application's application.properties file:

Once done, a rebuild/redeploy takes the information shared from this:

Spring Boot Actuator /info endpoint, git mode simple

and

Settings tab, Spring info section, git mode simple

To this:

Spring Boot Actuator /info endpoint, git mode full

and

Settings tab, Spring info section, git mode full

Sometimes it's helpful to review the code commit from which this deployment was built and to compare it to the previous commit. To do so, simply click the git commit id listed in the upper right of any of your application's tabs (Figure 4) or from the link labeled SHA under the Settings tab, Spring Info section (Figure 5). This will take you to your remote code repository (also shown in the Spring Info section’s git properties), where you can review the current commit and its delta from the previous one (Figure 6).

Figure 4: Application page, git commit id

Figure 5: Settings tab, Spring Info, git commit id (with summary commit info)

Figure 6: git commit linked from app deployment’s git id

New for Pivotal Cloud Foundry 1.11

Sometimes you really need to "get under the hood" of your application. Developers often want to capture and analyze their application's memory profile, interactions, and thread usage. Spring Boot Actuator and Pivotal Cloud Foundry 1.11 help you do just this, quickly and easily. After all, time is short and demands are high!

Heap dump

To get a heap dump from your Actuator-enabled PCF application, just click the three vertical dots next to one of your application's instances and select Heap Dump. You'll be prompted for a destination (Figure 7) to which to save a gzip-compressed file containing the heap dump.

Figure 7: Heap dump save dialog

Extracting the gzipped file yields a single file with the extension hprof. This dump file can be opened using your favorite heap dump analysis tool. We'll use VisualVM, a free tool included with the JDK, to take a closer look.

To do so, run jvisualvm from the command line. Select File|Load from the menu, navigate to the directory where you saved and extracted the heap dump, limit File Format to Heap Dumps, and select the heap dump file you just extracted (with hprof extension).

Once VisualVM loads the heap dump, you can review summary information for the dump (Figure 8).

Figure 8: VisualVM summary page for heap dump

Let's dive a bit deeper. Clicking the Classes tab shows a table of all classes used in your application with instance counts and sizes (Figure 9).

Figure 9: VisualVM Classes page for heap dump

To quickly zero in on classes of interest, you can use the Class Name Filter (Contains) box at the bottom of the page. Let's filter for classes we've defined in our application using org.thehecklers as the root of the Fully-Qualified Class Name/FQCN (Figure 10).

Figure 10: VisualVM filter classes from heap dump

Next, let's double-click a class with active instance(s) (or alternately, select it, right-click, and choose Show in Instances View) to review that class's instances (Figure 11).

Figure 11: VisualVM instances page for heap dump

From here, we can examine that instance's fields and references, exposing the nearest root for garbage collection by right-clicking on this under References and selecting Show Nearest GC Root. This can help determine what is keeping objects in question from being garbage-collected and thereby help us free much-needed memory (Figure 12).

Figure 12: VisualVM nearest GC root for selected object

View Trace

To view traces of your application's requests+responses, either click the three vertical dots next to one of your application's instances and select View Trace or select the Trace tab at the top of your application's page in Apps Manager. You can choose a particular instance or all instances, then choose a specific request for examination. Doing so provides you details about the particular request and its associated response (Figure 13).

Figure 13: Details for selected trace within Apps Manager

View Threads

Finally, Spring Boot Actuator and Pivotal Cloud Foundry 1.11 enable you to view your application's threads, examine their current status, and download a thread dump for additional scrutiny. To do so, either click the three vertical dots next to one of your application's instances and select View Threads or select the Threads tab at the top of your application's page in Apps Manager. You can choose a particular instance or all instances and if you choose, show all threads (default) or only those that are new, runnable, blocked, waiting, or in a timed-waiting state (Figure 14). You can select a thread for examination (Figure 15) or download a full thread dump for a more exhaustive review (Figure 16).

Figure 14: Filtering displayed threads within Apps Manager

Figure 15: Thread details within Apps Manager

Figure 16: Downloading a thread dump within Pivotal Cloud Foundry 1.11

Summary

This was a fairly quick tour of some of the key capabilities provided in Pivotal Cloud Foundry 1.11, courtesy of increasing integrations with Spring Boot Actuator. If you haven't yet included Actuator in your PCF-deployed Spring Boot applications, now's the time to start!

Try them in Pivotal Web Services today, or upgrade to Pivotal Cloud Foundry 1.11.

You gain vital tools for monitoring, introspection, and troubleshooting quickly and effectively: tools needed by productive developers and operations alike. We look forward to helping you take your projects to production and helping you keep them there. Onward & uptime, er, upward!

Ready to take your Spring skills to the next level? Register for SpringOnePlatform before June 24 and save $400!