AppMap Java Cheat Sheet

This is a quick reference guide for using the AppMap agent for Java.

Setup and Installation

The AppMap agent is a .jar file that attaches to the JVM. The AppMap IDE extensions (for VS Code or IntelliJ) will automatically download it for you. You can also use the Maven or Gradle plugins.

IntelliJ IDEA

The easiest way to record in IntelliJ is to use the built-in run actions.

Test Recording: Right-click on a test file, class, or method and select "Record AppMaps".
Request/Remote Recording: Right-click on your main class or Spring Boot entry point and select "Start with AppMap".

VS Code

The VS Code extension provides similar commands for running and recording.

Maven Plugin

Add the AppMap Maven plugin to your pom.xml to automatically run the agent during the test phase.

<plugin>
    <groupId>com.appland</groupId>
    <artifactId>appmap-maven-plugin</artifactId>
    <version>LATEST</version>
    <executions>
        <execution>
            <phase>process-test-classes</phase>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <phase>test</phase>
            <goals>
                <goal>test</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Gradle Plugin

Use the AppMap Gradle plugin by applying it in your build.gradle file.

plugins {
  id "com.appland.appmap" version "1.2.0"
}

Manual Setup (Command Line)

Run your application with the -javaagent JVM argument. The AppMap IDE extensions store the agent at $HOME/.appmap/lib/java/appmap.jar.

java -javaagent:$HOME/.appmap/lib/java/appmap.jar -jar myapp.jar

Configuration (`appmap.yml`)

Create an appmap.yml file in your project root to define what code to record.

# The name of your application
name: MyJavaProject
language: java

# Directory to save AppMaps into
appmap_dir: tmp/appmap

# List of packages to instrument
packages:
  # Instrument your application's main package
  - path: com.mycorp.myproject
    # Exclude specific classes or methods
    exclude:
      - com.mycorp.myproject.MyClass#MyMethod

  # You can record library packages with shallow recording
  # to see interactions without deep internal details.
  - path: org.springframework.web
    shallow: true

Recording Methods

Test Recording

This is the most common way to create AppMaps. It's handled automatically by the IDE actions or build tool plugins.

Request Recording

For supported web frameworks (Spring Boot, Spring Web, Spark), AppMap automatically records each HTTP request when the agent is attached.

To disable this, use the system property -Dappmap.recording.requests=false.

Remote Recording

Start your application with the AppMap agent attached (e.g., using "Start with AppMap" in IntelliJ or the -javaagent flag). You can then use the AppMap extension in your IDE to start and stop recordings on demand.

Process Recording

Record the entire execution of a JVM process from start to finish by setting a system property.

java -javaagent:$HOME/.appmap/lib/java/appmap.jar -Dappmap.recording.auto=true -jar myapp.jar

Code Block Recording

Record a specific block of code using the Recorder class.

import com.appland.appmap.record.Recorder;
import com.appland.appmap.record.Recording;

// ...

final Recorder recorder = Recorder.getInstance();

Recording recording = recorder.record(() -> {
  // ... code to be recorded ...
  System.out.println("This block is being recorded.");
});

// Manually save the recording to a file
String appmapJson = recording.toJson();
// ... write appmapJson to a file ...

Annotations

Add the com.appland:appmap-annotation:1.28.0 dependency to use annotations.

Maven:

<dependency>
    <groupId>com.appland</groupId>
    <artifactId>appmap-annotation</artifactId>
    <version>LATEST</version>
    <scope>provided</scope>
</dependency>

@Labels({"label1", "label2"}): Adds labels to a method in the AppMap metadata.

import com.appland.appmap.annotation.Labels;

@Labels({"security", "provider.authentication"})
public void myAuthMethod() { /* ... */ }

@NoAppMap: Disables AppMap generation for a specific JUnit test method or an entire test class.

import com.appland.appmap.annotation.NoAppMap;

@NoAppMap
@Test
public void testThatShouldNotBeRecorded() { /* ... */ }

Key System Properties

Pass these to the JVM using the -D<property>=<value> syntax.

Property	Description	Example
`appmap.config.file`	Path to the `appmap.yml` config file.	`-Dappmap.config.file=config/appmap.yml`
`appmap.output.directory`	Output directory for `.appmap.json` files.	`-Dappmap.output.directory=build/appmaps`
`appmap.recording.auto`	Set to `true` to automatically record the entire process at boot time.	`-Dappmap.recording.auto=true`
`appmap.recording.requests`	Set to `false` to disable automatic recording of HTTP server requests.	`-Dappmap.recording.requests=false`
`appmap.debug`	Set to `true` or a level (`info`, `debug`, `trace`) to enable debug logging.	`-Dappmap.debug=true`

Find the full documentation at AppMap Agent for Java Docs.

dividedmind/appmap-java-cheatsheet.md