Installation

Spider Sense runs on Java 25 or later, and it measures an application on Java 17 or later (Java versions). It is one jar, and that jar carries the OpenTelemetry Java agent, the collector, the UI and the command line. Nothing else has to be installed: no Docker, no account, and no server to run.

Coordinates

Releases are published to Maven Central, so a build needs no repository beyond the default one. The current version is 0.1.0.

0.1.0 is not on Maven Central yet, so the coordinates below do not resolve and a download from Maven Central answers 404. Until it is published, build the jar from a checkout (From a checkout), and run ./gradlew publishToMavenLocal there for a build that resolves the jar or the plugin from mavenLocal().
Artifact Coordinates What it is

The jar

net.benelog.spidersense:spider-sense:0.1.0

The single distributable jar, built by :spider-sense-agent:senseJar. Its POM declares no dependencies.

The Gradle plugin

net.benelog.spidersense:spider-sense-gradle-plugin:0.1.0, marker net.benelog.spidersense:net.benelog.spidersense.gradle.plugin

The plugin id net.benelog.spidersense, which puts -javaagent on bootRun and run. See The Gradle Plugin.

The jar and the plugin are released together at one version, which is version in the root gradle.properties of the repository. By default the plugin resolves the jar at that same version, so a plugin and the jar it fetches are always the same release. The repository publishes both with ./gradlew publishToMavenLocal into ~/.m2, and, signed, with ./gradlew centralBundle into one bundle for the Central Portal, as RELEASING.md in the repository describes. The Gradle Plugin Portal proxies Maven Central, so the default pluginManagement finds the plugin.

This manual describes main, which is ahead of the latest release, so a feature it documents may not be in 0.1.0 yet. Build the jar from a checkout to have everything it describes.

From a checkout

git clone https://github.com/benelog/spider-sense.git
cd spider-sense
./gradlew :spider-sense-agent:senseJar

The jar is then spider-sense-agent/build/libs/spider-sense-0.1.0.jar. The spider-sense-agent-0.1.0.jar beside it is the launcher alone, a build artifact, not the jar to run. Keep the jar’s absolute path in a variable, because the commands in this manual use it:

SENSE="$PWD/spider-sense-agent/build/libs/spider-sense-0.1.0.jar"

./gradlew publishToMavenLocal puts the jar and the plugin, unsigned, into ~/.m2 at the same version. A project with mavenLocal() in repositories and in pluginManagement.repositories then resolves them as it would a release. This is how a build outside this repository uses an unreleased version.

Quick start

java -javaagent:"$SENSE" -jar build/libs/my-app-0.1.0.jar

Open http://localhost:4000. The collector and the UI run inside the application’s JVM, and the first request appears a second or two after it is served. The service is named after spring.application.name in a Spring Boot application, and otherwise after the jar without its version, my-app here. -Dotel.service.name=my-app names it explicitly, and The service name has the whole order.

java -jar "$SENSE" status checks the setup from a terminal. It names the mode, the port, the database file, the thresholds in force, the services seen and how many spans are stored.

The four ways to run it

Way Command Where it is described

The jar on the command line

java -javaagent:spider-sense.jar -jar app.jar

Agent mode, and forwarding when several applications share one UI

The Gradle plugin

id 'net.benelog.spidersense' version '0.1.0', then ./gradlew bootRun

The Gradle Plugin

Maven

mvn spring-boot:run -Dspring-boot.run.agents=/path/to/spider-sense.jar

Maven

Standalone

java -jar spider-sense.jar

Standalone mode, for anything that already speaks OTLP/HTTP, including a Java application under the stock OpenTelemetry Java agent

bootRun and spring-boot:run fork the JVM themselves, so a -javaagent typed on the ./gradlew or mvn command line does not reach the application. The Gradle plugin adds it to the arguments of the forked JVM, and the Spring Boot Maven plugin’s agents parameter does the same.

Java versions

The collector, the UI and the command line run on Java 25 or later, which is the oldest Java Spider Silk runs on. The application they measure runs on Java 17 or later, and what -javaagent:spider-sense.jar does depends on its Java:

The application’s Java What the agent does

25 or later

Either agent mode: the embedded UI, or forwarding to a Spider Sense elsewhere.

17 to 24

The OpenTelemetry agent instruments the application, and no UI starts in its JVM. The telemetry goes to the Spider Sense spidersense.collector names, or without one to the Spider Sense that already answers at spidersense.port. With neither, nothing is exported, and one line on stderr says how to forward.

8 to 16

Nothing: one line on stderr says that Spider Sense needs Java 17, and the application starts without it.

The agent never stops the application from starting, on any Java. The class the JVM loads first is built for Java 8, the oldest Java the OpenTelemetry agent supports, and it checks the version before anything else of Spider Sense loads. java -jar spider-sense.jar on a Java older than 25 prints one line that names the Java it found and exits 2.

An application on Java 17 to 24 is measured by forwarding: run Spider Sense standalone on Java 25 or later and point the application at it, as forwarding describes. The Gradle plugin reads the Java a task runs on from its toolchain and attaches accordingly (Java versions).

What to read next

The Three Modes covers starting an application that is not a plain java -jar, and what to check when nothing arrives. Configuration lists every property, including the port, the database path and the slow thresholds. The Examples starts four misbehaving applications and a load generator, so there is data to look at immediately.