getappmap / appmap-java

AppMap client agent for Java

• About
• Usage
• Development
  • Building
  • Testing

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.

Usage

Visit the AppMap for Java reference page on AppLand.com for a complete reference guide.

Development

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

Obtain the spring-petclinic JAR file, and launch it with the AppLand 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

Building

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

./gradlew build

Testing

Unit tests

Unit tests are run with ./gradlew test.

Integration tests

The integration tests use bats and Docker.

Run the following command:

./bin/test

To get an interactive shell to write/debug the tests, try:

./bin/test /bin/bash

Once in the shell, run:

DEBUG_JSON=true bats --tap /test/*.bats

Or:

DEBUG_JSON=true bats --tap /test/*.bats -f 'http'