How AppMap Works

Language “agent”

The AppMap process begins with the AppMap recording agent. This “agent” is a language-specific library - agents are available for Java, Python, Ruby and Node.js (Beta). You add the agent as a dependency of your project in the normal manner - via Maven, Gradle, Pip, Bundler, Yarn, etc. Then you configure your application to load the agent when the application runs.

Java Python Ruby Node.js
-javaagent JVM option Django environment test and/or development bundle npx appmap-node yourapp
Gradle plugin Flask environment
Maven plugin

Running application code with the AppMap agent enabled

AppMap is designed to record and display the code internals of your project, along with important I/O operations. Here’s a comparison of AppMap with other runtime code tools:

AppMap Profiler Exception reporter Debugger APM / Telemetry
Primary focus Your code
Parameters and return values
I/O
Log statements
Execution stack
Timing data
Exceptions		 All code (your code + dependencies)
Execution stack
Timing data		 Exceptions
Execution stack 		All code
Parameters and return values
Execution stack
Exceptions		 I/O
Log statements
Timing data
Your code (limited)
Environment development, test, staging, CI development, staging staging, production development production

To summarize, AppMap is designed primarily to record full details of your code, including parameters and return values, as well as I/O (especially SQL and HTTP client requests), it includes log statements, the execution stack, timing information, and exceptions. It captures all of this with minimal configuration. It’s designed primarily for non-production environments.

appmap.yml configuration

When you start your app with the AppMap agent enabled, it reads a configuration file called appmap.yml. This file serves several basic purposes. It tells the AppMap agent:

  • Which code to record
  • Where to write the AppMap Data.

And it also tells other AppMap tools:

  • The project name
  • The language name
  • Where the AppMap Data is located

Note: In most environments, a default appmap.yml will be auto-generated by the AppMap agent if none exists.

Specifying which code to record

To get started, you just provide the top-level package names or directories containing the code you want to record. For a non-compiled language like Ruby, Python, or Node.js, it’s a directory list like [ app] or [ src, lib ]. For Java, it’s a package prefix like org.mycorp.

Going beyond this basic, initial configuration, you have fine-grained control over which code to record. You can choose to record selected dependency libraries or packages. You can also include or exclude specific packages, classes and/or functions. And you can apply custom “labels” to any function, in order to organize the code into functional groups and to facilitate reasoning and analysis.

Recording methods

The AppMap agent can be enabled in any environment, and configured to record selected code. There are several variants of this basic model that are commonly used to acquire AppMap Data for specific use cases.

Test case recording

AppMap provides specialized support for recording test cases. When you run your test cases in a supported framework (there are many - see the language agent reference for details), a separate AppMap Diagram is created for each test case. AppMap Diagrams created from tests cases have some distinct features:

  • Each AppMap file is named for the test case, and stored in a folder called $appmap_dir/$test_framework
  • The test framework name and version are stored in the AppMap.
  • The test case name, file name and line number are stored in the AppMap.
  • The test status (succeeded or failed) and any test failure message are stored in the AppMap.

Recording the test suite of an application is a good way to quickly obtain a lot of data about an application. And because test cases work the same way for each build, recording test cases is also a good way to compare the behavior of application code across versions.

Requests recording

For web applications, AppMap can be configured to record an AppMap for each HTTP server request handled by the app. This is a great way to collect data interactively. Just start the application with the AppMap language agent enabled, and start interacting with the app - manually, or using QA scripts or an API testing tool like Postman. AppMap Data is generated continuously as the application handles requests.

Remote recording

Remote recording is similar to requests recording, in that:

  • It’s for web applications
  • It makes AppMap Data as the application handles requests

But unlike requests recording, you control the boundaries of the AppMap, each AppMap can contain more than one HTTP server request, and it will also contain non-HTTP activity such as background jobs. To start a remote recording, you send an HTTP command to the AppMap agent running inside your application’s web stack to start recording. From that point on, everything that happens inside the application is recorded, until you send the “stop” command.

Code block recording

Some language agents enable you to make an AppMap by adding a simple code snippet to your code. This gives you total control over what’s recorded. The only downside of this is that you need access to the source code - which is not required by other recording methods.

Process recording

Process recording is something of a last resort, when other recording methods aren’t available. When you run your application with process recording enabled, everything that happens in the code (as configured by the appmap.yml) is recorded, from process startup to shutdown.

About AppMap files

AppMap Data is ordinary JSON files. As you record AppMap Data with test case recording, requests recording, or process recording, these JSON files are generated and written to the filesystem. The default location for AppMap Data is tmp/appmap, relative to the process working directory. Be sure that you know that the working directory of the application server is! You’ll need to know this to find and open your AppMap Diagrams.

When you use remote recording, the HTTP “stop” command responds with the AppMap in the response payload. It’s up to the client to decide where to write the file. For example, you can start and stop a remote recording using cURL, and write the output of the “stop” command to a file of your choosing.

When you use code block recording, it’s up to you in your code snippet to write the AppMap to a file. Naturally, you can direct the data anywhere you please.

AppMap files conform to the AppMap specification, which is freely available on GitHub.

Running in containers

You can make AppMap Data while running your application in a container. From the AppMap standpoint, there is really no difference between running in a container and running in any other environment. There are just a couple of basic considerations:

  • The AppMap file will be written to the filesystem of the container. To make it available to the host, you should either use a volume mount to the $appmap_dir (typically, tmp/appmap), or copy the AppMap Data out of the container after the recording is complete.
  • If you are using remote recording, your application web port should be exposed to the host, so that you can send the HTTP start and stop commands. You’ll need this anyway, in order to access your application’s web UI or API from the host.

Viewing AppMap Diagrams

AppMap includes open-source UI tools to display AppMap Data as visual diagrams. Built-in diagrams include:

  • Dependency map
  • Sequence diagram
  • Trace view
  • Flame graph

These diagrams are integrated together in the AppMap UI, and fully interactive. The data can be organized, selected, and filtered by the user. This makes the user interface much better suited for code investigation than a static diagram image. It’s also much more scalable, because the diagrams can be tuned to reveal specific information and hide extraneous data.

IDE extensions

The AppMap extensions for VSCode and JetBrains include a file association for AppMap Data. Just click on an AppMap file, and it will be opened graphically in the code editor. The diagram is fully linked to source code within the IDE.

Hosting an AppMap viewer

The AppMap Diagrams are published as an open source library on NPM. If you want to provide a centralized service to open AppMap Diagrams in the browser, you can just serve appmap.html from any web server. Provide a URL to the AppMap Data using the appmap parameter - for example: http://myappmapserver/appmap.html?appmap=https://<appmap-url>.

Exporting AppMap Data

The AppMap sequence diagram can be exported to SVG or PlantUML. Consult the diagrams reference for details.

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