appmap-java is a Java agent for recording
AppMaps of your code. “AppMap” is a data
format which records code structure (modules, classes, and methods), code
execution events (function calls and returns), and code metadata (repo name,
repo URL, commit SHA, labels, etc). It’s more granular than a performance
profile, but it’s less granular than a full debug trace. It’s designed to be
optimal for understanding the design intent and structure of code and key data
flows.
There are several ways to record AppMaps of your Java program using the appmap
agent:
AppMap.record API, which returns JSON containing the
code execution trace.Once you have made a recording, there are two ways to view automatically generated diagrams of the AppMaps.
The first option is to load the diagrams directly in your IDE, using the AppMap for IntelliJ IDEA or AppMap for Visual Studio Code.
The second option is to upload them to the AppMap Cloud using the AppMap Cloud CLI.
When you run your program, the agent reads configuration settings from
appmap.yml. Here’s a sample configuration file for a typical Java project:
# 'name' should generally be the same as the code repo name.
name: MyProject
packages:
- path: com.mycorp.myproject
- exclude: com.mycorp.myproject.MyClass#MyMethod
packages
Each entry in the packages list is a YAML object which has the following keys:
We recommend using the AppMap Maven plugin.
We recommend using the AppMap Gradle plugin.
Download the latest release from https://github.com/applandinc/appmap-java/releases.
The recorder is run as a Java agent. Currently, it must be started along with
the JVM. This is typically done by passing the -javaagent argument to your
JVM. For example:
java -javaagent:lib/appmap.jar myapp.jar
appmap.config.file Path to the appmap.yml config file. Default:
appmap.yml
appmap.output.directory Output directory for .appmap.json files. Default:
./tmp/appmap
appmap.debug Enable debug logging. Default: null (disabled)appmap.event.valueSize Specifies the length of a value string before
truncation occurs. If set to 0, truncation is disabled. Default: 1024
appmap.recording.auto Automatically begin recording at boot time. Default:
false
appmap.recording.file The file name of the automatic recording to be
emitted. Note that the file name will still be prefixed by
appmap.output.directory. Default: $TIMESTAMP.appmap.json
appmap.recording.name Populates the metadata.name field of the AppMap.
Default: $TIMESTAMP
When running test cases with the agent attached to the JVM, methods marked with
JUnit’s @Test annotation will be recorded. A new AppMap file will be created
for each unique test case.
To disable recording for a particular JUnit test (for example, a performance
test), list the class or methods under an exclude in appmap.yml.
The agent will hook an existing servlet, serving HTTP requests to toggle recording on and off. These routes are used by the AppMap browser extention.
GET /_appmap/recordRetreive the current recording status
Status 200
Body application/json
{
"enabled": boolean
}
POST /_appmap/recordStart a new recording session
Status 200 If a new recording session was started successfully 409 If an
existing recording session was already in progess
Body Empty
DELETE /_appmap/recordStop an active recording session
Status 200 If an active recording session was stopped successfully, and
the body contains AppMap JSON 404 If there was no active recording session to
be stopped
Body If successful, AppMap data is returned.
application/json
{
"version": "1.x",
"metadata": {},
"classMap": [],
"events": []
}
https://github.com/applandinc/appmap-java
https://app.land can be used to store, analyze, and share AppMaps.
For instructions on uploading, see the documentation of the AppMap Cloud CLI.