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 |
|
The single distributable jar, built by |
The Gradle plugin |
|
The plugin id |
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 |
|
Agent mode, and forwarding when several applications share one UI |
The Gradle plugin |
|
|
Maven |
|
|
Standalone |
|
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 |
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.