Application Agent

Drill4J Java Agent enables metrics collection for JVM-based applications.

General integration steps are:

1. Download Drill4J agent files
2. Set path to agent
3. Set agent parameters

Due to the diverse tools used in software development — such as CI/CD providers, deployment methods, testing stages — the exact process will depend on the environment.

How to download

Download agent files manually

The most basic way to get agent files is to download release .zip manually.

1. Download release appropriate for your platform at

   https://github.com/Drill4J/java-agent/releases/tag/v0.9.4

   mingwX64 is for Windows, Linux and Mac releases are called respectively.

2. Unzip the file. Rename unzipped folder to agent.

3. Inside you'll find the following files:

   • libdrill_agent.so (on Windows - .dll, on Mac - .dylib)
   • drill-runtime.jar
   • drill.properties

Refer to next section for further steps.

Use Docker image with a download script

Use case: when you are already using Docker Compose to start your application.

We provide a small Docker image, that executes download script upon startup.

The way it works is:

1. You add our container to your docker-compose.yml file, passing the desired version to JAVA_AGENT env variable.
2. On startup, the container launches the download script.
3. Docker's healthcheck waits for it to complete.
4. Downloaded agent files are placed in a shared volume.
5. Shared volume is mounted to your application's container.

See the example docker-compose.yml file for details.

Use Drill4J CI/CD Integration Plugin for Maven and Gradle

Use cases: when application (or certain classes of application) is launched with Maven or Gradle. Thats most often the case with Unit tests.

Drill4J CI/CD Integration Plugin automatically downloads agent files and passes required parameters to Java.

Because of that, the next sections of this page are irrelevant in this scenario. Instead, please refer to CI/CD Integration Plugin page for more info.

How to set path to agent

Java allows to load agents using special command line argument:

java -agentpath:<path-to-agent>

Where <path-to-agent> must point to agent library file.

There are two way to set this command line argument.

Pass -agentpath: directly to Java process

Use case: when you have a direct access to Java's process launch arguments.

Considering your application is launched with:

java -jar my-app.jar

Change it to:

# Linux

java -agentpath:/agent/libdrill_agent.so -jar my-app.jar

# Windows

java -agentpath:/agent/drill_agent.dll -jar my-app.jar

# macOS

java -agentpath:/agent/libdrill_agent.dylib -jar my-app.jar

Set -agentpath to JAVA_TOOL_OPTIONS env variable

Use case: when you don't have direct access to the Java's process launch arguments. It's often the case when app is launched somewhere deep in scripts or inside Docker container.

Use JAVA_TOOL_OPTIONS to instruct Java to use Drill4J Java Agent. Its a built-in env variable supported by any Java version.

JAVA_TOOL_OPTIONS=-agentpath:/agent/libdrill_agent.so

# Linux - libdrill_agent.so

# Windows - drill_agent.dll

# macOS - libdrill_agent.dylib

Troubleshooting

To ensure you set agentpath correctly see how to confirm agent is loaded section below.

How to set agent parameters

Drill4J agent supports 3 ways to set agent parameters

Set parameters using environment variables

This is the recommended way to set agent parameters.

Env variables names are prefixed with DRILL_ with uppercase snake case. Examples:

• Given packagePrefixes parameter the env variable is DRILL_PACKAGE_PREFIXES

Precedence: parameter values set with env variables have the highest precedence and will override values set in -agentpath string or drill.properties file.

Set parameters in -agentpath argument string

Append parameters to the -agentpath argument string. Add =<options> after <path-to-agent>:

-agentpath:<path-to-agent>=<options>

Example:

-agentpath:/agent/libdrill_agent.so=parameter1=hello,parameter2=bar

Parameters are:

• passed after <path-to-agent> (/agent/libdrill_agent.so above)
• start of parameters string is indicated with = sign
• parameters are <key>=<value> pairs
• each pair is separated by comma.

Precedence: parameter values set with -agentpath will override values set in drill.properties

Set parameters in drill.properties file

Alternatively, Drill4J agent checks for values in drill.properties file. By default it is downloaded with agent files.

parameter1=hello

parameter2=bar

It adheres to the properties file syntax

Precedence: parameter values set in drill.properties file have the lowest precedence and can be overriden by -agentpath and env variables.

Agent parameters reference

Parameter	Required	Example Value	Description
apiUrl	yes	http://localhost/api	URL to Drill4J Admin /api endpoint.
apiKey	yes	1_01cdf51ff20544ee...	Drill4J Backend API key. Generate it using Drill4J UI. Please make sure to read the apiKey security section
groupId	yes	my-cool-app	Unique arbitrary string identifying your application group.
appId	yes	api-service	Unique arbitrary string identifying your application.
packagePrefixes	yes	my/org/somecoolapp	Specifies the packages for Drill4J to monitor. See syntax and examples below.
buildVersion	recommended see more	v1.2.3	Build version of your application. Typically set to version tag.
commitSha	recommended see more	8d87b0c2379a925...	Full SHA hash of commit from which your application .jar is built from.
scanClassDelay	no	5000	Time in milliseconds to delay the class scanning procedure. If none is specified, the class scanning starts immediately upon JVM startup
scanClassPath	no		Path(s) to application's .jar/.war/.ear files. If none are specified, the agent attempts to find application classes automatically. See syntax and examples below.

Env variables naming

Environment variables start with the prefix DRILL_, followed by the parameter name in UPPERCASE_SNAKE_CASE.

Example:

1. For apiUrl, the env var is DRILL_API_URL.
2. For packagePrefixes, the env var is DRILL_PACKAGE_PREFIXES.

How to set package prefixes

packagePrefixes is the filter that specifies which packages Drill4J should monitor. It is usually set to the topmost common package of your application.

Avoid setting it to something very broad (like com or org) - otherwise you will be scanning and collecting metrics for third-party dependencies.

Syntax

1. Parts of package names are separated with forward slashes / (and not dots .)
2. Multiple packages can be specified using ; delimiter
3. To exclude package use ! prefix.

Example

Given you app packages are:

1. my.org.somecoolapp.user
2. my.org.somecoolapp.orders.repository
3. my.org.somecoolapp.db.models

packagePrefixes parameter should be set to my/org/somecoolapp

Adding extra package

Add package name separated by ; - my/org/somecoolapp;some/other/package.

This adds both my/org/somecoolapp and some.other.package to scanned packages.

Excluding package

Add package name prefixed with ! - my/org/somecoolapp;!my.org.somecoolapp.db.models.

This adds my/org/somecoolapp to scanned packages, but excludes my.org.somecoolapp.db.models.

How to set scanClassPath

Specifies path(s) for the application agent to look for .jar, .war, or .ear files

Useful when the application agent is unable to locate these automatically (e.g. when running Wildfly or Tomcat)

# Single path

scanClassPath=../webapps/my-app.war

# Multiple paths - use the ";" delimiter

# scanClassPath=../webapps/my-app.war;../webapps/other-app.war

# Absolute paths work too

# scanClassPath=C:/java/tomcat-10/webapps/helloworld.war

API key security

❗ Please avoid hardcoding apiKey and exposing it in plain text. Instead, use environment variables. ❗

Bad example:

-agentpath:/agent/libdrill_agent.so=drillApiKey=123

Good example:

# Set DRILL_API_KEY variable prior to application launch

DRILL_API_KEY=123

# exact syntax for env variables will depend on your environment

Considerations regarding buildVersion and commitSha

1. Necessity: While buildVersion and commitSha are not strictly required, we recommend providing at least one (ideally both) for the following reasons:

   • It allows Drill4J to group metrics by version or commit.
   • Without buildVersion and commitSha, Drill4J reports each application instance individually. Instances are identified with a random UUID.

2. Uniqueness: Both buildVersion and commitSha identify a unique application version, each associated with a specific set of classes and methods.

   To maintain the integrity of metrics, ensure that different application versions do not share the same buildVersion or commitSha values.

   Using identical values across different versions will lead to inaccurate metrics due to the mixing of unrelated data.

3. Semantics: buildVersion typically corresponds to the version tag of your application.

   Compliance with Semver is not required. Drill4J treats the build version as a unique string for grouping metrics, without any added semantics.

Troubleshooting

How to confirm agent is loaded

Once loaded Drill4J agent prints the following ASCII logo:

____ ____ _ _ _ _ _

| _"\U | _"\ u ___ |"| |"| | ||"| U |"| u

/| | | |\| |_) |/ |_"_| U | | u U | | u | || |_ _ \| |/

U| |_| |\| _ < | | \| |/__ \| |/__ |__ _| | |_| |_,-.

|____/ u|_| \_\ U/| |\u |_____| |_____| /|_|\ \___/-(_/

|||_ // \\_.-,_|___|_,-.// \\ // \\ u_|||_u _//

(__)_) (__) (__)\_)-' '-(_/(_")("_)(_")("_) (__)__) (__)

Java Agent (v0.9.1)

It indicates that you have configured agent path correctly and Java picked up and loaded agent files.

Cannot load the agent because some agent parameters are set incorrectly

If below Drill4J ASCII logo you see the following message:

ERROR [com.epam.drill.agent.configuration.ValidatedParametersProvider] Cannot load the agent because some agent parameters are set incorrectly. Please

check the following parameters:

It indicates that you are missing some required parameters. Refer to the agent parameters section.

Error "Could not create an Appender of type ..."

|-ERROR in com.epam.drill.autotest.shadow.ch.qos.logback.core.joran.action.AppenderAction - Could not create an Appender of type [ch.qos.logback.core.ConsoleAppender].

|-ERROR in com.epam.drill.autotest.shadow.ch.qos.logback.core.joran.spi.Interpreter@5:73 - ActionException in Action for tag [appender]

The following error can be safely ignored as it doesn’t impact the functionality of the application or agent. It simply indicates that Logback is being used with a logback.xml file, which conflicts with the Drill4J logging configuration. However, logging will still function as expected.