Agent setup

Install the AppMap extension for your code editor

The first step is to install the AppMap extension for your code editor. This will make all of the other steps easier, since there are specific guides and tours built into the code editor extension.

Follow quickstart instructions for your code editor.

Install and configure the AppMap agent

If you’re lucky, someone may have already configured your repo for AppMaps. Look for the appmap.yml file in the root directory of the project. If it’s there, you’re probably good to go and you can skip to step 3. If it’s not there, it takes about 5 minutes to install and configure the AppMap agent.

Choose the Quick Start video for your language:

Or check out the README in the agent repo for your language:

Record AppMaps

Recording AppMaps is easy. Once your environment is configured, AppMaps can be generated by running the project’s tests.

For Ruby and Python projects, generating AppMaps is as simple as running your tests normally with APPMAP=true at the beginning.


  • APPMAP=true bundle exec rake test
  • APPMAP=true bundle exec rspec
  • APPMAP=true bundle exec cucumber


  • APPMAP=true pytest


  • For Java projects, you can record tests by passing the appmap.jar as a javaagent.
    • java -javaagent:appmap.jar myapp.jar
  • If your project uses Maven, we recommend using the maven-plugin. Simply configure your project’s pom.xml to include the AppMap plugin and run
    • mvnw clean test
  • For Gradle builds, configure the build.gradle script to pass in the javaagent:
    • test { jvmArgs “-javaagent:$rootDir/appmap.jar” }

Using AppMap diagrams

Now you’re ready to dig into the code diagrams.

Once you’ve generated AppMaps, the next step is to open one in your code editor.

  • Ruby and Python: Find it in tmp/appmap/_test-framework_
  • Java: Find it in $buildDir/appmap

See How to use AppMap diagrams for additional details and examples of use.

Reference documentation

For advanced configuration options by language, check out their respective READMEs:

Refine appmap.yml for more impactful results

Recording large, complex applications can lead to acquisition of extraneous utility details that are not valuable for understanding how the application architecture works. If your AppMaps get too large, fine-tune the appmap.yml configuration file:

  1. Download and install AppLand CLI tools (only follow step 1 in the instructions)
  2. Refine your AppMap configuration

Then re-run the tests or re-record new AppMap files with the updated configuration.

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