The CLI
The Spider Sense jar is also a command line: java -jar spider-sense.jar <command> answers a question about a window of the stored data, in Markdown made for an agent to read.
The CLI renders nothing itself.
When a Spider Sense answers at --url, the CLI fetches the format=text rendering and prints the body, so its numbers are the ones the UI shows.
When none answers, the CLI opens the H2 file in process and runs the same queries through the same renderer (the direct-file fallback).
Invocation
java -jar spider-sense.jar <command> [arguments] [options]
The launcher treats a first argument that does not start with - as a command, and hands the whole line to the CLI inside the nested server jar, through the same SenseClassLoader the embedded server uses (The jar).
The launcher itself stays dependency-free.
--port= and the other standalone flags still start a server, so java -jar spider-sense.jar with no command is the standalone UI rather than a command (Standalone).
The command goes first.
A word after a flag, such as findings in java -jar spider-sense.jar --db=./yesterday findings, is a usage error that exits 2 without starting a server, and so is an empty first argument, such as the "$COMMAND" of an unset variable.
Under the Gradle plugin, the spiderSense task runs the same CLI, even in a project that never checked out the Spider Sense repository:
./gradlew -q spiderSense --args="findings --since=start"
./gradlew -q spiderSense --args="check --max-n-plus-one=0"
-q keeps Gradle’s own lines out of the output.
A CLI exit code other than 0 fails the task, and ./gradlew then exits 1 whatever the code was, so only Gradle’s failure message names it.
A script that branches on the exit code runs java -jar spider-sense.jar itself.
When the spiderSense block names a collector, a host or a port, the task also sets SPIDERSENSE_URL to the base URL that block implies, so the command asks the Spider Sense the application is sending to rather than the default port (Tasks).
SPIDERSENSE_URL names the Spider Sense to ask whenever --url is not given.
Without either, the spidersense.* properties decide: spidersense.collector when set, else http://<host>:<port> with the defaults filled in, which is http://127.0.0.1:4000 when nothing is set.
A spidersense.port that is not a port from 0 to 65535, such as abc, is read as the application reads it: a warning on stderr, [spider-sense] spidersense.port=abc is not a number; using 4000, and the default port.
The warning comes once, and only from a command that reads the setting: one that needs the default URL, or one that reads the file, whose configuration holds the port too.
help, version, init and a command whose --url names the server print none.
The launcher reads the properties file before a command runs, so a command run from the project’s directory asks the Spider Sense the application in that directory sends to.
Commands
| Command | Does |
|---|---|
|
what is running, where the database is, how much it holds |
|
the findings of the window, with the suspect change under each code frame |
|
accepts a known finding, which is then ranked after every other one |
|
withdraws that acknowledgement |
|
marks a finding fixed, so it is a |
|
withdraws that resolution |
|
one trace as a tree, or two aligned |
|
the newest traces |
|
the tables of the window |
|
log lines |
|
records a mark now |
|
lists marks |
|
the two windows side by side |
|
pass or fail, in the exit code |
|
tingles as they arrive, one line each |
|
one read-only statement over the store |
|
the window as one JSON document, to the file or to stdout |
|
that document back into the store |
|
writes the Spider Sense block into the project’s |
|
the MCP server over stdio |
|
this table, or what one command takes |
|
the version of the jar, as |
Every example below is the real output of one session against the spring-orders example application.
That Spider Sense listened on port 4100, so each command also carried --url=http://127.0.0.1:4100, which the listings leave out.
status
status names the mode, the port, the thresholds, the database and how much it holds.
You run it to confirm that an application really is collecting.
The services row counts the services seen and names them, the most recently seen first: 2 (spring-orders, silk-bookstore), or 25 (newest 20: …) past the twenty it names.
$ java -jar spider-sense.jar status
# status
| field | value |
| --- | --- |
| name | Spider Sense 0.1.0 |
| mode | agent |
| endpoint | http://127.0.0.1:4100 |
| started | 2026-09-17T08:19:14.060+09:00 |
| embedded service | spring-orders |
| thresholds | slow request 500 ms, slow query 100 ms |
| ignore | /actuator/**, /health, /healthz, /livez, /readyz |
| retention | 24 hours, 1000000 spans |
| database | /home/me/db/spider-sense/sense.mv.db |
| database size | 110395392 bytes |
| dropped spans | 0 |
| spans | 51785 |
| traces | 51257 |
| logs | 66 |
| metric series | 67 |
| services | 1 (spring-orders) |
| oldest span | 2026-09-17T08:14:07.250+09:00 |
findings, ack and resolve
findings is the command an agent reads first: a ranked list of the findings over the window.
The table lists the findings in rank order, and each numbered block under it holds one row’s evidence, in the same order: its numbers, its statement, its code frames and its trace ids.
The table holds 20 findings unless --limit says otherwise, at most 100, and when there were more, a line under the heading says so: 20 of 54 findings; --limit=54 shows them all (The text rendering).
Findings has every kind with its rule and its numbers.
$ java -jar spider-sense.jar findings --since=before
# findings 2026-09-17T08:19:28.122+09:00 → 08:19:34 (6s, all services, 21 requests)
| # | severity | state | kind | id | service | title |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | high | new | error | error:eecf9878a68f | spring-orders | IllegalStateException in GET /api/flaky |
| 2 | medium | new | n-plus-one | n-plus-one:4c5f46be8bc5 | spring-orders | GET /api/orders/{id}/enriched runs SELECT product 5 times per request |
| 3 | medium | new | slow-query | slow-query:6b3aae6f9bef | spring-orders | SELECT p.id AS product_id, p.sku AS sku, p.name AS name, SUM… is slow: p95 269.7 ms in GET /api/reports/revenue |
1. error:eecf9878a68f — 1 occurrence in GET /api/flaky; Payment gateway timeout
count 1, firstSeen 2026-09-17T08:19:28.962+09:00, lastSeen 2026-09-17T08:19:28.962+09:00, type java.lang.IllegalStateException, message Payment gateway timeout, endpoints [name GET /api/flaky count 1]
orders.web.MiscController.flaky(MiscController.java:24)
traces: 5e6769395a77c8f192949af91cbdedf2
2. n-plus-one:4c5f46be8bc5 — 1 of 3 requests repeated it; 5 times; 0.4 ms per request in that statement
requests 3, affected 1, medianRepeats 5, maxRepeats 5, msPerRequest 0.4
select p1_0.id,p1_0.name,p1_0.price,p1_0.sku from product p1_0 where p1_0.id=?
traces: e7cfa77cb4c9135b623a04e470ef58d0
ack <finding id> [--note=<text>] accepts a finding that is known and will not be fixed now.
It is then ranked after every other finding, and its severity column reads acked.
unack <finding id> withdraws the acknowledgement, and exits 4 when there was none.
findings --hide-acked leaves the acknowledged findings out altogether.
The finding id is the one findings printed in its id column, and it is stable across windows (Acknowledgements).
ack and resolve refuse any other id and record nothing: one that is not <kind>:<12 hex digits>, such as an id of the errors, queries or endpoints table, is a usage error and exits 2, and a well-formed one that names no finding of the data kept exits 4 (Acknowledgements says what names one for each kind).
unack and unresolve refuse a word that is not <kind>:<12 hex digits> in the same way.
resolve <finding id> [--note=<text>] records that a finding is fixed.
If it occurs again after that, findings reports it as a regression, severity high, first in the list, and check fails on it by default.
Until then it is ranked after every other finding, and its severity column reads resolved.
unresolve <finding id> withdraws the resolution, and exits 4 when there was none.
Resolutions says when a finding counts as back.
The state column says what the last restart changed: new for a finding the run before the restart did not have, ongoing for one it had, and regressed for a regression (State).
The suspect change
Under each code frame whose file it finds, when it runs in a repository, findings adds one line naming the file and the change that last touched the frame’s line:
orders.OrderService.load(OrderService.java:41)
src/main/java/orders/OrderService.java:41 — changed in 4743e1d (2 hours ago): Run Error Prone and NullAway in every javac
orders.web.OrderController.show(OrderController.java:28)
src/main/java/orders/web/OrderController.java:28 — uncommitted
The line is indented two spaces past the frame, so a reader of the block sees it as the frame’s.
It starts with the file’s path relative to the working directory and the frame’s line, <path>:<line>, so an agent opens the file without searching for it.
After ` — ` comes one of two verdicts, or none.
-
uncommittedwhen the file is ingit diff --name-onlyorgit diff --cached --name-only, or is untracked (git ls-files --others --exclude-standard), because a file the agent has just created is the most likely suspect of all. It is alsouncommittedwhengit blamesays the line itself is not committed yet. -
Otherwise
changed in <hash> (<age>): <subject>, from the commitgit blame -L <n>,<n> --porcelainnames for the frame’s line: the first seven characters of its hash, its author date as an age in the largest whole unit (45 seconds ago,2 hours ago,3 days ago,3 weeks ago,4 months ago,2 years ago), and its subject. -
The path alone when the file lies outside the repository, or when
git blamehas nothing to say about the line, as for a file edited to be shorter than the frame’s line.
The file is found under the source roots first (Source lines and the suspect change).
A frame no root resolves is looked up among the repository’s files, tracked or untracked, by its package path, with git ls-files --cached --others --exclude-standard — ':(glob)**/<package path>/<file>'.
That finds a module one directory deeper than the default roots reach, as examples/servlet-warehouse/src/main/java from the repository’s root.
The one file it lists is the frame’s, or, among several, the one under a src/main/ directory; two candidates there leave nothing to choose by, and the frame gets no line.
At most 20 files are looked up this way, and the lookups together get the 10 seconds one git command gets.
An empty spidersense.source.dirs turns the lookup off with the roots.
When the working directory is in a repository and the findings have code frames but not one of them resolves, findings prints one line on stderr naming the property that says where the sources are:
spider-sense: no code frame resolved to a source file under /home/me/project; -Dspidersense.source.dirs=<dir>[,<dir>…] names the source roots, as in java -Dspidersense.source.dirs=app/src/main/java -jar spider-sense.jar findings
The line says whether the line a finding points at is in the change the agent has just made.
It is off when the working directory is not in a repository or git cannot be run, and --no-git turns it off.
A git command that has not answered within 10 seconds is killed, with whatever it started, and what it would have said is left out.
--json prints the server’s JSON, which never carries it.
This line is the one thing the CLI adds to an answer instead of printing what the server or the in-process renderer produced.
Only the CLI can add it: the CLI runs in the project directory, where the repository is, and the server may run elsewhere or not at all.
It is added to the text after the rendering, and left out by --no-git and by --json.
It is therefore also the one part of a findings answer that is not a function of the window alone: the age depends on when it was asked, and the verdict on the working tree.
The HTTP API and the MCP findings tool answer without it, since neither knows which repository the caller is working in.
trace and traces
trace <traceId> prints one trace as an indented tree, one span per line with its offset and duration.
--full expands collapsed groups and keeps statements whole.
--diff=<traceId> aligns two traces instead (Trace diff).
$ java -jar spider-sense.jar trace e7cfa77cb4c9135b623a04e470ef58d0
# trace e7cfa77cb4c9135b623a04e470ef58d0 2026-09-17T08:19:28.782+09:00 174.5 ms spring-orders 15 spans, 8 db, 0 errors
offset duration span
0.0 ms 174.5 ms SERVER spring-orders GET /api/orders/{id}/enriched → 200
3.6 ms 2.0 ms INTERNAL OrderRepository.findById
3.9 ms 1.5 ms INTERNAL Session.find orders.domain.Order
4.5 ms 0.2 ms db SELECT orders
6.0 ms 0.2 ms db SELECT order_line
7.3 ms 0.4 ms db SELECT product × 5, 0.1 ms avg, 0.4 ms total
select p1_0.id,p1_0.name,p1_0.price,p1_0.sku from product p1_0 where p1_0.id=?
9.0 ms 0.0 ms db SELECT customer
9.3 ms 0.1 ms INTERNAL Transaction.commit
42.4 ms 89.6 ms CLIENT GET http://localhost:8081/api/books/106 → 200
162.5 ms 2.5 ms CLIENT GET http://localhost:8081/api/books/49 → 200
A failed span carries its exception and the application frames underneath, and the trace’s log lines follow, oldest first:
$ java -jar spider-sense.jar trace 5e6769395a77c8f192949af91cbdedf2
# trace 5e6769395a77c8f192949af91cbdedf2 2026-09-17T08:19:28.962+09:00 22.0 ms spring-orders 1 span, 0 db, 1 error
offset duration span
0.0 ms 22.0 ms SERVER spring-orders GET /api/flaky → 500 [error]
exception IllegalStateException: Payment gateway timeout
orders.web.MiscController.flaky(MiscController.java:24)
logs (2)
08:19:28.963 WARN orders.web.MiscController Flaky endpoint failing this time: payment gateway timeout
traces lists the newest traces of the window.
--status=error or --status=ok filters by outcome, --min-ms=<n> to the traces longer than n ms, --q=<text> by free text, and --limit=<n> sets the page size.
--status takes error or ok and nothing else, in any case, and another value is a usage error that lists the two.
--min-ms takes a whole number of milliseconds, and any other value, such as 1.5, is a usage error in both modes.
$ java -jar spider-sense.jar traces --since=before --limit=5
# traces 2026-09-17T08:19:28.122+09:00 → 08:19:35 (8s, all services, 21 requests)
5 of 21 traces, newest first
| start | duration | trace | root | service | spans | db | errors | status |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 08:19:29.969 | 3.5 ms | b02e7baec05adb0651ad0671066bb4e0 | POST /api/orders/{id}/pay | spring-orders | 4 | 1 | 0 | 404 |
| 08:19:29.960 | 3.0 ms | 3fde475ce08a20f45944dd769739de28 | GET /api/customers/search | spring-orders | 5 | 1 | 0 | 200 |
| 08:19:29.939 | 12.6 ms | 739be08737bae7de506fdb0a8da510f8 | GET /api/orders/{id}/enriched | spring-orders | 13 | 6 | 0 | 200 |
endpoints, queries, errors and logs
endpoints, queries, errors and logs print the tables of the window, the same data the matching UI pages draw.
endpoints always lists every endpoint of the window and takes no --limit.
$ java -jar spider-sense.jar endpoints --since=before
# endpoints 2026-09-17T08:19:28.122+09:00 → 08:19:34 (7s, all services, 21 requests)
| endpoint | id | service | calls | errors | p50 | p95 | max | total | apdex |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| GET /api/reports/revenue | 7342d163d1ee | spring-orders | 3 | 0 | 411.5 ms | 549.8 ms | 549.8 ms | 1,354.9 ms | 0.833 |
| GET /api/orders/{id}/enriched | 8c62f8d5090d | spring-orders | 3 | 0 | 12.6 ms | 174.5 ms | 174.5 ms | 195.7 ms | 1.000 |
| GET /api/flaky | 40e6cdb7cd69 | spring-orders | 3 | 1 | 2.8 ms | 22.0 ms | 22.0 ms | 25.5 ms | 0.667 |
queries lists the database statements of the window, grouped by statement, with the endpoints that called each one:
$ java -jar spider-sense.jar queries --since=before --limit=5
# queries 2026-09-17T08:19:28.122+09:00 → 08:19:35 (7s, all services, 21 requests)
| id | service | calls | slow | p50 | p95 | max | total | callers | unindexed | statement |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| e0e233d8ad75 | spring-orders | 3 | 3 | 266.6 ms | 269.7 ms | 269.7 ms | 782.8 ms | GET /api/reports/revenue ×3 | — | SELECT p.id AS product_id, p.sku AS sku, p.name AS name, SUM(l.quantity) AS quantity… |
| 14eb3eff12dc | spring-orders | 22 | 0 | 0.1 ms | 0.2 ms | 0.2 ms | 2.0 ms | GET /api/orders/{id} ×11; GET /api/orders/{id}/enriched ×11 | — | select p1_0.id,p1_0.name,p1_0.price,p1_0.sku from product p1_0 where p1_0.id=? |
unindexed lists the columns the statement filters on that no index of their table serves, from the schema block: none when every predicate is served, and — when there is no block.
The unindexed column is — in both rows above because that run collected no index catalog.
errors lists the error groups of the window.
Each group whose sample stack trace has application frames gets a block naming one trace and those frames:
$ java -jar spider-sense.jar errors --since=before
# errors 2026-09-17T08:19:28.122+09:00 → 08:19:35 (7s, all services, 21 requests)
| id | service | type | message | target | count | first | last | endpoints |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 458522ccda9f | spring-orders | java.lang.IllegalStateException | Payment gateway timeout | — | 1 | 08:19:28.962 | 08:19:28.962 | GET /api/flaky ×1 |
458522ccda9f — trace 5e6769395a77c8f192949af91cbdedf2
orders.web.MiscController.flaky(MiscController.java:24)
target is the outbound HTTP call the group’s occurrences mostly are, which is what says what failed when its type is a status and it has no message, and — for any other group.
logs prints log lines, newest first.
--severity=<level> sets the floor, --q=<text> searches the body, and --trace=<traceId> narrows to one trace.
The level is TRACE, DEBUG, INFO, WARN, ERROR or FATAL, in any case, and another value is a usage error that lists them, rather than a filter that lets every line through.
The count line says how many lines were printed out of how many matched the window:
$ java -jar spider-sense.jar logs --since=before --limit=3
# logs 2026-09-17T08:19:28.122+09:00 → 08:19:35 (8s, all services)
3 of 5 lines, newest first
08:19:29.922 INFO orders.service.OrderService Revenue report over 90 days: 244 groups, 10 top products, 391 ms trace cbc8be4f6ec5a1c033e57cbb7f269bd5
08:19:28.965 ERROR org.apache.catalina.core.ContainerBase.[Tomcat].[localhost].[/].[dispatcherServlet] Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: java.lang.IllegalStateException: Payment gateway timeout] with root cause trace 5e6769395a77c8f192949af91cbdedf2
mark and marks
mark <name> records a named moment now, and --note=<text> keeps a sentence with it.
marks lists the newest 50 marks, newest first.
Marks has the rules, including the automatic start mark.
$ java -jar spider-sense.jar mark before
mark before at 2026-09-17T08:19:28.122+09:00
$ java -jar spider-sense.jar mark after --note="after the fix"
mark after at 2026-09-17T08:19:35.837+09:00 — after the fix
$ java -jar spider-sense.jar marks
# marks
| at | name | service | note |
| --- | --- | --- | --- |
| 2026-09-17T08:19:35.837+09:00 | after | — | after the fix |
| 2026-09-17T08:19:28.122+09:00 | before | — | — |
| 2026-09-17T08:19:16.727+09:00 | start | spring-orders | pid 178056 instance 5c1e9a52-3f0d-4b8e-a7c4-0e6b2d9f8a13 |
compare
compare --before=<selector> --after=<selector> puts the window before a mark beside the window after it, endpoint by endpoint and query by query.
It takes no --since, because its windows are the two selectors.
--until closes the second window.
The verdict is each row’s first column, and the rows sort worse, new, same, better, gone, so anything that got worse is at the top of each table.
Compare has the verdicts and their thresholds.
$ java -jar spider-sense.jar compare --before=before --after=after
# compare 2026-09-17T08:19:28.122+09:00 → 08:19:35 vs 2026-09-17T08:19:35.837+09:00 → 08:19:45 (all services)
| totals | before | after |
| --- | --- | --- |
| requests | 21 | 12 |
| errors | 1 | 1 |
| p95 | 411.5 ms | 1,201.7 ms |
| apdex | 0.929 | 0.792 |
## endpoints
| verdict | endpoint | id | calls | errors | p95 | db/req | db ms/req |
| --- | --- | --- | --- | --- | --- | --- | --- |
| new | GET /api/slow | 7c7ff534a0ec | — → 3 | — → 0 | — → 1,202.5 ms | — → 0.0 | — → 0.0 ms |
| better | GET /api/reports/revenue | 7342d163d1ee | 3 → 3 | 0 → 0 | 549.8 ms → 417.1 ms | 2.0 → 2.0 | 419.8 ms → 383.6 ms |
| gone | GET /api/customers/search | cf03d98e70da | 3 → — | 0 → — | 29.6 ms → — | 1.0 → — | 0.9 ms → — |
## queries
| verdict | id | calls | calls/req | p95 | total | statement |
| --- | --- | --- | --- | --- | --- | --- |
| same | e0e233d8ad75 | 3 → 3 | 0.1 → 0.3 | 269.7 ms → 247.1 ms | 782.8 ms → 698.9 ms | SELECT p.id AS product_id, p.sku AS sku… |
## errors
| verdict | id | type | message | target | before | after |
| --- | --- | --- | --- | --- | --- | --- |
| same | 458522ccda9f | java.lang.IllegalStateException | Payment gateway timeout | — | 1 | 1 |
check
check turns thresholds into pass or fail, and puts the verdict in the exit code.
Every rule named on the command line is evaluated, and naming one replaces the default set.
Check has every rule, the value it measures and its default.
$ java -jar spider-sense.jar check --since=before
# check fail 2026-09-17T08:19:28.122+09:00 → 08:19:45 (17s, all services, 33 requests)
| rule | limit | actual | verdict | detail |
| --- | --- | --- | --- | --- |
| maxP95Ms | 500 | 1,202.5 | fail | GET /api/slow p95 1,202.5 ms over 3 calls |
| maxErrors | 0 | 2 | fail | 2 occurrences: IllegalStateException in GET /api/flaky ×2 |
| maxNPlusOne | 0 | 2 | fail | 2 findings: GET /api/orders/{id} runs SELECT product 5 times per request |
| maxRegressions | 0 | 0 | pass | no resolved finding came back |
$ echo $?
1
--endpoint= narrows the scope to one endpoint, by its id or by its name, and the heading names that endpoint.
An endpoint the window does not have, while the window has requests, is a usage error that exits 2 and points at endpoints, rather than a check with no request to judge.
So is a name that endpoints of several services share, without --service: the message lists each service with its endpoint’s id.
tail
tail prints one line per live event as it arrives, so a request that was just sent can be watched instead of polled for.
It needs a running Spider Sense.
See Tail.
export and import
export writes the window as one JSON document, and import reads one back into a store.
See Export and import.
sql
sql "<statement>" runs one read-only statement over the schema, for a question no other command answers.
See SQL.
init
init writes the Spider Sense block into the project’s CLAUDE.md or AGENTS.md and installs the skills into its .claude/skills/.
It is the one command that reads nothing: no HTTP, no database, no running Spider Sense.
It takes none of the common options, and its own are --dir, --jar, --url, --gradle, --no-skill and --mcp.
Its --url asks nothing: it is the address of the project’s Spider Sense, which the block it writes tells the agent to ask.
See init.
mcp
mcp runs the MCP server over stdio, for a host that has no shell.
It takes --url and --db and nothing else, because since, until and service are arguments of each tool call, and every tool answers the text rendering.
See MCP.
help
help prints every command, every common option, the selector forms and the exit codes.
$ java -jar spider-sense.jar help
Spider Sense: ask a running Spider Sense, or the database file, from the terminal.
java -jar spider-sense.jar <command> [arguments] [options]
Commands:
status what is running, where the database is, how much it holds
findings [--hide-acked] [--no-git]
the findings of the window; under each code frame,
the suspect change git names (uncommitted, or the
commit that last changed the line)
ack <finding id> [--note=<text>]
accepts a known finding, so it is ranked last
unack <finding id> withdraws that acknowledgement
resolve <finding id> [--note=<text>]
marks a finding fixed; if it comes back it is a
regression, ranked first
unresolve <finding id> withdraws that resolution
trace <traceId> [--full] [--diff=<traceId>]
one trace as a tree, or two aligned
tail [--kind=slow-request|slow-query|error] [--service=<name>]
[--until-traces=<n>] [--timeout=<duration>]
tingles as they arrive, one line each
traces [--status=error|ok] [--min-ms=<n>] [--q=<text>] [--limit=20]
the newest traces
endpoints the endpoints of the window
queries the database statements of the window
errors the errors of the window
logs [--severity=<level>] [--q=<text>] [--trace=<traceId>]
log lines; --severity is the lowest level shown:
TRACE, DEBUG, INFO, WARN, ERROR or FATAL
mark <name> [--note=<text>] records a mark now
marks lists marks
compare --before=<selector> --after=<selector> [--until=<selector>]
the two windows side by side
check [--max-p95-ms=] [--max-errors=] [--max-error-rate=]
[--max-queries-per-request=] [--max-slow-queries=]
[--max-n-plus-one=] [--max-log-errors=] [--max-regressions=]
[--min-apdex=] [--endpoint=]
pass or fail, in the exit code
sql "<statement>" [--limit=200]
read-only SQL over the store (SELECT only)
export [--out=<file>] the window as one JSON document, to the file or to
stdout; a name ending in .gz is gzipped
import <file> that document back into the store, and one line
saying what arrived
init [--dir=<project dir>] [--jar=<path>] [--url=<base url>] [--gradle]
[--no-skill] [--mcp]
writes the Spider Sense block into the project's
CLAUDE.md or AGENTS.md and installs the skills into
.claude/skills/; --mcp writes the stdio MCP server
into .mcp.json instead of the skills
mcp the MCP server over stdio, for a host with no shell;
takes --url and --db and nothing else
help [<command>] this table, or what one command takes, which
<command> --help prints too
version the version of this jar, as --version prints it
Common options:
--since=<selector> default 15m
--until=<selector> default now
--service=<name> one service
--limit=<n> how many rows, at least 1; the default and the cap:
findings 20/100, traces 20/1000, queries 100/1000,
errors 100/1000, logs 200/5000, marks 50/500,
sql 200/5000
--url=<base url> default http://127.0.0.1:4000, or SPIDERSENSE_URL, or what
spider-sense.properties in the working directory implies
--db=<path or jdbc url> read the database directly, without asking any server
--json the JSON of the HTTP API instead of the text
--full whole statements, every repeated span
--hide-acked findings only: leave acknowledged findings out
--no-git findings only: no suspect-change line under the code frames
A selector is a duration (30s, 5m, 2h, 1d), a date-time (2026-10-08T05:50:00,
with or without an offset), epoch milliseconds, a mark name, start (the newest
automatic start mark) or now.
With no --url and nothing listening, the database file is read in process; the
thresholds are then --slow.request.ms, --slow.query.ms and --app.packages, since
no server is there to ask.
Exit codes: 0 success, 1 check failed, 2 usage or connection error,
3 check had no request to judge, 4 not found (a trace id, a mark name,
a finding id to ack, resolve, unack or unresolve).
help <command> prints one command’s block instead: its entry of the table, then every option it takes, its own first and the common ones after them.
<command> --help and <command> -h print the same block whatever else the line holds, so trace --help needs no trace id.
$ java -jar spider-sense.jar mark --help
mark <name> [--note=<text>] records a mark now
Options: --note=<text> --service=<name>
Common options: --url=<base url> --json --db=<path or jdbc url>
--slow.request.ms=<ms> --slow.query.ms=<ms>
--app.packages=<packages>
java -jar spider-sense.jar help lists every command, the selector forms and the
exit codes.
version prints the version of the jar, the line java -jar spider-sense.jar --version prints.
A usage error prints two lines on stderr and exits 2: what is wrong, and which help to read, the command’s block when the line named a command and the table otherwise.
So does a value the line spells correctly and the store refuses, such as --since=5min, a mark named 5m, an inverted window, an --endpoint= the window does not have or a statement sql does not run, whether a server answered it with a 400 or the CLI read the file.
A command or an option that is not known but is within two edits of one that is gets a did you mean …?:
$ java -jar spider-sense.jar findings --sinse=5m
spider-sense: unknown option for findings: --sinse; did you mean --since?
see: java -jar spider-sense.jar findings --help
Common options
| Option | Default | Meaning |
|---|---|---|
|
|
start of the window |
|
|
end of the window |
|
every service |
narrow to one service; taken by the commands that narrow by service, which are |
|
per list |
how many rows, at least 1: findings 20 (at most 100), traces 20 (at most 1000), queries 100 (at most 1000), errors 100 (at most 1000), logs 200 (at most 5000), marks 50 (at most 500), sql 200 (at most 5000); a larger limit is lowered to the cap, and one below 1 is a usage error |
|
|
which Spider Sense to ask |
|
|
read that database directly, without asking any server; a path is taken with or without its |
|
off |
print the JSON of the HTTP API instead of the text |
|
off |
keep statements whole and expand collapsed spans |
|
off |
|
|
off |
|
--since and --until take a time selector: a duration, a date-time such as 2026-10-08T05:50:00, epoch milliseconds, a mark name, start or now.
Time selectors states every form.
Five commands depart from the table.
compare takes no --since, because its windows are the two selectors, and its --until closes the second window.
init takes none of these options but --url, which it writes into its block rather than asks, and its own are --dir, --jar, --gradle, --no-skill and --mcp.
mcp takes only --url and --db.
export takes no --json, because it writes a document rather than printing an answer, and help takes no option at all.
--slow.request.ms=, --slow.query.ms= and --app.packages= set the thresholds and the application packages in the direct-file path, where no server is there to ask.
A threshold that is not a whole number is a usage error whichever mode would answer.
A server that answers uses its own settings, so a line on stderr then says that these options changed nothing: (the Spider Sense at http://127.0.0.1:4000 answered with its own settings; --slow.query.ms applies only when the file is read).
An option a command does not take is a usage error rather than a silently ignored word, so a mistyped --sinse is reported, with did you mean --since?, rather than answered for the last 15 minutes.
An option that takes a value is a usage error without one, so a bare --since is reported rather than read as the mark name true, and so is an empty one, such as the --url= of an unset variable, except --note=, which is no note; only --json, --full, --hide-acked, --no-git and init’s `--gradle, --no-skill and --mcp are named bare.
A flag given a value is a usage error too, such as --json= or --full=1, rather than a flag read as off.
A command’s own word, such as the trace id of trace or the finding id of unack, is a usage error when it is empty, as when it is missing, so trace "$ID" with ID unset is trace needs a trace id rather than the list of traces.
Exit codes
| Code | Meaning |
|---|---|
|
success, and |
|
|
|
usage or connection error |
|
|
|
not found: a trace id, a mark name, a finding id to |
A trace id that matches nothing prints spider-sense: No such trace: <id> on stderr and exits 4, whether the answer came over HTTP or from the file.
A word that cannot be a trace id, which is at most 32 hex digits, gets the same line and exit code before any server or file is asked, so trace .. never meets the server’s refusal of a path that holds it.
A mark name that matches no mark also exits 4, with a message naming the mark.
A mistyped duration such as --since=5min or --since=1h30m is not a mark name: it is a usage error and exits 2.
unack of a finding that has no acknowledgement prints spider-sense: No such acknowledgement: <id> and exits 4 as well.
unresolve of a finding that has no resolution prints spider-sense: No such resolution: <id> and exits 4.
ack or resolve of a well-formed id that names no finding of the data kept prints spider-sense: No finding <id> in the data kept (the last 24 hours); the id column of findings names one and exits 4, while an id that is not a finding id at all exits 2.
The argument of ack, unack, resolve and unresolve is checked before any server or file is asked, so a word such as .. or a table id prints spider-sense: Not a finding id: <word>. A finding id is <kind>:<12 hex digits>, … and the help line in both modes, rather than the server’s refusal of a path that holds it.
Exit code 3 means the exercise step did not reach the application, not that a fix worked.
The direct-file fallback
When nothing answers at the default URL, the CLI opens the H2 database in process, runs the same queries through the same renderer, and says so on stderr:
(no Spider Sense at http://127.0.0.1:4000; reading /home/me/db/spider-sense/sense.mv.db directly)
AUTO_SERVER=TRUE makes this possible (Storage).
After the application has crashed and taken the UI with it, findings --since=start still answers.
"Nothing answers" means the connection was refused or not made within 2 seconds.
Every answer of a Spider Sense, a success or an error, carries the header X-Spider-Sense: <version> (API conventions).
An answer without it counts as nothing answering, with the reason HTTP <status> for <path>, whatever its status, type and body, so an application that answers JSON to any path is never printed as the answer to --json.
A server that answers with an error in a shape that is not Spider Sense’s counts as nothing answering too, so it is never the exit 4 of a missing trace or mark.
Spider Sense’s own error is the {"error": "…"} object with nothing beside it, or, from sql, the one line of a 400.
Another application’s HTML error page is not, and neither is a Spring application’s JSON error, which carries a status and a path beside its error.
A success that is not Spider Sense’s counts the same way, so a port that belongs to another server never prints its page as the answer or passes a check.
Spider Sense answers with a 2xx of the type asked for: text/markdown for the text, application/json for --json, the attachment spider-sense-….json for export, a JSON-RPC message for mcp, text/event-stream for tail, and 204 for unack and unresolve.
A redirect never is one, because the CLI follows none, and neither is a frontend dev server’s index.html or, asked for text, a health page’s JSON.
A check answer also carries the X-Spider-Sense-Pass header, and one without it is not a Spider Sense’s either, since a verdict that is not there must never read as a pass.
That is most often the application’s own port named as --url, and the line says so:
spider-sense: no Spider Sense at http://127.0.0.1:8082 (HTTP 404 for /api/status); is that the application's port?
A --url typed without a scheme, such as 127.0.0.1:4001, is read as http://127.0.0.1:4001.
A --url is a base URL, so one with a path, such as http://127.0.0.1:4000/api copied from a browser, is a usage error rather than a prefix of every request.
A Spider Sense’s own 404 for a route it does not have, such as an older version without /api/check, is not a missing trace or mark either: it is exit 2 with (HTTP 404 for /api/check); is it a Spider Sense of another version?.
A Spider Sense that accepted the connection and has not answered within 2 minutes is busy, not gone.
The CLI then prints spider-sense: the Spider Sense at <url> did not answer within 2 minutes and exits 2 without reading the file, since reading it in process would be slower still.
Naming --url states that a server is there.
When nothing answers it, the CLI prints spider-sense: no Spider Sense at <url> (…); if the application stopped, read its database with --db=<path> and exits 2, rather than silently falling back to a file that may hold a different application.
--db=<path or jdbc url> states the opposite, where to read, and the CLI goes straight to that file without asking any server.
In that path the thresholds are the defaults, or whatever --slow.request.ms, --slow.query.ms and --app.packages say, since no server is there to ask.
The file must exist and carry this version’s schema.
The CLI never creates a database and never upgrades one, because AUTO_SERVER=TRUE may have joined the database of an older Spider Sense that is still running, and recreating the tables would empty it under that server.
A jdbc: URL that names no file, such as jdbc:h2:mem:scratch, has no file to check, so the database behind it must hold this version’s schema already; an empty one is exit 2 with the database holds no Spider Sense schema on stderr.
A missing file is exit 2 and, on stderr:
spider-sense: no Spider Sense database at /home/me/db/spider-sense/sense.mv.db; start an application with -javaagent:spider-sense.jar first
A file of another schema version is refused the same way, with exit 2 and a message naming both versions.
A file that holds tables but no Spider Sense schema, such as the application’s own database named by a mistaken --db, is refused as well, with exit 2 and spider-sense: the database holds tables but no Spider Sense schema; point --db at the file an application under the agent or the standalone server writes.
A URL H2 itself refuses, such as a jdbc: URL without AUTO_SERVER=TRUE for a file the application holds open, is exit 2 with spider-sense: could not open <url>: ` and H2’s own reason.
A relative path, such as `db/sense.mv.db pasted from ls, is resolved against the working directory, since H2 refuses a path that is implicitly relative.
Six commands write rather than read, and they write in this path too: mark, ack, unack, resolve, unresolve and import.
tail is the one command that has no direct-file path, because there is no file to tail.
Text rendering
Every answer follows the conventions below, which keep it short: a statement is cut at 200 characters, and repeated sibling spans collapse into one line.
The same data renders to the same bytes, so two answers can be diffed.
The CLI writes them, and its messages on stderr, in UTF-8 whatever charset the platform gives its streams, so a JVM started without LANG or through a pipe on Windows still prints →, — and … rather than ?; a Windows console shows them once its code page is UTF-8 (chcp 65001).
The arguments are not covered: the JVM decodes its command line in the platform’s charset before the CLI runs, and one started without a UTF-8 locale reads it as ASCII, with each non-ASCII letter replaced by �, which the CLI cannot undo.
A --note, a mark name, a --q, a sql statement or a --db path with non-ASCII text therefore needs a UTF-8 locale, such as LANG=C.UTF-8 java -jar spider-sense.jar mark after --note="café → ok", or it is stored, searched or opened as the replaced text.
The CLI prints these renderings, and the HTTP API serves them too.
An agent-facing endpoint answers Markdown when it is asked with format=text, or with an Accept header whose first type is text/markdown or text/plain, and the response is then text/markdown; charset=utf-8.
JSON stays the default, and Agent-facing endpoints has the wire shapes.
The endpoints with a text rendering are /api/status, /api/findings, /api/findings/{id}, /api/marks, /api/compare, /api/check, /api/sql, /api/traces, /api/traces/{id}, /api/endpoints, /api/queries, /api/queries/{queryId}, /api/errors, /api/errors/{errorId}, /api/logs and /api/services.
The conventions:
-
The first line is a heading naming the answer and the window, in ISO-8601 with the offset of the answering Spider Sense’s time zone:
# findings 2026-09-18T12:37:06+09:00 → 12:41:08 (4m 1s, all services, 2456 requests). The start carries its milliseconds when it has any, such as2026-09-17T08:19:28.122+09:00for a window that begins at a mark, so it can be pasted into--since; the end is a time of day to the second. The range is rounded to the second and written in its largest units (6s,2m 30s,15m,2h), never in milliseconds. -
Lists are Markdown tables, and ids are complete: a trace id is 32 hex characters, an endpoint, query or error id 12, because a later command takes them whole, as
trace <traceId>andcheck --endpoint=<id>do. -
A trace and
logsare lines rather than a table, andstatusandmarkanswer in their own shape. -
Durations are milliseconds with one decimal and a thousands separator (
1,532.4 ms), counts are integers, rates are percentages with one decimal, and an Apdex is a score with three decimals. A count with its noun takes the singular for one alone, as in1 spanor# sql 1 row, and the plural for any other count, as in the UI. -
A cell with nothing in it is
—, and incomparethe two sides of a row share one cell,before → after. -
A cell is one line whatever text it holds: its newlines and runs of whitespace collapse to one space, and a
|in it is escaped, so an exception message, a note or a span name never splits a row. A finding’swhyline and itsnumbersline collapse the same way, with no escape since they are not table rows, so an error message never spills onto a line of its own. So does every other line that is not a table row, again with no escape: a finding’s statement, a trace’s statement and exception, a log line with its severity and logger, a service name in a heading, a span line or a mark, and the note after a mark or an acknowledgement, so a statement reads as SQL that can be pasted intoEXPLAIN. -
A control character, which a terminal would act on rather than print, is written as JSON escapes it, such as
\u001bfor ESC, wherever it stands: in a cell, a line, a statement, a frame or a heading. That covers C0, DEL and C1 (U+009B is a CSI on its own), and leaves the newline that ends each line of the answer as the only one it holds. An answer often quotes what a request sent the application, such as the parameter an exception message repeats, and an ESC in it would otherwise reach the terminal as an instruction, one that writes the clipboard or clears the screen.tailprints its lines the same way. -
A statement is cut at 200 characters with
…, and--fullkeeps it whole. This cut, and those of asqlcell and a finding’s title, stop before a surrogate pair they would split, such as an emoji, as the store’s cuts do (The writer), since half of one has no UTF-8 form. A statement of 1,999 characters or more may have been cut by the store, which keeps at most 2,000 of them, one fewer when the cut falls inside a surrogate pair, and records nothing when it cuts (statementCut). Such a statement ends in… (cut at 2,000 characters), after its 200th character or, with--full, after all the store kept, so it never reads as a whole statement to paste intoEXPLAIN. -
Nothing in the body depends on when it was rendered, only on the window.
nowappears only in the heading. -
An empty result says what was looked for and where, as in
no findings since 2026-09-18T12:42:26+09:00 (20s, 16 requests), and, when there was no request at all, how to send some: the OTLP endpoint. When the request count is zero because--servicenames no service Spider Sense has seen, it says that instead and lists the services there are, since data did arrive, under other names.
A trace
A trace is an indented tree, one span per line.
The trace below crosses two example applications, spring-orders calling silk-bookstore, and the repeated SELECT product spans under the entry span are collapsed into one row that carries the statement:
# trace 09e96c4c6db157e690716c2615ffd146 2026-09-18T12:37:29.077+09:00 12.2 ms spring-orders → silk-bookstore 20 spans, 10 db, 0 errors
offset duration span
0.0 ms 12.2 ms SERVER spring-orders GET /api/orders/{id}/enriched → 200
0.7 ms 0.6 ms INTERNAL OrderRepository.findById
0.7 ms 0.5 ms INTERNAL Session.find orders.domain.Order
0.9 ms 0.1 ms db SELECT orders
1.4 ms 0.0 ms db SELECT order_line
1.6 ms 0.0 ms db SELECT product × 4, 0.0 ms avg, 0.0 ms total
select p1_0.id,p1_0.name,p1_0.price,p1_0.sku from product p1_0 where p1_0.id=?
1.7 ms 0.0 ms db SELECT customer
1.8 ms 0.1 ms INTERNAL Transaction.commit
2.2 ms 2.7 ms CLIENT GET http://localhost:8081/api/books/155 → 200
3.3 ms 1.0 ms SERVER silk-bookstore GET /api/books/{id} → 200
3.7 ms 0.1 ms db SELECT books
5.6 ms 3.1 ms CLIENT GET http://localhost:8081/api/books/87 → 200
6.5 ms 2.0 ms SERVER silk-bookstore GET /api/books/{id} → 200
7.2 ms 0.1 ms db SELECT books
9.0 ms 2.4 ms CLIENT GET http://localhost:8081/api/books/27 → 200
9.9 ms 0.9 ms SERVER silk-bookstore GET /api/books/{id} → 200
10.3 ms 0.1 ms db SELECT books
Two spaces of indentation mark each level of depth, and the service is named only where it changes from the parent.
A span’s summary collapses its newlines and runs of whitespace to one space, so a statement written over several lines still takes one.
Consecutive sibling spans of one service with the same summary and category, alike in whether they failed and whether they are slow, none with children of its own, collapse after the third into one line with × n, the average and the total, as the waterfall folds them (Waterfall).
A failed or slow span among repeats that are neither therefore keeps a line of its own, and a collapsed line is marked [error] or [slow] only when every span in it is.
A database span that is slow, or the first of a collapsed group, shows its statement on the next line.
An error span shows its exception and the application frames under it, a collapsed line of failed spans its first span’s, and the trace’s log lines follow, oldest first.
--full lists every repeated span and keeps the statements whole.
trace and traces shows a failed trace with its exception, its frames and its log lines.
One finding
GET /api/findings/{id}?since&until&service answers one finding of the window, so a person who sees it in the UI can hand exactly it to an agent.
This is what the UI’s Copy as Markdown copies.
The rules run over the window as for the list, with no limit and with acknowledged and resolved findings included, and the answer is the finding with that id and its rank among them.
An id the rules do not produce over the window is 404.
Its text rendering is written by the code that writes the list, so apart from the heading its lines are the list’s bytes:
# finding n-plus-one:1d41bc5a9b2c 2026-09-18T12:37:06+09:00 → 12:41:08 (4m 1s, all services, 2456 requests)
| # | severity | state | kind | id | service | title |
| --- | --- | --- | --- | --- | --- | --- |
| 2 | medium | new | n-plus-one | n-plus-one:1d41bc5a9b2c | orders | GET /orders/{id} runs SELECT order_line 6 times per request |
2. n-plus-one:1d41bc5a9b2c — 1 of 1 request repeated it; 6 times; 12.0 ms per request in that statement
requests 1, affected 1, medianRepeats 6, maxRepeats 6, msPerRequest 12.0
select * from order_line where order_id = ?
traces: 4bf92f3577b34da6a3ce929d0e0e4736
The heading is the list’s with finding <id> in place of findings, over the same window and service.
The table has the list’s columns and the finding’s one row, numbered by its rank, and the evidence block under it is the one findings prints for that number.
findings --since=<from> --until=<to> --limit=100 over the same window prints both unchanged, bar the suspect-change lines it adds under the code frames, which no HTTP answer carries.
GET /api/errors/{errorId} and GET /api/queries/{queryId} answer the same way with format=text: the heading # error <errorId> or # query <queryId> over the window, then the errors or queries table with the group’s one row, and for an error the sample’s application frames as the list prints them.
The JSON of those two stays the pages' own (One query, One error group).
Trace diff
trace <a> --diff=<b> [--full] aligns two span trees and renders them as one text with a gutter, so after a fix you see which span went away and which one got slower without reading two trees.
Over HTTP it is GET /api/traces/{a}?diff={b}.
# trace diff 4bf92f3577b34da6a3ce929d0e0e4736 → 09e96c4c6db157e690716c2615ffd146 312.4 ms → 41.2 ms (−271.2 ms, −86.8%) 48 → 12 spans
a b span
= 312.4 ms 41.2 ms SERVER spring-orders GET /api/orders/{id}/enriched → 200
= 0.5 ms 0.4 ms INTERNAL OrderRepository.findById
- 38.2 ms — db SELECT product × 42
+ — 2.1 ms db SELECT product × 1
= 9.1 ms 8.7 ms CLIENT GET http://localhost:8081/api/books/155 → 200
The alignment works on the lines of the single-trace rendering, minus their timing.
Each span becomes the key (depth, category, summary with every run of digits replaced by one ?), so /api/books/155 and /api/books/87 are the same line, and a collapsed group keeps its summary and drops its count.
The two key sequences are then aligned by their longest common subsequence, each side cut at 2,000 lines.
A matched line is =, a line only in b is +, and a line only in a is -.
The heading carries both ids, both durations, the delta in milliseconds and in percent of a, and both span counts.
The columns are the gutter, a’s duration, `b’s duration, then the span line indented by depth as in the single rendering.
A side with no such span prints `—.
A collapsed group prints × n per side on its own line, so a count that changed is two lines, one - and one +.
Statement, exception and log lines are not diffed. A matched span shows its statement or its exception when either side has one, as the single rendering would.
--full expands collapsed groups on both sides before aligning.
Either id unknown is a 404 naming it over HTTP, and exit code 4 in the CLI.
The JSON is one object per line of the text:
{ "a": "<id>", "b": "<id>", "durationMs": { "a": …, "b": … }, "spans": { "a": 48, "b": 12 },
"lines": [ { "op": "=" | "+" | "-", "depth": 1, "summary": "…", "category": "…",
"aMs": … | null, "bMs": … | null, "count": { "a": 42, "b": null } | null } ] }
Tail
java -jar spider-sense.jar tail [--kind=slow-request|slow-query|error] [--service=<name>] [--until-traces=<n>] [--timeout=<duration>] [--json]
tail prints the live event stream, GET /api/events (Live events): one line per tingle event as it arrives, so an agent that has just sent a request sees its slow requests, slow queries and errors without sleeping and asking findings again.
12:37:28.565 slow-query spring-orders SELECT orders 1,532 ms 2519b548daad800090e8f56de6a5a62a
12:37:29.077 error silk-bookstore GET /api/books/stats ArithmeticException: / by zero 09e96c4c6db157e690716c2615ffd146
The columns are local time with milliseconds, kind, service, title, detail and trace id, which are the event’s own fields in that order.
--kind and --service each filter on one value, and without either every event is printed.
--until-traces=<n> ends with exit 0 once the stats events have shown n new traces since the command started, counted by tracesIngested, the traces the server has stored since it started (Live events), so a retention sweep that deletes old traces in the meantime does not hold the command up.
A stats event comes after the tingles of the traces it counts, so the lines of those traces are printed before it ends.
The stream opens with a stats event, so --until-traces=0 ends there, on an idle server too, and a negative n is a usage error.
--timeout=<duration> takes a selector duration such as 30s or 5m, and ends with exit 0 when it elapses.
It counts from the start of the command, so it also bounds the wait for a Spider Sense that took the connection and has not answered, such as one whose JVM is suspended in a debugger.
Without either, tail runs until it is interrupted.
A reader that went away, as head -1 does once it has its line, ends tail with exit 0 when it prints its next line, so tail --kind=error | head -1 ends at the error after the one head printed.
A stream the server closes first, as an embedded Spider Sense does when its application restarts, prints spider-sense: the Spider Sense at <url> closed the stream on stderr and exits 2, so a script never reads the traces it waited for as arrived.
--json prints the event’s JSON object per line instead, with "event": "tingle" (or "stats") added.
tail needs a running Spider Sense, because there is no file to tail.
Nothing at --url is a message on stderr and exit 2, and so is a server there that answers with something other than an event stream.
That holds whatever --timeout says: a connection refused, or not made within --timeout (given at least 100 ms, and at most the CLI’s 2-second connect timeout), is nothing at --url, so tail --timeout=0s with nothing there exits 2 as well.
Export and import
export writes the window as one JSON document, and import reads that document back into a store.
Together they move a session to another machine, attach it to a bug report, or keep it past the retention.
java -jar spider-sense.jar export --since=start --out=session.json.gz
java -jar spider-sense.jar import session.json.gz
export [--since=… --until=… --service=…] [--out=<file>] writes to stdout, or to the file --out names, gzipped when that name ends in .gz.
Over HTTP it is GET /api/export?since&until&service (or from and to) without traceId, streamed as it is read, with Content-Disposition: attachment; filename="spider-sense-<from>-<to>.json".
With traceId the answer is the single-trace export instead (Delete and export).
The document carries every service, span, log record, metric, metric series, metric point, tingle and mark of the window, and the index catalog (db_table) of its services:
{ "spiderSense": { "version": "0.1.0", "schema": 9, "exportedAt": …, "window": { "from": …, "to": … }, "service": "…" | null },
"services": [ { "name": "…", "language": "…", "pid": …, "firstSeen": …, "lastSeen": …, "resource": { … } } ],
"spans": [ { …every column of the span table except id, attributes and events as the objects they are… } ],
"logs": [ { …every column of log except id… } ],
"metrics": [ { "service", "name", "type", "unit", "description", "monotonic", "temporality" } ],
"metricSeries": [ { "id": 7, "service", "name", "attributes": { … } } ],
"metricPoints": [ { "seriesId": 7, "atMs", "value", "count", "sum", "min", "max", "buckets": { … } | null } ],
"tingles": [ { …every column except id… } ],
"marks": [ { "atMs", "name", "service", "note" } ],
"dbTables": [ { "service", "schemaName", "tableName", "product", "indexes": [ { "name", "unique", "columns": [ … ] } ], "seenMs" } ] }
Every key is its column’s name in camelCase, so each section holds the rows of one table and import writes them back column by column: at_ms is atMs, start_ms is startMs, parent_span_id is parentSpanId.
export writes entry, slow, queryId and every other derived column as stored, and import does not recompute them, so a span that was slow under the exporting machine’s slow.request.ms and slow.query.ms stays slow whatever the importing machine’s thresholds are.
dbTables is cut by service and not by time.
The extension reads a table’s indexes once per process, so the row behind the window’s statements was usually written before the window began, and every catalog row of the exported services travels, all of them when no service is given.
Its indexes is the stored array as an array, or the stored text as a string when that text is not JSON.
A slow-query or n-plus-one finding over the imported session therefore has the schema block it had where it was recorded.
import <file> [--url=… | --db=…] posts the document to the running Spider Sense, or, when none answers or --db names a file, writes into the file in process through the same code the server uses.
Over HTTP it is POST /api/import with the document as the body, Content-Encoding: gzip accepted, and the answer is 200 with the counts:
{ "spans": n, "logs": n, "metricPoints": n, "tingles": n, "marks": n, "dbTables": n, "skippedTraces": n, "window": { "from": …, "to": … } }
The command prints one line:
imported 12,345 spans, 456 logs, 7,890 metric points, 12 tingles, 3 marks (2 traces already present) from 2026-09-18T12:37:06+09:00 → 12:41:08
Import keeps every timestamp as exported, so set the time range to the answer’s window, or to all, to see the data.
Importing a file twice stores its rows once, by these rules.
-
A trace whose id already has rows in the store is skipped whole, its spans, logs and tingles, and
skippedTracescounts it. -
Any other log line, or tingle without a span, is skipped when an identical row is already stored, which is what keeps a line logged outside a span, such as a worker’s job log, from being imported again. A log line is identified by its service, instant, severity, body, logger and ids, and such a tingle by its instant, kind, service, title, detail and ids. Two identical rows in the file stay two rows.
-
A tingle of a span is skipped when a tingle of that span and kind is already stored, the key the writer stores it under (How it is written), so the file’s own copies of it are imported once.
-
A metric point is merged on its
(series, at)key, with the series looked up or created by(service, name, attributes). -
A service row is inserted when the store has none of that name, and otherwise only widens its first and last sighting, keeping the stored process id, language and resource. Those describe the process running here, not the one that ran the imported session.
-
A mark is skipped when one with the same name and instant exists, and a
startmark is never imported: it would claim a run of an application that is not running here and become the newest start of its service. A mark whose namePOST /api/marksrefuses, such as5mornow, refuses the document with a400naming it, since the mark could be listed but never selected. So does a mark at an instant it refuses, before the epoch, which the next sweep would delete, or past the year 9999, which no selector reaches. -
A catalog row is merged on its key
(service, schema_name, table_name)as the writer merges it (How it is written), so the table the file describes replaces the row the store had for it.
A document whose schema is not this version’s is a 400 naming both versions.
A document that is not JSON, or whose rows are not the shapes export writes, is a 400 naming what did not decode, and nothing of it is written.
A resource or an attributes that is not a JSON object, or events that are not an array of event objects, is such a row.
So is a document with a value the store refuses, such as a trace id longer than 32 characters or a required column left out, and the 400 carries H2’s own message.
In the CLI each of these is the 400’s sentence on stderr and exit `2, the same line from the file as over HTTP, and a .gz that is not gzipped is Undecodable import document: Not in GZIP format in both.
A file export cannot write or import cannot read is exit 2 with the operating system’s reason, as in spider-sense: could not write out: Is a directory.
Acknowledgements and resolutions are not exported, because they record what the user of the exporting store decided about a finding, not what the application sent.
SQL
java -jar spider-sense.jar sql "SELECT endpoint, COUNT(*) FROM span WHERE entry GROUP BY endpoint"
sql "<statement>" [--limit=200] runs one read-only statement over the schema, for a question no other command answers.
A statement that begins with a -- comment is still the statement, because a word whose option name would hold whitespace or a newline is the command’s own word rather than an option.
A bare -- ends the options, so every word after it is the statement, whatever it begins with.
findings, compare and check cover the kinds and the rules Spider Sense has, and the schema lists the tables and columns to query for anything else.
Reach for it last: findings, endpoints, queries, errors, compare and check are the same data with the thresholds, the ranking and the rendering already applied, and they stay correct when the schema changes.
The index catalog the extension reads is there too, as db_table.
SELECT table_name, indexes FROM db_table WHERE service = 'servlet-warehouse' lists every table a slow statement of that service has touched, with its indexes as JSON.
Over HTTP it is POST /api/sql with { "sql": "SELECT …", "limit": 200 }.
format=text as a query parameter, or an Accept whose first type is text/markdown or text/plain, selects the Markdown rendering, and the JSON is otherwise:
{
"columns": ["ENDPOINT", "STATEMENTS"],
"rows": [ ["GET /orders/{id}", 42], ["GET /orders", 7] ],
"rowCount": 2,
"truncated": false,
"elapsedMs": 3
}
A value is a JSON number, string, boolean or null, as the store holds it.
Every instant in the schema is epoch milliseconds and stays a number, and an H2 TIMESTAMP a statement computes itself is an ISO string.
The answer is a heading and a table:
# sql 2 rows
| ENDPOINT | STATEMENTS |
| --- | --- |
| GET /orders/{id} | 42 |
| GET /orders | 7 |
The column headers are H2’s own labels, which upper-case an unquoted name (SERVICE, SPANS), so alias a column when the heading matters.
At most 200 rows come back unless --limit=<n> says otherwise, and the cap is 5000; a limit below 1 is a 400 over HTTP, and a usage error on the command line.
One row more than the limit is fetched, so truncated reports whether the cap cut the answer off rather than guessing at it.
The heading carries ` (truncated at 200)` when the cap cut the answer off, and a truncated answer is a sample rather than a total.
--json prints columns, rows, rowCount, truncated and elapsedMs instead of the table.
The conventions hold here too.
Nothing in the body depends on when it was rendered, so elapsedMs is in the JSON only.
A cell is cut at 200 characters with … unless --full (full=true) is given, a | in a cell is escaped, and its newlines collapse to spaces.
Numbers are printed as the store holds them, without a thousands separator, so a value can be pasted into the next statement as it reads.
A SQL NULL is —, and a double that is NaN or infinite reads NaN, Infinity or -Infinity, as the JSON answer’s string does.
An ARRAY or a row value is its JSON text (["GET /a","GET /b"]), as the JSON answer writes it.
A CLOB is its text and a BLOB its bytes in hex (01ff), so the same statement over the same data renders the same bytes.
Read-only, in three layers
Each layer catches what the one before it cannot. The second is the guarantee, because there H2 itself refuses a write.
-
A statement allowlist. After the leading whitespace and the
--and/* */comments are stripped, the first keyword must beSELECT,WITH,TABLE,VALUES,EXPLAINorSHOW, and there must be one statement: a;followed by anything but whitespace is refused. A;inside a'…'or"…"literal or H2’s dollar-quoted…string does not count.FOR UPDATEis refused too: it reads, but it locks rows the writer would then wait on past its lock timeout. String literals and comments make this a scanner over SQL text rather than a parser, so a statement it misreads is left to the second layer to refuse. -
A user with
SELECTand nothing else. The schema createsspider_sense_reader, idempotently, on every open by a server of this version, and grants itSELECTon schemaPUBLIC(The read-only user). The statement runs on a connection opened as that user, with the same JDBC URL. H2 itself therefore refusesINSERT,UPDATE,DELETE,DROPandALTERwith "Not enough rights for object", and the administrator-only functionsFILE_WRITE,CSVWRITE,FILE_READ,LINK_SCHEMAandRUNSCRIPTwith "Admin rights are required for this operation", whatever the layer above thought it read. -
The limits of the connection.
setMaxRows(limit + 1), a query timeout of 10 seconds,setReadOnly(true), autocommit off, and arollback()whatever happens.
Only a server creates the reader user, when it opens the database.
The direct-file path opens the reader connection the same way, and a database an older Spider Sense created has no reader user in it yet.
sql then reports the database has no read-only user yet; start an application or the standalone server with this version first on stderr and exits 2.
A statement that is not allowed is a 400 with { "error": "…" } naming the reason, and a statement H2 refuses or cannot parse is a 400 carrying H2’s own message.
In the text rendering, and so in the CLI, an error is that message on one line, because an agent that asked for Markdown should not have to parse a JSON object it did not expect.
Bounding the window
There is no --since here, because the window is a predicate you write.
Every instant in the schema is epoch milliseconds in a BIGINT, and every duration is nanoseconds, so arithmetic on times is plain integer arithmetic.
Two predicates bound most windows:
-- the last 15 minutes of data, whenever the data ends
WHERE s.start_ms >= (SELECT MAX(start_ms) FROM span) - 15 * 60 * 1000
-- since the mark you set before the change
WHERE s.start_ms >= (SELECT MAX(at_ms) FROM mark WHERE name = 'before')
(SELECT MAX(at_ms) FROM mark WHERE name = 'start') is the last restart.
Without a predicate on start_ms or at_ms the query reads the whole retention, which is up to 24 hours of everything.
Three predicates on span select the rows most questions are about: entry counts requests, category = 'db' counts statements, and error counts failures.
The schema has every table and column.
Worked queries
The endpoints that issue the most distinct statements, a ranking findings cannot make.
An endpoint may run few statements often or many statements once, and the n-plus-one rule, which counts repeats of one statement, reports only the first.
SELECT e.endpoint,
COUNT(DISTINCT d.query_id) AS statements,
COUNT(d.id) AS db_calls,
COUNT(DISTINCT e.id) AS requests
FROM span e
JOIN span d ON d.trace_id = e.trace_id AND d.service = e.service AND d.category = 'db'
WHERE e.entry
AND e.start_ms >= (SELECT MAX(start_ms) FROM span) - 15 * 60 * 1000
GROUP BY e.endpoint
ORDER BY statements DESC, db_calls DESC
The p95 per minute for one route. Findings give one p95 over the window, and this says whether it was the whole window or one bad minute.
SELECT s.start_ms / 60000 * 60000 AS minute_ms,
COUNT(*) AS requests,
ROUND(PERCENTILE_DISC(0.95) WITHIN GROUP (ORDER BY s.duration_ns) / 1000000.0, 1) AS p95_ms,
ROUND(MAX(s.duration_ns) / 1000000.0, 1) AS max_ms
FROM span s
WHERE s.entry AND s.endpoint = 'GET /orders/{id}'
GROUP BY s.start_ms / 60000 * 60000
ORDER BY minute_ms
The statements of one trace, in order.
trace <id> collapses repeated siblings, and this lists every one of them with its offset, which is what to read when the repeats are not identical.
SELECT s.start_ns - (SELECT MIN(start_ns) FROM span WHERE trace_id = s.trace_id) AS offset_ns,
ROUND(s.duration_ns / 1000000.0, 1) AS ms,
s.service, s.db_operation, s.db_table, s.db_statement
FROM span s
WHERE s.trace_id = '4bf92f3577b34da6a3ce929d0e0e4736' AND s.category = 'db'
ORDER BY s.start_ns
Errors per endpoint per hour. Findings rank error groups over one window, and this says whether a group is growing.
SELECT s.start_ms / 3600000 * 3600000 AS hour_ms,
s.service, s.endpoint,
COUNT(*) AS requests,
SUM(CASE WHEN s.error THEN 1 ELSE 0 END) AS errors
FROM span s
WHERE s.entry
GROUP BY s.start_ms / 3600000 * 3600000, s.service, s.endpoint
HAVING SUM(CASE WHEN s.error THEN 1 ELSE 0 END) > 0
ORDER BY hour_ms DESC, errors DESC
The pools' worst pending value per five minutes.
The pool-exhausted finding names the single worst point, and this says whether requests waited for a connection once or throughout the window.
SELECT p.at_ms / 300000 * 300000 AS five_minutes_ms,
ms.service, ms.attributes AS pool,
MAX(p.value) AS pending_max
FROM metric_point p
JOIN metric_series ms ON ms.id = p.series_id
WHERE ms.name IN ('db.client.connections.pending_requests', 'db.client.connection.pending_requests')
GROUP BY p.at_ms / 300000 * 300000, ms.service, ms.attributes
ORDER BY five_minutes_ms DESC
The requests that ran the most statements.
The N+1 rule fires at 5 repeats of one statement, so a request that ran 40 different statements gets no n-plus-one finding, and this lists it.
SELECT e.endpoint, e.trace_id, COUNT(*) AS db_calls,
ROUND(SUM(d.duration_ns) / 1000000.0, 1) AS db_ms
FROM span e
JOIN span d ON d.trace_id = e.trace_id AND d.category = 'db'
WHERE e.entry
GROUP BY e.endpoint, e.trace_id
HAVING COUNT(*) >= 10
ORDER BY db_calls DESC
What was logged inside the failed traces.
SELECT l.at_ms, l.severity, l.service, l.logger, l.body, l.trace_id
FROM log l
JOIN trace t ON t.trace_id = l.trace_id
WHERE t.error AND l.severity_number >= 13
ORDER BY l.at_ms DESC
Add the id or the name as the last ORDER BY key, so two runs over the same data print the same rows in the same order.