AppMap for Java

• AppMap for Java
  • About
    • Supported versions
  • Configuration
  • Recording test cases
    • Recording tests with Maven
    • Recording tests with Gradle
    • Other situations
  • Remote recording
  • System Properties
  • GitHub repository

About

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:

• Run your tests (JUnit, TestNG) with the Java agent. An AppMap will be generated for each test.
• Run your application server with AppMap remote recording enabled, and use the AppMap browser extension to start, stop, and upload recordings.
• Record the code with 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.

Supported versions

Supported Java versions: JDK 8, 11

Configuration

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

• name Provides the project name (required)
• packages A list of packages, classes and methods which should be instrumented.

packages

Each entry in the packages list is a YAML object which has the following keys:

• path A Java package, class or methods that will be included in the instrumentation.
• exclude A list of sub-packages, sub-classes and sub-methods that will be ignored. The exclude list only applies to the path specified in the same package entry.
• shallow When set to 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: false.

Recording test cases

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.

Recording tests with Maven

We recommend using the AppMap Maven plugin.

Recording tests with Gradle

We recommend using the AppMap Gradle plugin.

Other situations

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

Remote recording

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.

System Properties

• 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

GitHub repository

https://github.com/applandinc/appmap-java