Recording AppMaps

Overview

There are three ways to use AppMap to record your application’s behavior:

  • Recording AppMaps from test cases - AppMap agents integrate with popular test frameworks and automatically record AppMaps from individual tests when the tests are run.
  • Remote recording - Use the npx @appland/appmap record command to create an AppMap of your app’s backend while you interact with its UI or API.
  • Direct code block recording - Developers can add code to their applications that starts/stops AppMap recording using APIs implemented in AppMap agents.

Recording AppMaps from test cases

Automated tests offer a convenient method for creating and managing AppMaps. AppMaps are recorded when the tests run, and the AppMap filenames correspond to the names of tests. Using this method, AppMap can easily be configured to run continuously in CI.

We provide detailed instructions for recording test cases for all supported languages.

Remote recording

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

The steps for creating a remote recording are:

  1. Hook the AppMap agent when you start the server for your Rails, Django, Flask, Java, or JavaScript application or microservice
  2. Run this command to start recording: npx @appland/appmap record
  3. Interact with your application or microservice sufficiently to allow AppMap to record the behaviors which you wish to review.
  4. Stop the recording by typing Y at the CLI prompt and save your new AppMap.

Advanced Use Cases for Remote Recording

Remote recording of monolithic apps or individual services

Let’s consider a recording scenario where a test framework executes functional/integration tests that in turn interact with the tested application deployed to a remote host. These tests may perform both API- and UI-driven testing:

Simple remote recording diagram

Fig. 1 Simple remote recording diagram

Setup
  • Functional1 tests are run by a test framework on Host A.
  • Functional tests interact with the application running on Host B.
  • The AppMap agent records the application on Host B.
Execution flow

In this setup, an AppMap is recorded and saved to disk when this flow is completed:

  1. Prior to each individual test’s execution, the test framework calls the AppMap agent’s endpoint that starts recording the application on Host B.
  2. The test framework starts a test on Host A.
  3. The test interacts with the tested application on Host B. The AppMap agent records the execution of the tested application on Host B.
  4. When the test finishes on Host A, the test framework calls the AppMap agent’s endpoint to finish recording on Host B.
  5. In the response payload, the AppMap agent returns the recorded AppMap back to the test framework. The test framework names the returned AppMap and saves it to disk on Host A.

These steps are repeated by the test framework for all tests in a suite. When finished, the AppMap files will be stored on Host A and ready for downstream processing, either in an AppMap code editor plugin or on the AppMap server.

Remote recording of distributed applications

A similar strategy can be adopted when recording mapsets of distributed applications that have services deployed to remote hosts. The topology and flow of such setups looks like this:

Remote recording distributed apps

Fig. 2 Remote recording distributed apps

Setup
  • Functional2 tests are run by a test framework on Host A.
  • Functional tests interact with the application running on Host B.
  • Application running on Host B invokes services running on Host C.
  • AppMap agent records the application on Host B and the services are recorded on Host C.
Execution flow

Just like in the simple case, AppMaps are recorded remotely by the Test framework logic, then fetched and saved to disk on Host A. The major differences between the simple and distributed scenarios are:

  • The test framework on Host A starts and stops remote recording on multiple hosts, (on Host B and on Host C in this example).
  • The test framework fetches and stores AppMaps from each host when a test ends. The control logic is responsible for giving the AppMaps names representing the hosts/applications/services that they were recorded for.
Processing data from distributed tests
In your code editor

AppMap for Visual Studio Code only opens a single AppMap at a time, so the multiple AppMaps recorded per each test need to be viewed sequentially, or in multiple open code editors.

In AppMap

When uploading mapsets recorded on multiple hosts to the AppMap server, there are two options for aggregating the data:

  1. Recommended: Application’s distributed components’3 AppMaps are uploaded as separate mapsets for a dedicated application. This is the recommended route.
  2. Not recommended: Recorded AppMaps of multiple distributed components are merged into one large mapset during upload. We do not recommend this route without consulting with our team first.

Associating distributed components with dedicated applications in the AppMap server comes with these important benefits:

  • Git metadata can only be properly tracked in mapsets and their histories if all recorded code objects in a mapset were managed in the same git repository, (coming from the same branch, commits, etc.)
  • A set of smaller mapsets is faster and easier to process, interact with and analyze than a single large mapset.
  • It’s common for individual components to have different owners. Component owners may perceive data recorded from other components as extraneous or as noise.

Application
Components
AppMap Data
Application - Mapset - AppMap
Tests
Main
Application
Main
Application
Mapset
For M.A.
v1.0.0
AppMap Test 1 Test Session
for
v1.0.0
Test 1
AppMap Test 2 Test 2
AppMap Test 3 Test 3
Mapset
For M.A.
v1.1.0
AppMap Test 1 Test Session
for
v1.1.0
Test 1
AppMap Test 2 Test 2
AppMap Test 3 Test 3
Service A Service A Mapset
For S.A
v1.0.0
AppMap Test 1 Test Session
for
v1.0.0
Test 1
AppMap Test 2 Test 2
AppMap Test 3 Test 3
Mapset
For S.A
v1.1.0
AppMap Test 1 Test Session
for
v1.1.0
Test 1
AppMap Test 2 Test 2
AppMap Test 3 Test 3
Service B Service B Mapset
For S.B
v1.0.0
AppMap Test 1 Test Session
for
v1.0.0
Test 1
AppMap Test 2 Test 2
AppMap Test 3 Test 3
Mapset
For S.B
v1.1.0
AppMap Test 1 Test Session
for
v1.1.0
Test 1
AppMap Test 2 Test 2
AppMap Test 3 Test 3

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.

Examples:

  1. Functional / integration / end-to-end tests, as opposed to elementary unit tests 

  2. Functional / integration / end-to-end tests, as opposed to elementary unit tests 

  3. In this context, the components are the application itself or any of its (micro)services 


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