Install Agent & Generate AppMaps from Tests

In this video
We install AppMap into our sample Ruby on Rails project inside of VS Code. You can find a link to the sample project below if you would like to follow along.

Links mentioned
Rails Sample Application
AppMap Slack community

Follow along

You can review the previous video for more details about what the ideal types of projects for AppMap are. We’re using a Ruby on Rails sample app, and can use APPMAP=true bundle exec rails test (use set APPMAP=true on Windows) to generate AppMaps, this is how AppMap will analyze the runtime of the code.

Install AppMap agent

From here, navigate to AppMap by clicking on the button in the left hand sidebar, and click on “Install AppMap agent”. The project picker will help you confirm that you’re running a suitable project before you install.

Copy the AppMap installer command and run it within your terminal window. The installer will look for project files like a Gemfile or a Package.json and it will ask you to confirm your details. For our Rails sample app, it’s going to find yarn configuration files as well as a Gemfile because this is a Ruby on Rails project. We’ll select a bundler option, and confirm our details. Once the agent is installed correctly, continue on to the next step, recording AppMaps.

Recording AppMaps

Copy the record command, it will ask what you want to use for your test command. It will make an assumption based on your test scenario. If the command you run tests with is different, you can change this command by pressing no, then entering a new command and include any environment variables you need.

You will need APPMAP=true (set APPMAP=true on Windows). We do recommend disabling spring as well DISABLE_SPRING=true (set DISABLE_SPRING=true on Windows). Confirm that this is the test command you want to run and how long you want to be able to run these test cases for my test finished pretty quickly. The default is 30 second run time.

Open AppMaps

By running this command we’ve generated 68 AppMaps in our Rails sample project, and we can continue on to the next step. We now have AppMaps that have been generated. We surface some of the AppMaps here, maybe ones that have a large number of requests or in this scenario, ones that have large numbers of SQL queries. You can click on any one of these to open the map directly inside of your vs code. You’ll be able to see which tests executed and generated this AppMap. You will also be able able to see server requests, packages, classes, functions, and SQL queries related to this.

Investigate findings and view code objects

We’ll continue on the onboarding process and be able to view any findings that the analysis function has picked out. When we click on the “View Problems” button, we’ll see a series of N-plus-one SQL queries. These could lead to performance issues for your users. By clicking on any of these findings, it will navigate us into the code base where this issue is occurring.

You can also see code objects have been indexed. This is another helpful way to be able to find which AppMaps include which specific SQL queries or specific API requests. From here, you can see the changes that we’ve made in our project to support AppMaps. The appmap.yml file includes the command that we’re going to execute as part of our test run, as well as which paths within our project we’re going to analyze.

And you can also see the Gemfile. We include AppMap as a development dependency. You can commit all of these files, which will make this available to any other developers on this project.

Finally, you’ll see AppMaps actually exist inside your temp directory in the AppMap folder. We don’t recommend committing these to your project. They can grow your git repositories unnecessarily.

If you’d like to learn more about how to share AppMaps with your team, reach out to us on Slack for a preview of at maps team offerings.

AppMap is now installed in our project and by running tests locally with the AppMap flag enabled, we will be able to generate AppMaps.

Next step: Generate AppMaps with Remote Recording

Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!