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
• Requests recording - Python
• Requests recording - Java

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 (VS Code)
   • 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
• 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. Start the recording, troubleshooting the agent connection if necessary.
2. Interact with your application through the UI or API.
3. Stop and save the recording
4. Open the AppMap in your code editor

Code block recording

For some languages, the AppMap library provides a language-native function that you can use to record a specific span of code. For example, a Ruby block, a Java Runnable, or a Python context manager (with statement). This is a useful method when you need direct control over which code is recorded, when test cases are not avaliable, and when the application does not have a webserver and therefore can’t support remote recording. 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.

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.

• Full control over the recording 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.

• Block recording - Ruby
• Context manager recording - Python
• Runnable recording - Java

Process recording

Some AppMap agents provide the ability to record an entire process from start to finish. As long as you’ve configured it correctly, this is a sure-fire way to get an AppMap of your code.

Pros

• Easy to set up You don’t need to change your code to make a process recording. Just start your application with the AppMap agent enabled.

Cons

• Not focused on a specific code area The AppMap will contain all of the code that is executed during the process. So it may contain code that you don’t care about.

• Verbose The AppMap will contain all of the code that is executed during the process, there may be extraneous information that you have to filter out or ignore in order to find what you’re looking for.

• Process recording - JavaScript
• Process recording - Java

Note For Ruby and Python, it’s recommended to use code block recording instead. You can record the entire process by injecting code block recording into the entry point of your application.