Check
check turns thresholds into a pass or a fail, and puts the verdict in the exit code, so a script or a build fails on it as it fails on a failing test.
java -jar spider-sense.jar check [--since=] [--until=] [--service=] [--endpoint=] [--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=]
Over HTTP, the endpoint is GET /api/check?since&until&service&endpoint&…rules…&format=.
The rules are query parameters in camel case (maxP95Ms, maxErrors).
The response also carries the verdict as the header X-Spider-Sense-Pass: true|false|none, so the CLI asks once for the text rendering and still exits with a code.
The rules
Every rule given is evaluated, and each one is a limit compared against a value measured over the window.
A value counts every group and every finding of the window, never the top of a list, so a finding past the 20 that findings prints by default still counts toward its rule.
| Rule | Default | The value it judges |
|---|---|---|
|
|
The highest p95 of any endpoint in scope. |
|
|
Error groups' occurrences, summed. |
|
none |
Failed entry spans over entry spans. |
|
none |
Database spans per entry span, the highest of any endpoint; a database span counts for its nearest entry span of its own service, as |
|
none |
Query calls over |
|
|
The number of |
|
none |
|
|
|
The number of |
|
none |
The Apdex over the scope. |
When no rule is given the default set is --max-errors=0, --max-n-plus-one=0, --max-regressions=0 and --max-p95-ms=<slow.request.ms>.
Naming a rule replaces that set, and only the rules named are then evaluated.
A limit is a finite decimal number (500, 0.05, 1e3); NaN, an infinity and Java’s 5d or 0x1p3 are refused, as a usage error on the command line and a 400 over HTTP, because NaN fails every comparison and an infinity passes every one.
--endpoint= narrows the scope to one endpoint, by endpointId or by name (GET /api/orders/{id}), and the heading names it.
Over HTTP an empty endpoint= narrows nothing, as an empty service= filters nothing.
An endpoint the window does not have, while the window has requests, is a usage error (exit 2, 400 over HTTP) that names the endpoint and points at endpoints, rather than a check with no request to judge, so a mistyped endpoint cannot pass a build as exit 3.
A name that endpoints of several services share is a usage error too, without --service, since one verdict over all of them would fail one service’s endpoint for another’s: it lists each service with its endpoint’s id, the two ways to name one of them.
--max-n-plus-one and --max-regressions then count only the findings about that endpoint.
--service= narrows the scope to one service.
requests counts the entry spans in scope, as Endpoint identity defines an entry span, so a seeder’s or a scheduler’s root spans never make a verdict of their own.
A job is never a request, so check says nothing about one.
slow-job is the one place a slow scheduler tick or batch step is reported.
check does not look at acknowledgements.
Its rules compare what was measured against the limits given, so --max-n-plus-one counts an acknowledged n-plus-one finding like any other.
The window
check takes the same window as every other command: --since defaults to 15m and --until to now.
Time selectors lists every accepted form.
After a change, --since=after judges only the traffic that followed the mark, and --since=start judges only the run that followed the restart.
A window that reaches back before the change holds the requests made before it, so their durations, errors and findings count toward the verdict.
Exit codes
| Code | Meaning |
|---|---|
|
|
|
|
|
A usage or connection error. The command was wrong, or nothing answered at |
|
There was no request to judge, so the verdict is |
|
Something named was not found, such as a mark name used as a selector. |
The text rendering
The heading carries the verdict, then the window.
One row follows per rule, with its limit, its actual value, its own verdict and a detail naming what decided it.
The limit reads as it was given, an Apdex is a score with three decimals, and the error rate’s limit and actual value are percentages, as every rate in a rendering is.
The error rate’s limit moves the decimal point of the number given, so --max-error-rate=0.07 reads 7.0% and 0.0005 reads 0.05%, never the 7.000000000000% that 0.07 * 100 is in binary.
An actual value that is not its limit carries as many more decimals as it takes to read differently from it, in the row and in the detail alike, so a rule that fails by less than the usual precision reads | maxQueriesPerRequest | 1 | 1.04 | fail | rather than 1.0 beside its limit.
A detail names its worst offender the way findings does: maxErrors gives the occurrences of the scope, then the largest error group by the title of its error finding and its own occurrences (2 occurrences: IllegalStateException in GET /api/flaky ×2), and maxNPlusOne and maxLogErrors give the title of their first finding.
$ 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
Naming rules replaces the default set, and every rule named is evaluated:
$ java -jar spider-sense.jar check --since=after --max-queries-per-request=3 --min-apdex=0.9
# check fail 2026-09-17T08:19:35.837+09:00 → 08:19:45 (10s, all services, 12 requests)
| rule | limit | actual | verdict | detail |
| --- | --- | --- | --- | --- |
| maxQueriesPerRequest | 3 | 6.7 | fail | GET /api/orders/{id} runs 6.7 database calls per request |
| minApdex | 0.900 | 0.792 | fail | Apdex 0.792 over 12 requests |
$ echo $?
1
--json prints the JSON instead: pass (true, false, or null when there was no request in scope), requests, reason, and one object per rule under checks with its rule, limit, actual, pass and detail.
limit and actual are unrounded, and the error rate is a fraction there, as the limit was given.
{
"pass": false,
"requests": 12,
"reason": null,
"checks": [ { "rule": "maxP95Ms", "limit": 500, "actual": 812.4, "pass": false,
"detail": "GET /orders/report p95 812.4 ms over 3 calls" } ]
}
reason is null when pass is not.
When pass is null it is no requests in the window, or, when --service names no service Spider Sense has seen, a sentence that says so and lists the services there are.
In a build
check exits 1 when a rule is over its limit, so as a build step it fails the build when a change made the application slower.
The spiderSenseCheck task runs it from Gradle with the thresholds declared in the spiderSense block, and fails the build on exit code 1.
In CI, run the application under the agent, exercise it, and then run check over a window that starts at the restart:
java -jar spider-sense.jar check --since=start --max-p95-ms=300 --max-n-plus-one=0 --max-errors=0
Exit code 3 means the exercise step sent no request, so treat it as a failure of the pipeline rather than as a pass.