Remote recording

Remote recording is often the preferred method of creating AppMaps during troubleshooting of stubborn bugs, or when existing code coverage is thin.

How it works

Remote recording is one of the recording methods supported by AppMap. It consists of two steps:

  1. Run your application with a properly configured AppMap agent
  2. Start and stop AppMap recording remotely with REST endpoints that the agent injects into the running application’s web stack.

AppMap agent setup instructions

Don't enable AppMap remote recording in production. AppMap remote recording will serve recording results to any client request, without authentication. Remote recordings may contain sensitive data like passwords and API keys.

For all applications: configure appmap.yml

In the first step, configure the appmap.yml for your application code base. Visit the quickstart for instructions for your language and code editor.

For Python applications

Follow the Python remote recording instructions for Django and Flask applications.

For Ruby applications

Follow the Ruby remote recording instructions for Rails applications.

For Java applications

To enable an AppMap recording for a Java application, add the -javaagent JVM parameter to the startup parameters of your Java application or server as outlined in the appmap-java setup instructions.

Starting Spring boot applications from command line

Follow the appmap-java instructions for downloading the appmap.jar AppMap agent, then start your application with the -javaagent parameter, for example

$ java -javaagent:appmap.jar myapp.jar 

Adding AppMap agent to Tomcat configuration

Download the appmap.jar AppMap agent as described above, then add -javaagent and other AppMap parameters to the setenv script (setenv.sh or setenv.bat) in the CATALINA_HOME/bin folder of your Tomcat installation, for example:

JAVA_OPTS="-javaagent:/Users/user/myapp/appmap.jar -Dappmap.config.file=/Users/user/myapp/appmap.yml -Dappmap.output.directory=/Users/user/myapp/appmap/  -Dappmap.debug=true"

You can take a similar approach for configuring other Java servlet engines.

Remote recording with code editors

The AppMap extensions for popular code editors come with convenient controls for remote recording in the UI.

JetBrains: IntelliJ, PyCharm, RubyMine

Remote recording controls are accessible as plugin actions and also as buttons in the AppMap view.

  1. Open the AppMap view by clicking on the AppMaps tab in the top right corner
  2. Click on the recording button in the top right corner and in the Remote URL field, enter the address of your instrumented running web app. For example, if your application runs locally on port 8080, enter http://localhost:8080

    Start recording icon

    Remote URL

    Note: you can pick a previously entered URL in the drop-down list under the text field.

  3. The recording starts. If you see an error message, make sure that the Remote URL is correct, that your application is properly instrumented and that it is running. You will see the recording status in the status bar of your code editor.

    Recording status

  4. Now interact with the application while a new AppMap is being recorded. All instrumented code paths executed by the running application will be recorded.

  5. Stop the recording by clicking on the stop recording button. You will be asked to enter the name of the recorded AppMap and the storage folder. In order to view the AppMap in your code editor, pick a folder in your current project.

    Save AppMap

  6. If you’ve saved the AppMap in the current project folders, the AppMap opens and you can see it in the AppMaps view.

    AppMap in list

Visual Studio Code

Remote recording controls are accessible as extension actions and as buttons in the AppMap view.

  1. Open the AppMap view by clicking on the AppMap tab in the left bar
  2. Click on the recording button in the top right corner of the view and in the Remote URL field, enter the address of your instrumented running web app and press Enter . For example, if your application runs locally on port 8080, enter http://localhost:8080

    Start recording icon

    Remote recording URL

    Note: you can pick a previously entered URL in the drop-down list under the text field.

  3. The recording starts. If you see an error message, make sure that the Remote URL is correct, that your application is properly instrumented and that it is running. You will see the recording status in the status bar of your code editor.

    Recording status

  4. Now interact with the application while a new AppMap is being recorded. All instrumented code paths executed by the running application will be recorded.

  5. Stop the recording by clicking on the stop recording button. You will be asked to enter the name of the recorded AppMap.

    Save AppMap

  6. The AppMap opens and you can see it in the AppMaps view.

    AppMap in list

Remote recording API

When an application is set up for AppMap recording, the AppMap agent injects itself into the web stack and handles the remote recording HTTP requests, accepting requests on the same port as the web interface of the application.

For example, if you deployed your application to a local Tomcat server listening on port 8080, call the remote recording endpoints at http://localhost:8080/_appmap/*

Start a remote recording

POST /_appmap/record

No payload in the request is expected.

This endpoint returns 200 if a new recording session was started successfully or 409 if an existing recording session was already in progress. It returns an empty body in the response.

curl example:

curl -H 'Accept: application/json' -sXPOST http://localhost:8080/_appmap/record

Retrieve the current recording status

GET /_appmap/record

No payload in the request is expected.

This endpoint returns status 200 .

AppMap recording status is returned in the response body, the “enabled” property is set to true when recording is in progress:

Content-type: application/json
{
  "enabled": boolean
}

curl example:

curl -H 'Accept: application/json' -sXGET http://localhost:8080/_appmap/record

Stop a remote recording

DELETE /_appmap/record

No payload in the request is expected.

This method returns 200 If an active recording session was stopped successfully, and the body contains AppMap JSON, or 404 If there was no active recording session to be stopped.

If successful, the recorded AppMap is returned in the response body.

Content-type: application/json
{
  "version": "1.x",
  "metadata": {},
  "classMap": [],
  "events": [],
}

curl example:

curl -H 'Accept: application/json' -sXDELETE http://localhost:8080/_appmap/record -o MyFirstAppMap.appmap.json

Save recorded AppMaps to disk

Save the returned payload to disk as an .appmap.json file. We recommend that the AppMap file be named after the recorded test and that additional metadata is added to the recorded AppMap prior to saving, such as the AppMap’s name or labels indicating the test outcome and framework. See the AppMap specification for details about AppMap metadata.

Example: remote recording in Ruby

For inspiration, see this sample Ruby code that starts and stops the recorder, retrieves the AppMap, updates its metadata and saves it to disk. This code snippet is used to record Cucumber tests.


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