The Examples
The repository carries four deliberately misbehaving applications and a load generator, so the pages and the findings can be seen with data on them before an application of your own runs under Spider Sense. All of them send to whichever Spider Sense they are pointed at. Each one does something wrong on purpose. Three are web applications on three different stacks, and the fourth has no web server at all.
The applications
- spring-orders
-
A Spring Boot 4.1 application with Spring Data JPA and H2 over an orders and customers domain, on port 8082. It has a slow report endpoint whose JPQL runs over a large table, a lazy-loading N+1 page, a checkout that fails with a business exception, and a flaky endpoint that fails 20% of the time. One endpoint calls
silk-bookstoreover HTTP, so a trace spans two services. Spring Boot Actuator is on, and its Micrometer meters, fromhttp.server.requestsand the HikariCP pool to Spring Data repository invocations, Tomcat sessions, Logback events and Micrometer’s ownjvm.*meters, reach Spider Sense through the agent’s Micrometer bridge. The metrics explorer therefore shows about ninety metrics for this one service. The OpenTelemetry agent has the bridge off by default.-Dotel.instrumentation.micrometer.enabled=trueturns it on, andbootRunand the demo scripts pass it. - servlet-warehouse
-
A Jakarta Servlet application on embedded Tomcat 11, with plain JDBC over Tomcat’s own pool and H2 holding about 400,000 rows, on port 8083. There is no framework between the servlets and the agent, so it shows what a classic Servlet stack looks like: endpoints are named after servlet mappings, so every item page is
GET /items/*, a filter runs inside the server span, and the exception behind a 500 is what Tomcat’s error page received. It has a full-scan search, an N+1 item page, a slow report, a flaky endpoint, and an async servlet (AsyncContext) whose span lasts untilcomplete()is called on another thread, or until the timeout turns it into a 503. - batch-worker
-
A plain Java program with HikariCP, Logback and H2 that runs scheduled jobs and serves no HTTP at all. It shows what the web applications cannot: a service with zero requests that still has a JVM, logs and jobs, and the four findings the other three never produce (
slow-job,log-error,pool-exhausted,thread-growth). A reconciliation job scans 300,000 unindexed rows and then runs oneUPDATEper account, which is a slow query inside a job, and a report job streams every row into memory, which is a slow job. A reminder job catches a gateway failure and logs it atERROR, so the span succeeds and only the log records the failure, which is alog-error. An archive job holds a connection while it sleeps through a slow upload, eight tasks over a pool of three, so the pool has no free connection, the last tasks fail on the connection timeout, and the job is slow as well. Every reminder starts a thread that waits for an acknowledgement that never comes, so the thread count climbs until a cap that keeps the process alive, which is athread-growth. The jobs are@WithSpanmethods called from aScheduledExecutorService, so each run is a rootINTERNALspan, which is what a job is. - silk-bookstore
-
A Spider Silk application with jte pages and a JSON API, over spring-jdbc and an H2 file database, on port 8081. About 200,000 rows are seeded, so an unindexed
LIKE '%…%'search is slow because it scans them, with no artificial delay. ASLEEPalias makes one query slow on purpose, one page runs N+1 queries, one endpoint throws, and one endpoint sleeps without running any SQL. - load-gen
-
A plain Java program that hits the three web applications at a randomised rate, so the dashboards fill without manual clicking. It is instrumented too, through
java.net.http, so some traces start at the client.batch-workerneeds no traffic, because its jobs run on their own.
Each of the five lives under examples/ in the repository, with a README that lists every route or job and says why it is wrong.
The demo without installing anything
spider-sense.benelog.net/demo is the same UI over a recording of the demo below: the four applications and the load generator under one Spider Sense for five minutes. Every page is answered from a database of the recording, with no server behind it. Everything that reads works, from the map to a single trace’s profile, and the range, the marks and the compare page cover the recorded window. Anything that writes, such as a mark or an acknowledgement, answers that the page is a recording.
The recording is a DoltHub database with the tables of Storage as a running Spider Sense keeps them, plus one table of the answers the UI asks for.
The page reads it through DoltHub’s SQL API as it is opened, so every trace of the recording opens, and the rows can be queried there as SQL too.
scripts/demo-site.sh record makes one: it runs scripts/demo-shared.sh for MINUTES (five by default), marks before and after along the way, exports the rows since the launch out of the H2 file, loads them into a fresh Spider Sense to capture the answers, and pushes both to DoltHub.
scripts/demo-site.sh recapture redoes the answers from the rows already there, after a change to the server’s queries.
The published demo describes how the recording is made and read.
The two scripts
Both scripts build what they need, start everything, print where each thing is, and stop it all on Ctrl-C.
Pass --no-build to skip the Gradle build when nothing has changed.
Every process writes its log to build/demo-logs/, and each script prints the CLI line to run next.
RPS sets the load generator’s rate, which defaults to 4 requests per second.
scripts/demo-shared.sh # one standalone Spider Sense that all four applications forward to
scripts/demo.sh # each application with its own embedded Spider Sense
demo-shared.sh
scripts/demo-shared.sh is one standalone Spider Sense on port 4000, which the four applications and the load generator forward to with -Dspidersense.collector=.
SENSE_PORT moves it.
In this setup a trace crossing two services shows up in one place, the map has every service on it, and one findings call covers all of them.
The applications keep their own ports: 8082 for spring-orders, 8083 for servlet-warehouse and 8081 for silk-bookstore, and batch-worker has none.
The load generator runs under the agent here as well, named load-gen, so its calls are the root of the traces they start.
demo.sh
scripts/demo.sh runs each of the four applications in agent mode, with no extra process.
Each application starts from its own installDist script or boot jar with the agent on the command line and hosts its own Spider Sense, so there are four UIs, on the ports in the table below.
The load generator runs without the agent here.
| Application | Application port | Spider Sense |
|---|---|---|
silk-bookstore |
8081 |
|
spring-orders |
8082 |
|
servlet-warehouse |
8083 |
|
batch-worker |
none |
The four share the one H2 file under ~/db/spider-sense/, so java -jar "$SENSE" findings on the default port answers for every service, and --url=http://127.0.0.1:4003 asks the one batch-worker hosts instead.
After the applications stop
The data is in an H2 file under ~/db/spider-sense/, which stays after every process that wrote to it has stopped.
java -jar spider-sense.jar opens the same screens on the same rows once the demo has been stopped.
What to do with them
The examples put data on every page of the UI, and the manual’s walk through the agent loop runs against them.
Start scripts/demo-shared.sh, let the load generator run for a minute, and then read the findings:
java -jar "$SENSE" findings --since=15m
Each finding points back at one of the faults above, so Findings can be read against code that is known to be wrong.
The web applications produce n-plus-one, n-plus-one-http, slow-query, slow-endpoint, slow-external and error.
batch-worker adds slow-job, log-error, pool-exhausted and thread-growth, and it is the one service on which check has nothing to judge, because a job is never a request.
The Loop gives the steps to run on them next: mark, exercise, findings, fix, compare, check.
Handing the demo to an agent
The repository carries the skills at skills/, linked from .claude/skills/ and .agents/skills/, so Claude Code and Codex started in the checkout find them without an init step.
Start scripts/demo-shared.sh, let the load generator run for a few minutes, and then ask in Claude Code:
/spider-sense The example apps have been running under Spider Sense with some traffic for a few minutes.
What are the three biggest problems, and which lines under examples/ cause them?
Do not change the code yet; propose how to fix them first.
In Codex the skill is called $spider-sense instead of /spider-sense.
The prompt names no command, because the skill says how to read the findings, open a trace for each, and locate the code.
The agent answers with the findings as the tool printed them, a trace id for each as evidence, the file and line each fault comes from, and a proposed fix for each.
It can find the line because the finding carries the code location, and the README beside each example says what is wrong on purpose.
A second prompt such as "apply the first fix and show me before and after" has it fix, restart the application, exercise the same endpoints, and run compare (Marks and Compare).
In a project of your own, java -jar spider-sense.jar init installs the same skill and writes the jar’s path into CLAUDE.md.
The prompt can be watched before it is tried. Real sessions of it are replayed in a terminal, from the event stream each agent printed, in English and in Korean:
Each session is two tables in the same DoltHub database as the recorded UI.
scripts/agent-demo.sh record claude en records one, and scripts/agent-demo.sh push pushes the sessions there.
The agent demo describes how a session is recorded and replayed.
Quick Start for Agents lists further prompts, each with the commands the agent runs for it.