Java Agent Configuration

Drill4J Java Agent is using JVMTI interface to analyze and instrument Application Under Test(AUT) in runtime.

Download#

Java Agent has two parts two it - JVM in .jar and native in either .dll or .so depending on the platform.

Pick the platform appropriate release depending on where Application Under Test runs:

Currently Linux and Windows are supported
There are caveats to Alpine support

Start the agent#

You have to provide the following string to java command running your Application Under Test:

You can either directly bake it into java launch like that

java -agentpath:/data/agent/libdrill_agent.so=drillInstallationDir=/data/agent,adminAddress=wss://drill-admin:8090,agentId=my-app-backend,groupId=my-app-under-test,buildVersion=0.1.0,logLevel=INFO,packagePrefixes=io/spring -jar my-app.jar
# .so is for linux, swap for .dll if running under Windows
# ! IMPORTANT ! make sure to change value of packagePrefixes=io/spring to your application package prefix
#               separated by "/" instead of "."
#               example: your app consists of my.org.project.moon.user, my.org.project.moon.orders, my.org.project.moon.logic
#                        set package prefixes to my/org/project/moon

But more elegant and handier way is to use JAVA_TOOL_OPTIONS env variable which is picked up by Java automatically

JAVA_TOOL_OPTIONS=-agentpath:/data/agent/libdrill_agent.so=drillInstallationDir=/data/agent,adminAddress=wss://drill-admin:8090,agentId=my-app-backend,groupId=my-app-under-test,buildVersion=0.1.0,logLevel=INFO,packagePrefixes=io/spring"

Using JAVA_TOOL_OPTIONS option also allows to add Drill4J Java Agent to any Java app running inside Docker container without alterting the image.
This enables you to easily integrate Drill4J into any testing environment seamlessly - no need to rebuild the image, no need to deploy separate env to collect metrics

Delivery options#

Manual#

You can simply download Drill4J Java Agent from its github releases page and place them next to App Under Test jar

Docker Shared Volume#

When running under Docker it can be handier to use our small image, that runs a script to download these files into shared volume:

version: '3'
services:
  
  # The sole function of this container is to download agent files
  # according to version specified in AGENT_VERSION env variable
  # and place them into volume named agent-files
  agent-files:
    image: drill4j/java-agent:latest
    environment:
      - AGENT_VERSION=${AGENT_VERSION} 
    volumes:
      - agent-files:/data

volumes:
  # you can attach this volume to your Application Under Test for ease of access to agent files
  agent-files:

Kubernetes Init Container#

When running in Kubernetes consider using init containers to download agent files from github and make them available for pod running App Under Test

Purpose#

Drill4J Java Agent is responsible for multiple tasks:

Analyze application's packages, classes, methods and send metadata (not the actual code) to Drill4J Admin Backend
Instrument AUT code to enable code execution tracking (in other words, code coverage)
Analyze incoming requests to extract tests context (supplied, for example, by either Drill4J Java Agent or Browser Extension)

See Data Colletion for a comprehensive in-depth summary