The CLI

$ 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 |
| oldest span | 2026-09-17T08:14:07.250+09:00 |

$ java -jar spider-sense.jar findings --since=before
# findings  2026-09-17T08:19:28+09:00 → 08:19:34  (6s, all services, 21 requests)

| # | severity | kind | id | service | title |
| --- | --- | --- | --- | --- | --- |
| 1 | high | error | error:eecf9878a68f | spring-orders | IllegalStateException in GET /api/flaky |
| 2 | medium | n-plus-one | n-plus-one:4c5f46be8bc5 | spring-orders | GET /api/orders/{id}/enriched runs SELECT product 5 times per request |
| 3 | medium | slow-query | slow-query:6b3aae6f9bef | spring-orders | SELECT p.id AS product_id, p.sku AS sku, p.name AS name, SUM… is slow |

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

$ 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

$ java -jar spider-sense.jar trace 5e6769395a77c8f192949af91cbdedf2
# trace 5e6769395a77c8f192949af91cbdedf2  2026-09-17T08:19:28.962+09:00  22.0 ms  spring-orders  1 spans, 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

$ java -jar spider-sense.jar traces --since=before --limit=5
# traces  2026-09-17T08:19:28+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 |

$ java -jar spider-sense.jar endpoints --since=before
# endpoints  2026-09-17T08:19:28+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 |

$ java -jar spider-sense.jar queries --since=before --limit=5
# queries  2026-09-17T08:19:28+09:00 → 08:19:35  (7s, all services, 21 requests)

| id | service | calls | slow | p50 | p95 | max | total | callers | 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=? |

$ java -jar spider-sense.jar errors --since=before
# errors  2026-09-17T08:19:28+09:00 → 08:19:35  (7s, all services, 21 requests)

| id | service | type | message | 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)

$ java -jar spider-sense.jar logs --since=before --limit=3
# logs  2026-09-17T08:19:28+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

$ 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 |

$ java -jar spider-sense.jar compare --before=before --after=after
# compare  2026-09-17T08:19:28+09:00 → 08:19:35  vs  2026-09-17T08:19:35+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 | before | after |
| --- | --- | --- | --- | --- | --- |
| same | 458522ccda9f | java.lang.IllegalStateException | Payment gateway timeout | 1 | 1 |

$ java -jar spider-sense.jar check --since=before
# check  fail  2026-09-17T08:19:28+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 over the window |
| maxNPlusOne | 0 | 2 | fail | 2 findings: GET /api/orders/{id} runs SELECT product 5 times per request |

$ echo $?
1

$ 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]      the findings of the window
  ...

Common options:
  --since=<selector>   default 15m
  --until=<selector>   default now
  --service=<name>     one service
  --limit=<n>          the lists: findings, traces, queries, errors, logs, marks,
                       and the rows of sql (default 200, at most 5000)
  --url=<base url>     default http://127.0.0.1:4000, or SPIDERSENSE_URL
  --db=<path or jdbc url>   read the database directly, without asking any server
  --json               the JSON of api.md instead of the text
  --full               whole statements, every repeated span
  --hide-acked         findings only: leave acknowledged findings out

A selector is a duration (30s, 5m, 2h, 1d), epoch milliseconds, a mark name,
start (the newest automatic start mark) or now.

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 unack).

-- 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 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

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

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

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

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

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

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