Recording AppMaps

Test case recording

AppMap integrates with popular test frameworks, so you can automatically record an AppMap from each test case that you run.

Some characteristics of test case recording include:

• Named for the test case The name of each AppMap corresponds to the name of the test.
• Includes source location The AppMap metadata contains the path and line number of the test case. From the AppMap diagram, you can navigate to the test case code.
• Supports incremental testing AppMap’s dependency analysis capability can help you re-run out-of-date test cases as you modify the code - even in very large repositories.
• Run in CI You can make AppMaps of your test cases as your CI job runs. Then you can archive the AppMaps for each branch, and you can run AppMap Analysis for each pull request.

For details on test case recording, see:

• Tests recording - Ruby
• Tests recording - Python
• Tests recording - Java
• Tests recording - JavaScript

Requests recording

You can configure your application to record an AppMap of each HTTP server request.

Some characteristics of test case recording include:

• Named for the route The name of each AppMap contains the HTTP request method and path, so you can see at a glance what request AppMap contains.
• Sortable by timestamp In the AppMap extension, requests AppMaps are sorted by timestamp, with newest AppMaps at the top. So you can see a chronology of the requests that your app is serving.

For details on requests recording, see:

• Requests recording - Ruby

Remote recording

Remote recording enables you to create an AppMap while interacting directly with your app through the UI and/or API.

Some characteristics of remote recording include:

• Named by you When you finish creating a remote recording, you give it a name that makes sense to you. For example, you can name it for the user flow, or the id of the issue that you are trying to reproduce.
• Contains a sequence of requests A remote recording AppMap contains the entire sequence of HTTP server requests that occur as you use the application.
• Contains both foreground and background work A remote recording AppMap contains all threads of execution, not just the web server. So you can see background jobs, message queue activity, and other threads of activity along with the main HTTP server request.
• Ideal for sharing When you reproduce a bug, security vulnerability, or performance problem in a remote recording AppMap, you can share it with colleagues so they can see exactly what the problem is. An AppMap contains much more information than the source code itself.

The steps for creating a remote recording are:

1. Start your application server with remote recording enabled:

   • Remote recording - Ruby
   • Remote recording - Python
   • Remote recording - Java (IntelliJ)
   • Remote recording - Java (command line)
   • Remote recording - JavaScript

2. Start the remote recording

There are several ways to start (and stop/finish) remote recording.

• VSCode - Remote Recording
• JetBrains - Remote Recording
• @appland/appmap CLI

npx @appland/appmap@latest record remote

Note If you are having trouble connecting to your application to make a remote recording, try the CLI command. It provides step-by-step instructions with feedback at each step.

1. Interact with your application through the UI or API.
2. Stop and save the recording

Use the code editor command to stop the recording, or follow the CLI propmt.

1. Open the AppMap in your code editor

Once you stop/finish the recording, the AppMap will open automatically in your code editor.

Direct code block recording

All AppMap agents provide an API that enables rapid recording of execution of a block of code. This is a useful method for a quick spin of application logic without tests such as when prototyping new code or troubleshooting stubborn bugs. The method can be performed with a few lines of code, allows for programmatic control of the recording context, and does not require an upfront setup of functional or integration tests. You can read more details about Appmap.record() in the agent documentation.

Some characteristics of remote recording include:

• Focused on a specific code area You can start and stop the recording exactly where you want in the code.
• Integrated with the code Because the AppMap is made by your own code, you can inspect it, pre-process it, filter it, transform it, etc before it’s even written to the filesystem. You can even send it to other locations such as a remote storage system or HTTP endpoint.

Examples:

• Python
• Ruby
• Java