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
There are several ways to record AppMaps of your Java program using the
AppMap.recordAPI, 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.
Supported Java versions: JDK 8, 11
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 ] - path: org.springframework.web shallow: true exclude: - org.springframework.web.util
Each entry in the
packages list is a YAML object which has the following keys:
pathspecified in the same package entry.
true, only the first function call entry into a package will be recorded. Subsequent function calls within the same package are not recorded unless code execution leaves the package and re-enters it. Default:
When running test cases with the agent attached to the JVM, methods marked with
@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.
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 when recording tests. For example:
java -javaagent:lib/appmap.jar myapp.jar
appmap-java supports the AppMap remote recording API.
This functionality is provided by the AppMap agent. It will hook an existing servlet, serving HTTP requests to toggle
recording on and off.
To run your Java application with remote recording enabled, add the
-javaagent JVM parameter to the startup parameters of your application. For example:
java -javaagent:/Users/JavaPowerUser/.m2/repository/com/appland/appmap-agent/1.5.0/appmap-agent-1.5.0.jar -jar target/*.jar
To setup your Java application for remote recording and make a remote recording, follow the Remote recording documentation.
appmap.config.filePath to the
appmap.ymlconfig file. Default: appmap.yml
appmap.output.directoryOutput directory for
appmap.debugEnable debug logging. Default:
appmap.event.valueSizeSpecifies the length of a value string before truncation occurs. If set to
0, truncation is disabled. Default:
appmap.recording.autoAutomatically begin recording at boot time. Default:
appmap.recording.fileThe file name of the automatic recording to be emitted. Note that the file name will still be prefixed by
metadata.namefield of the AppMap. Default: