Installation

Spider Sense requires Java 21 or later. 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.

Artifact Coordinates What it is

The jar

net.benelog.spidersense:spider-sense:0.1.0

The single distributable jar. Its POM declares no dependencies.

The Gradle plugin

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

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, and the plugin’s default version for the jar it resolves is its own, so a plugin and the jar it fetches are always the same release. 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. A -launcher jar beside it is a build artifact, not the one to use. Keep the absolute path in a variable, because every command wants 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, which is how a build outside this repository uses an unreleased version.

Quick start

java -javaagent:"$SENSE" -Dotel.service.name=my-app -jar your-app.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. -Dotel.service.name= is worth setting always, because the alternative is the OpenTelemetry agent’s own default, unknown_service:java.

java -jar "$SENSE" status confirms it 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

bootRun and spring-boot:run fork the JVM themselves, so the agent has to be handed to the build tool rather than typed on your own command line. That is what the Gradle plugin and the Maven parameters exist for.

Java versions

The jar itself needs Java 21 or later, which is Spider Silk’s floor. The monitored application can run on any JVM the OpenTelemetry Java agent supports, but the embedded UI needs 21 or later, so agent mode requires 21 or later. An application on an older JVM can still be measured: run Spider Sense standalone on a modern JVM and point the application at it, as forwarding describes.

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.