AppMap agent guide

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.

Check out the documentation for your language, including detailed configuration, recording and code labeling instructions:

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 use the gradle-plugin and run
    • gradlew clean appmap test

Use 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 for Maven and Gradle run tests, or in tmp/appmap.

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 AppMap Cloud 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!