Spring PetClinic as a Stand-alone App

This guide describes how to enable the Retrace Java profiler on a stand-alone Spring PetClinic application.

The app has the following pages:

1. Home - a simple landing page
2. Find Owners - page showcasing simple DB queries as part of sub-transactions that add a new owner and find records.
3. Veterinarians - page that shows the list of vets in tabular format
4. Error - used to simulate an exception. The exception will be auto-captured by the profiler and then reported to your Retrace account.

Pre-requisites

1. Retrace agent. Your machine will appear on your Retrace account after installing the agent.
   1. Windows: https://docs.stackify.com/docs/net-agent-installation-overview
   2. Linux: https://docs.stackify.com/docs/linux-installation
2. Java (either JRE or JDK will work)

   1. Download the appropriate package for your environment at https://jdk.java.net/21/

   2. Extract the contents of archive and take note of the path.

      • On Windows:
        

   3. Add the system variables: JAVA_HOME=/Path/To/Your/JavaDir and Path=${existing path values};/Path/To/Your/JavaDir/bin

      • On Windows:
        
        Note

        The app used in this guide does not require the JRE_HOME variable so the variable seen in the screenshot can be disregarded. Other apps, however, might require this variable.

      • On Linux:

        $ export JAVA_HOME=/Path/To/Your/JavaDir
        $ export PATH=${PATH}:/Path/To/You/JavaDir
        

   4. Test by opening the terminal and executing the command java -version.
      

Now that both the Retrace agent and Java are installed, let's proceed to the next section.

Enabling APM on the Java App

1. Download the sample app from the GitHub repo and save to your preferred location: https://github.com/stackify/example-apps/raw/main/sample-java-petclinic/spring-petclinic-2.7.0.jar.
   Clicking on the click will trigger the download of a jar file.

2. Open the terminal and go to the same directory you saved the app (jar file) in Step 1, and then run the app using the Java command:

   1. On Windows

   C:\your-app-path> java -Djava.io.tmpdir="C:\your-app-path\" -Dserver.port=<any-unused-port> -javaagent:"C:\ProgramData\Stackify\Profiler\Java\stackify-java-apm.jar" -DSTACKIFY_APPLICATION_NAME="Your-App-Name" -DSTACKIFY_ENVIRONMENT_NAME="Your-Env-Name" -jar spring-petclinic-2.7.0.jar
   

   Image showing the app's path/location:
   

   Image showing a successful launch of the app:
   

   2. On Linux:

   $ java -Dserver.port=<any-unused-port> -javaagent:/usr/local/stackify/stackify-java-apm/stackify-java-apm.jar -DSTACKIFY_APPLICATION_NAME="Your-App-Name" -DSTACKIFY_ENVIRONMENT_NAME="Your-Env-Name" -jar spring-petclinic-2.7.0.jar
   

   Image showing the app location on Linux:
   

   Image showing a successful start of the app on Linux:
   

3. Send requests to the app and view APM data in Retrace.
   To view the app, open your browser and go to http://localhost:[port-used-in-step-2].

   Here's what the landing page looks like:
   

   And how APM will appear in Retrace:
   

Post-Installation Checks

1. The Retrace Java profiler will generate output logs at C:\ProgramData\Stackify\Java\, in .\debug for debug logs and .\log for trace logs after the app receives any request. In Linux, the paths are at /usr/local/stackify/stackify-java-apm/debug and /usr/local/stackify/stackify-java-apm/log

   As long as traces are generated, it should only be a matter of time before the app appears in your Retrace account.

Done!

To learn more about viewing your application's data, be sure to check out documentation on the App Dashboard.