Recording methods

Overview

AppMap agents can record all running application code provided there is control logic that determines when the recording is started, when it is stopped and how it should be named. These are the major AppMap recording methods:

  • Recording automated test cases - AppMap agents integrate with popular test frameworks and automatically record AppMaps from individual tests when the tests are run.
  • Remote recording - A user or script (like a Cucumber test suite) starts, stops and saves the recording of a running Web application or service remotely via http calls.
  • Direct code block recording - Developers can add code to their applications that starts/stops AppMap recording using APIs implemented in AppMap agents.

Recording test cases

Automated tests offer a convenient automated recording control layer as they trigger recording when they start, the recording stops when they finish, and the AppMaps files are naturally named after the tests (which are typically understandable names).

Instructions for recording tests

Pros

The biggest benefit of recording tests is the automation and repeatability - you only set up AppMap recording from tests once, then you can record AppMaps whenever tests are run such as in CI/CD or in local dev environments.

Cons

While recording automated tests can be an excellent way to make AppMaps, there are situations where other methods are preferred:

  • When test coverage is thin
  • When code is covered by simplistic unit tests that lead to a large number of simplistic AppMaps
  • When the server runs in a separate process from the test scripts (i.e. integration and functional tests)
  • When you want to record distributed applications that consist of multiple components (such as microservices) deployed to multiple VMs

Remote recording

Remote recording allows starting, stopping, retrieving and storing AppMaps from a remote host. When AppMap agents are set up and running, they expose the recording API via REST endpoints that can be invoked by control logic run on the same or remote hosts. This control logic can be implemented programmatically or performed by human operators using command line tools, UI controls available in AppMap code editor extensions or the AppMap web browser extension.

Remote recording instructions

Remote recording is the recommended method for users new to AppMap. Please visit the remote recording documentation for more information.

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 in AppMap Cloud.

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 Cloud

When uploading mapsets recorded on multiple hosts to AppMap Cloud, 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 AppMap Cloud 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 Cloud 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!