Record scenarios for Java projects

  1. Install the AppMap Java agent

    JAR
  2. Configure your project

  3. Record scenarios

    { } appmap JSON

Step 1: Install the AppMap Java agent

Download the most recent appmap.jar from GitHub to your $HOME directory (or other suitable directory) to use in your project.

Step 2: Configure your project

Create a file called appmap.yml in the root directory of your project. When you run your program, the appmap agent will read configuration settings from this file.

A sample configuration file for a typical Java project is provided below.

Customize the sample by providing an application name:

name: 
packages: - path: com.mycorp.myproject

Code that doesn’t match a path entry in appmap.yml is not recorded. It’s basically a way to tell AppLand which code is “your code” vs “other / library code.” For more information and to see advanced configurations of appmap.yml check out the README.

Organizational Scoping

An organization in AppLand is a place where you and your team can access a shared group of applications. To create a new organization or view your organization memberships, check out the Organizations section of your account settings.

To upload data to an application that is owned by an organization you belong to, include the organization name in the name parameter (name: my-org/my-app).

By omitting the organization name, data will be uploaded to your own personal account.

If you're looking for the name of an existing application, visit the home page for a list of applications that you have access to.

Step 3: Record scenarios

The AppMap recorder is run as a Java agent. It must be started along with the JVM. This is typically done by passing the -javaagent argument to your JVM.

For example, running a raw Java command:

java -javaagent:$HOME/appmap.jar <java command arguments>

Check the README for other examples.

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.json 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. By default each test will output an appmap.json data file to the current working directory.

Other system properties can be used to configure the AppMap Java agent. These properties allow you to control where the agent should find appmap.yml as well as the directory where the AppMap files should be created.