The Gradle Plugin
The net.benelog.spidersense plugin puts -javaagent: on the JVM that Gradle forks for bootRun or run, so an application starts under Spider Sense with no path and no JVM argument in the build file.
Spider Sense is a -javaagent, so it has to be on the command line of the JVM that runs the application.
Gradle forks that JVM itself for bootRun and run, and the option has to reach the forked JVM, not Gradle’s own.
This page covers only getting the jar onto that command line.
The jar’s own options are in Configuration, and the modes it runs in are in The Three Modes.
plugins {
id 'org.springframework.boot' version '4.1.1'
id 'net.benelog.spidersense' version '0.1.0'
}
./gradlew bootRun
That is the whole setup. The application starts under Spider Sense, named after the project, and the UI is at http://127.0.0.1:4000.
The plugin resolves the jar from Maven Central through the project’s repositories, as net.benelog.spidersense:spider-sense:0.1.0 at the plugin’s own version.
mavenCentral() therefore has to be among them, as it is in every Spring Boot project.
The plugin itself is a plain Gradle plugin, published to Maven Central with its marker.
The Gradle Plugin Portal proxies Maven Central, so the default pluginManagement finds the plugin.
The plugin applies no other plugin and changes no task outside attachTo.
It works the same with the application plugin’s run task.
A project with neither Spring Boot nor application gets the spiderSense block and the three tasks, and no task gets the agent.
A build that cannot take a new plugin puts the argument on the task itself, with an absolute path to the jar:
tasks.named('bootRun') {
jvmArgs '-javaagent:/absolute/path/to/spider-sense-0.1.0.jar', '-Dotel.service.name=spring-orders'
}
What applying it does
-
Creates the
spiderSenseextension, which is thespiderSense { }block. -
Creates the
spiderSenseconfiguration, resolvable and not consumable, non-transitive, with one default dependency:net.benelog.spidersense:spider-sense:<version>, whereversionis the block’s property and defaults to the plugin’s own version. A dependency added to the configuration by the build replaces the default. A project in a checkout of this repository uses the jar it just built this way:dependencies { spiderSense project(path: ':spider-sense-agent', configuration: 'senseJar') }. -
Attaches to every
JavaExecorTesttask whose name is inattachTo(defaultbootRun,bootTestRun,run) by adding aCommandLineArgumentProviderto the task’sjvmArgumentProviders. A name inattachTothat is neither kind of task attaches nothing. The provider contributes-javaagent:<jar>first, then one-Dspidersense.<key>=<value>per property of the block that has a value. The jar is a declared input of the task, so a project dependency on it is built first. A task that is not inattachTo, a task that runs on a Java older than 17 (Java versions), or a run withspiderSense.enabledfalse, gets nothing: no argument, no jar resolution. The plugin adds a provider and never editsjvmArgs, so the task’s ownjvmArgsstay as the build wrote them. The arguments are computed when the task runs, so aspiderSense { }block anywhere in the build file, before or aftertasks.named('bootRun'), is seen. -
Registers the tasks
spiderSense,spiderSenseInitandspiderSenseCheckin the groupSpider Sense, which./gradlew taskslists as "Spider Sense tasks".
Nothing here touches the Gradle daemon.
A jvmArgumentProvider reaches only the forked JVM.
That is the reason to use the plugin rather than JAVA_TOOL_OPTIONS.
JAVA_TOOL_OPTIONS reaches every JVM the command starts, including the daemon, which then tries to host a Spider Sense of its own on port 4000.
The block
Every property is a lazy Gradle Property.
An unset property leaves the jar’s own default in place.
Configuration lists the jar’s defaults.
| Property | Type | Default | Becomes |
|---|---|---|---|
|
|
|
nothing is attached when |
|
|
the plugin’s version |
the version of |
|
|
unset |
the jar to attach instead of resolving one; the project property |
|
|
|
the names of the |
|
|
unset |
|
|
|
|
|
|
|
|
|
|
|
unset ( |
|
|
|
unset ( |
|
|
|
unset |
|
|
|
unset ( |
|
|
|
unset ( |
|
|
|
unset ( |
|
|
|
unset ( |
|
|
|
unset ( |
|
|
|
unset |
|
|
|
unset (the jar’s default list) |
|
|
|
unset ( |
|
|
|
unset |
|
|
|
unset (the jar’s default roots) |
|
|
a nested block |
the rules of the |
The plugin looks for the jar in this order: the project property spiderSense.jar, then the block’s jar, then the single file of the spiderSense configuration.
A blank property (-PspiderSense.jar=) counts as unset.
When a task that needs the jar runs, a configuration with more than one file, or none, is an error that names the configuration.
A path from the property or the block that is not a regular file is an error too, and it names the path and which of the two gave it: The Spider Sense jar /home/me/spider-sense.jar does not exist (from -PspiderSense.jar).
The block sets only spidersense. properties.
The launcher also reads a spider-sense.properties in the project directory, because the forked JVM’s working directory is the project’s.
configFile names a different properties file.
The block’s -D properties win over the file either way (the properties file).
Every otel. property of the OpenTelemetry agent goes on the task as usual, and the block and the task’s jvmArgs combine:
spiderSense {
port = 4001
slowQueryMs = 50
appPackages = ['com.acme.orders']
}
tasks.named('bootRun') {
jvmArgs '-Dotel.instrumentation.jdbc-datasource.enabled=true'
}
Switching it off and on
./gradlew bootRun -PspiderSense.enabled=false runs the application bare.
spiderSense { enabled = false } with -PspiderSense.enabled=true reverses that: the plugin stays in the build, and attaches only when you pass the property.
An enabled of false is the same as not applying the plugin, except that the block and the tasks are still there.
Java versions
The plugin runs inside Gradle, on any Java that Gradle 9 runs on, which is 17 or later. The application runs on the Java of its task: the project’s toolchain, or the launcher the build gives the task. The plugin reads that Java from the task’s launcher when the task runs, and attaches by it:
| The task’s Java | What the plugin does |
|---|---|
25 or later |
Attaches |
17 to 24 |
Attaches them too, and the agent starts no UI in the application’s JVM (Java versions).
Without a |
16 or older |
Attaches nothing, and the build prints one warning that Spider Sense is not attached to the task. |
A task with no launcher, such as one given an executable of its own, is attached whatever its Java is, and the agent checks the version itself.
A project on Java 17 to 24 forwards to a Spider Sense on Java 25 or later, which ./gradlew spiderSense starts, since the three Spider Sense tasks run on Java 25 whatever the project’s toolchain (The tasks):
spiderSense {
collector = 'http://127.0.0.1:4000'
}
The tasks
spiderSense runs the jar exactly as java -jar spider-sense.jar would, so a project that never checked out this repository starts the standalone server and runs the CLI through this one task:
./gradlew spiderSense # the standalone collector + UI; Ctrl-C stops it
./gradlew -q spiderSense --args="findings --since=start" # the CLI; -q keeps Gradle's own lines out
./gradlew -q spiderSense --args="check --max-n-plus-one=0"
The spiderSense task is a JavaExec with the jar as its only class path, the jar’s Main-Class, net.benelog.spidersense.boot.VersionGate, as its main class, and no dependency on compiling the project.
It runs no code of the project, so it does not run on the project’s toolchain: the jar’s server and CLI need Java 25 or later, whatever Java the project compiles for.
It runs on the JVM that runs Gradle when that is Java 25 or later, and otherwise on a Java 25 toolchain, which Gradle finds among the installed JDKs or provisions as the build’s toolchain settings allow.
spiderSenseInit and spiderSenseCheck run the same way, and a build that wants another Java sets the task’s javaLauncher itself.
A javaLauncher older than Java 25 gets the line java -jar prints on it, naming the Java it found, and the task fails with exit code 2.
The block’s spidersense. properties are passed to it as they are to the application, so a standalone started this way listens where the block says.
Its service is passed as well, and a standalone ignores it: the standalone runs inside no application, so its status names no embedded service.
When the block sets no port and forwards to a collector on this machine (127.0.0.1, localhost or [::1], with a port written in the URL), the task passes the collector’s port as -Dspidersense.port=.
./gradlew spiderSense then starts the very Spider Sense the block forwards to.
Only the spiderSense task gets that port: the application forwards and listens on nothing of its own.
When the block names a collector, a host or a port, it also sets the environment variable SPIDERSENSE_URL to the base URL they imply, which is collector when set and otherwise http://<host>:<port> with the defaults filled in.
A CLI command therefore asks the Spider Sense the application is sending to rather than the default port.
When the block names none of them, the variable stays unset and the CLI’s own default applies.
That default is the URL the task’s spidersense. properties imply, so a port set in configFile or in spider-sense.properties is followed too.
java -jar on the jar by hand reads neither the block nor SPIDERSENSE_URL from the task.
When the block names a port other than 4000, add --url=http://127.0.0.1:<port> to such a command, or set the port as spidersense.port in spider-sense.properties instead, which the application and the CLI both read.
A CLI exit code other than 0 fails the task, and Gradle’s failure message names that code as the process’s exit value.
./gradlew itself exits 1 for every failed task, so a script cannot tell the CLI’s codes 1 to 4 apart through the task.
A script that branches on the code runs java -jar on the jar itself, and spiderSenseCheck fails with a message of its own for each outcome of check (Check as a build step).
spiderSenseInit runs init --dir=<the project directory> --jar=<the jar> --gradle, and adds --url=<base URL> when the block names a collector, a host or a port.
The URL is the one SPIDERSENSE_URL gets above.
It writes the Spider Sense block into the project’s CLAUDE.md and installs the skills into .claude/skills/, as The Agent Skill describes.
With --gradle the CLAUDE.md block starts the application with ./gradlew bootRun and runs every CLI command as ./gradlew -q spiderSense --args="…", so the agent asks the Spider Sense the spiderSense { } block configures.
With --url it names the UI at that URL rather than at port 4000.
The jar path it writes is where Gradle resolved the jar to.
For a Maven Central jar that is a file under ~/.gradle/caches/, which stays valid until the version changes.
Run it again after a version bump.
Check as a build step
spiderSenseCheck runs the CLI’s check with the rules of the check { } block and fails the build when the verdict is fail:
spiderSense {
check {
since = 'start' // the default: since the application was last started
maxP95Ms = 300
maxNPlusOne = 0
maxErrors = 0
}
}
./gradlew bootRun & # or forward the tests to a standalone and judge their service, as in Tests below
./gradlew test spiderSenseCheck
| Property | Type | Becomes |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
default |
spiderSenseCheck runs the jar as the spiderSense task does, with check and those arguments.
It asks the Spider Sense the block implies, through SPIDERSENSE_URL or the CLI’s own default as The tasks describes.
It prints the check’s text rendering.
Exit code 1 after the heading of a failing verdict, # check fail (The text rendering), fails the build with Spider Sense check failed.
Exit code 1 without that heading is the JVM failing rather than the check, such as a main class it could not load, and fails the build with Spider Sense check could not run (exit 1).
Exit code 3 fails it with Spider Sense check had no request to judge, unless failOnNoRequests is false.
Exit code 2 or 4 fails it with Spider Sense check could not run (exit <n>).
The CLI’s own message reaches the build log first in every case.
With no rule set the CLI’s defaults apply: maxErrors=0, maxNPlusOne=0, maxRegressions=0, maxP95Ms=<slow.request.ms>.
Setting any rule replaces that set, so a build that sets maxP95Ms and still wants regressions caught sets maxRegressions = 0 too.
-PspiderSense.check.since=before overrides since for one run.
spiderSenseCheck depends on no other task, because producing the traffic it judges is the build’s job, as in the setup of Tests.
Tests
The test task is not attached by default.
A test JVM is short-lived and may be forked several times, and only one of several embedded servers can bind the port.
To measure tests, forward them to a standalone Spider Sense: add test to attachTo and set collector, one line each.
Gradle’s test task is a Test, not a JavaExec, and the plugin attaches to both kinds.
spiderSense {
attachTo.add('test')
collector = 'http://127.0.0.1:4000'
}
./gradlew spiderSense & # once
./gradlew -q spiderSense --args="mark before"
./gradlew test --tests '*OrderServiceTest'
./gradlew -q spiderSense --args="findings --since=before"
./gradlew spiderSense starts the standalone on the collector’s port, so with a collector of http://127.0.0.1:4100 it listens on 4100 with nothing more in the block (The tasks).
attachTo.add('test') adds to the default tasks, so bootRun stays attached, and with collector set it forwards too.
That is what you want when the tests and the running application should land in one Spider Sense.
A Test task reports as testService, which defaults to the block’s service with -test after it, so the tests of the project orders are the service orders-test.
The bootRun and run tasks keep service, and so do the Spider Sense tasks.
This is the name Surefire gives tests too.
The 404s and 500s a test provokes on purpose then stay out of the application’s numbers, and spiderSenseCheck, which judges service, does not count them.
A check that judges the tests names their service:
spiderSense {
attachTo.add('test')
collector = 'http://127.0.0.1:4000'
check {
service = 'orders-test'
maxNPlusOne = 0
}
}
testService = 'orders' puts the tests back under the application’s service.
Two applications, several modules
Each module that applies the plugin gets its own block, so in a multi-project build each application is configured in its own module’s build file:
// orders/build.gradle
spiderSense { port = 4001 }
// bookstore/build.gradle
spiderSense { port = 4000 }
When one calls the other and the trace should be one trace, run a standalone and forward both:
spiderSense { collector = 'http://127.0.0.1:4000' }
Spring Boot devtools
A devtools restart replaces the application’s classes inside the same JVM. The agent stays attached, the embedded UI keeps running, and the restarted classes are instrumented like the first ones. There is nothing to configure.
A jar that is not on Maven Central
A version that is not published yet, or a jar built from a checkout, is attached in one of three ways:
./gradlew bootRun -PspiderSense.jar=/home/me/spider-sense/spider-sense-agent/build/libs/spider-sense-0.1.0.jar
spiderSense {
jar = file('/home/me/tools/spider-sense.jar')
}
// In this repository: the jar the build just made, built before bootRun runs.
dependencies {
spiderSense project(path: ':spider-sense-agent', configuration: 'senseJar')
}
./gradlew publishToMavenLocal in this repository publishes both the jar and the plugin to ~/.m2.
mavenLocal() in repositories and in pluginManagement.repositories then makes an unreleased version resolvable like a released one.
Configuration cache
The plugin is compatible with Gradle’s configuration cache.
Every value is a provider, the argument provider holds no Project, and the jar is a FileCollection input.
Coordinates
The plugin is net.benelog.spidersense:spider-sense-gradle-plugin, with the marker net.benelog.spidersense:net.benelog.spidersense.gradle.plugin, and resolves the jar net.benelog.spidersense:spider-sense at its own version.
Installation lists both artifacts and how they are published.