ta-bruce/appmap-java

Inspect and record the execution of Java for use with App Land

AppLand AppMap Recorder for Java

• Building
• Running
  • Other examples
    • Maven
    • Maven Surefire
    • Gradle
• System Properties
• Operation
  • Recording test cases
  • HTTP recording controls
    • GET /_appmap/record
    • POST /_appmap/record
    • DELETE /_appmap/record
• Developing
  • Testing
• Build status

Building

Artifacts will be written to build/libs. Use appmap.jar as your agent.

$ ./gradlew build

Running

The AppMap 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

Other examples

Maven

$ mvn -DargLine="-javaagent:lib/appmap.jar" test

Maven Surefire

<plugin>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <argLine>-javaagent:${session.executionRootDirectory}/lib/appmap.jar</argLine>
  </configuration>
<plugin>

Gradle

test {
  jvmArgs "-javaagent:$rootDir/lib/appmap.jar"
}

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: disabled
• appmap.event.valueSize Specifies the length of a value string before truncation occurs. If set to 0, truncation is disabled. Default: 1024

Operation

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 AppMap for a particular JUnit test (for example, a performance test), list the class or methods under an exclude in appmap.yml.

HTTP recording controls

AppMap will hook an existing servlet, serving HTTP requests to toggle recording on and off. These routes are used by the AppLand browser extention.

GET /_appmap/record

Retreive the current recording status

Status
200

Body
application/json

{
  "enabled": boolean
}

POST /_appmap/record

Start 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/record

Stop 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, scenario data is returned.

application/json

{
  "version": "1.x",
  "metadata": {},
  "classMap": [],
  "events": [],
}

Developing

The Spring PetClinic provides a convenient way to develop on appmap-java.

Obtain the spring-petclinic JAR file, and launch it with the AppMap Java agent:

$ export PETCLINIC_DIR=<path-to-petclinic>
$ java -Dappmap.debug \
  -javaagent:build/libs/appmap.jar \
  -Dappmap.config.file=test/appmap.yml \
  -jar $(PETCLINIC_DIR)/target/spring-petclinic-2.2.0.BUILD-SNAPSHOT.jar

You can use Java remote debug settings to attach a debugger:

$ export PETCLINIC_DIR=<path-to-petclinic>
$ java -Dappmap.debug \
  -javaagent:build/libs/appmap.jar \
  -Dappmap.config.file=test/appmap.yml \
  -Xdebug \
  -Xrunjdwp:server=y,transport=dt_socket,address=5005,suspend=y \
  -jar $PETCLINIC_DIR/target/spring-petclinic-2.2.0.BUILD-SNAPSHOT.jar

Testing

Unit tests are run via the test task.

Docker is required to run integration tests. Run the following command:

$ ./bin/test