A Step-by-Step Guide for Installing and Using AppMap for Java

A Step-by-Step Guide for Installing and Using AppMap for Java

Posted 07 Sep 2021 by Petr Dvorak

Thanks to everyone who attended our recent workshop for the Boston Java Meetup Group! If you weren’t able to join us, don’t worry. Here are the step-by-step instructions we shared for how to use free and open source AppMaps to highlight a design flaw in a simple Spring application.

A quick note: As we were preparing for the workshop, we actually found an even better way to solve the N+1 issue in the Pet Clinic app that we demoed. So the below instructions reflect these new updates.

If you have any questions or feedback as you go through these steps, please don’t hesitate to reach out. You can find us on Slack where we can chat one-on-one or feel free to email us at support@appmap.io.

Prerequisites

  • JDK 8 and newer
  • macOS, Linux or Windows are all fine
  • Supported IDE: IntelliJ 2021.1 or newer, or VSCode with Java extensions
  • git client, basic familiarity with git
  • Node.js installed
  • GitHub or GitLab account

Instructions for installing and using AppMap for Java

Step 1: Clone, build and run the Spring Petclinic Application

  • Clone the Petclinic git repository to a local folder 
    git clone https://github.com/spring-projects/spring-petclinic.git
cd spring-petclinic
  • Build locally with Maven
    • mvnw clean install (Windows)
    • ./mvnw clean install (macOS, Linux)
  • Start the app and open the web UI
  • Stop the app with CTRL+C

Step 2: Install AppMap for IntelliJ or VSCode

  • Open the PetClinic project in your IDE
  • Install AppMap from the marketplace
  • Use this command to install the appmap-java agent for this project 
      npx @appland/appmap install-agent

Step 3: Record and open AppMaps from tests

  • Run tests with Maven
    • mvnw test (Windows)
    • ./mvnw test (macOS, Linux)
  • View recorded AppMaps in your IDE.

Step 4: Record AppMaps with remote recording

The AppMap agent can record all running application code. In this step, we’ll instrument the application server and record your application’s behavior as it runs. Here’s how it’ll happen:

  • Configure and start the application with remote recording
    • Download appmap-1.5.0.jar
    • Start the application with the appmap-1.5.0.jar javaagent: 
      java -javaagent:appmap-1.5.0.jar -jar target/*.jar
  • Record an AppMap
    • Start AppMap recording in your IDE
      • IntelliJ: Menu Tools -> AppMap -> Start AppMap Recording
      • VSCode: SHIFT+COMMAND+P AppMap: Start remote recording
    • Find and view owner in the PetClinic application
    • Stop and save AppMap in your IDE
      • IntelliJ: Menu Tools -> AppMap -> Stop AppMap Recording
      • VSCode: SHIFT+COMMAND+P AppMap: Stop remote recording
  • Inspect the recorded AppMap
    • HTTP requests
    • Function calls
    • SQL commands

Step 5: Record and inspect the behavior of the Spring framework

  • Configure AppMaps for shallow recording of the Spring framework. Update the appmap.yml file in the project root folder to include this path:

     - path: org.springframework.web
   shallow: true
   exclude:
   - org.springframework.web.filter.OncePerRequestFilter
   - org.springframework.web.context.request.RequestContextHolder
   - org.springframework.web.context
   - org.springframework.web.servlet.resource.ResourceUrlEncodingFilter
  • Make a new remote recording
    • Start AppMap recording in your IDE
    • Find and view owner in the PetClinic app
    • Stop and save AppMap
  • Inspect the Spring framework events in the AppMap
    • See how OwnerController is called from the framework

Step 6: Find N+1 anti-pattern with AppMaps

  • Find and fix N+1 SQL antipattern in the Pet Clinic app
    • View the anti-pattern in a recorded AppMap
      • Find and open a ‘should find vets’ AppMap recorded from a test
      • View the SQL commands
    • Find the bug and fix the code (here is a hint)
    • Re-record the AppMap with the fix in place and compare it with the “before” AppMap

Step 7: Share AppMap with your peers

Congratulations! You’ve completed our tutorial for using AppMap in a simple Spring application. Now it’s time to give it a try with your own app! We’re rooting for you and here to help, so give us a shout on Slack if you have any questions. You can also check out our doc site and our blog for additional resources, use cases and tutorials. Happy mapping!

Additional Resources:

AppMap logo Get AppMap