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

  1. Creates the spiderSense extension, which is the spiderSense { } block.

  2. Creates the spiderSense configuration, resolvable and not consumable, non-transitive, with one default dependency: net.benelog.spidersense:spider-sense:<version>, where version is 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') }.

  3. Attaches to every JavaExec or Test task whose name is in attachTo (default bootRun, bootTestRun, run) by adding a CommandLineArgumentProvider to the task’s jvmArgumentProviders. A name in attachTo that 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 in attachTo, a task that runs on a Java older than 17 (Java versions), or a run with spiderSense.enabled false, gets nothing: no argument, no jar resolution. The plugin adds a provider and never edits jvmArgs, so the task’s own jvmArgs stay as the build wrote them. The arguments are computed when the task runs, so a spiderSense { } block anywhere in the build file, before or after tasks.named('bootRun'), is seen.

  4. Registers the tasks spiderSense, spiderSenseInit and spiderSenseCheck in the group Spider Sense, which ./gradlew tasks lists 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

enabled

Boolean

true

nothing is attached when false; the project property spiderSense.enabled (-PspiderSense.enabled=false, or =true) wins over the block

version

String

the plugin’s version

the version of net.benelog.spidersense:spider-sense the default dependency names

jar

RegularFile

unset

the jar to attach instead of resolving one; the project property spiderSense.jar (-PspiderSense.jar=/path/to/spider-sense.jar) wins over the block

attachTo

Set<String>

bootRun, bootTestRun, run

the names of the JavaExec and Test tasks that get the agent; attachTo.add('test') keeps the defaults and adds test, attachTo = ['test'] replaces them

configFile

RegularFile

unset

-Dspidersense.config=, the file’s absolute path: a properties file of spidersense.* keys the launcher reads. Every other property of the block wins over a key in the file.

service

String

project.name

-Dspidersense.service=, which is otel.service.name unless that is set already. It therefore wins over Spring Boot’s spring.application.name, which the OpenTelemetry agent reads only when no otel.service.name is set; service = 'spring-orders' names the service after the application instead

testService

String

service + -test

-Dspidersense.service= for a Test task in attachTo, in place of service (Tests)

port

Integer

unset (4000)

-Dspidersense.port=

host

String

unset (127.0.0.1)

-Dspidersense.host=

collector

String

unset

-Dspidersense.collector=: forward to that Spider Sense instead of embedding one

db

String

unset (~/db/spider-sense/sense)

-Dspidersense.db=

retentionHours

Integer

unset (24)

-Dspidersense.retention.hours=

slowRequestMs

Long

unset (500)

-Dspidersense.slow.request.ms=

slowQueryMs

Long

unset (100)

-Dspidersense.slow.query.ms=

open

Boolean

unset (false)

-Dspidersense.open=: open the UI in the browser at startup, the collector’s when collector is set

appPackages

List<String>

unset

-Dspidersense.app.packages=, the list joined with commas

ignoreEndpoints

List<String>

unset (the jar’s default list)

-Dspidersense.ignore.endpoints=, the list joined with commas; an empty list set explicitly (ignoreEndpoints = []) passes an empty value, which ignores nothing

retentionSpans

Long

unset (1000000)

-Dspidersense.retention.spans=

maxSpansPerSecond

Long

unset

-Dspidersense.ingest.max-spans-per-second=

sourceDirs

List<String>

unset (the jar’s default roots)

-Dspidersense.source.dirs=, the list joined with commas; relative paths are against the task’s working directory, the project’s; an empty list set explicitly (sourceDirs = []) passes an empty value, which names no root

check { }

a nested block

see Check as a build step

the rules of the spiderSenseCheck task

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 -javaagent and the block’s options, as What applying it does describes.

17 to 24

Attaches them too, and the agent starts no UI in the application’s JVM (Java versions). Without a collector in the block the build prints one warning, because the telemetry then goes only to a Spider Sense that already listens at the block’s port.

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

since

String

--since=; default start

until

String

--until=

service

String

--service=; default the block’s service

endpoint

String

--endpoint=

maxP95Ms

Long

--max-p95-ms=

maxErrors

Long

--max-errors=

maxErrorRate

Double

--max-error-rate=

maxQueriesPerRequest

Double

--max-queries-per-request=

maxSlowQueries

Long

--max-slow-queries=

maxNPlusOne

Long

--max-n-plus-one=

maxLogErrors

Long

--max-log-errors=

maxRegressions

Long

--max-regressions=

minApdex

Double

--min-apdex=

failOnNoRequests

Boolean

default true: exit code 3 (no request in the window) fails the build too, because it means the exercise step sent no request, not that the rules passed

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.