The HTTP API

The HTTP API is the contract between spider-sense-server and the UI under src/main/resources/public.

Both sides are built against this page. A change here is a change to both.

Conventions

  • All times are epoch milliseconds (integers) in JSON. Durations are milliseconds as doubles (12.34), rounded to three decimals, a microsecond, unless the field name ends in Ns. The values of a metric series and the attribute values of a span or a log are in their own units, seconds as often as milliseconds, and are written as they are, unrounded.

  • Every read endpoint takes an optional window from and to (epoch ms). The default to is now, and the default from is to - 15 min. A window that starts before the epoch or ends past the year 9999 (253402300799999) is a 400, which is what a time in microseconds or nanoseconds becomes. window.bucketMs grows with the range, by whole days past a range of 72 days, so a window of any length holds at most 75 buckets.

  • service filters are exact matches on service.name. An empty service=, which is what the UI’s selects send for every service, is no filter. A path parameter is one percent-encoded segment, so a service name or a finding id that holds a / travels as %2F, and one that holds a % as %25.

  • Lists are newest first unless stated.

  • Unknown query parameters are ignored. A malformed number is a 400 ({"error": "…​"}). So is a JSON body that is not the object an endpoint takes, or that carries a field of the wrong type.

  • Every JSON answer is application/json; charset=utf-8. An error is {"error": "<message>"} with a 4xx or 5xx status. That includes a path the HTTP server refuses before any route sees it, such as a segment holding %5C or %2E%2E, which is a 400. A read the store stopped at its 30-second timeout is a 503 with The read took longer than 30 seconds and was stopped. Try again, or ask over a shorter range. (How it is read).

  • Every answer carries the header X-Spider-Sense: <version>, with the version /api/status reports: a JSON or Markdown answer, an error, a page of the UI, a static file and the event stream alike. The CLI reads an answer without it as another server’s, since an application on the URL can answer JSON of its own to any path (The direct-file fallback).

  • A JSON request body is at most 1 MB (1,048,576 bytes), which is Spider Silk’s default, and a larger one is 413 with {"error": "Request body is larger than the limit of 1048576 bytes"}. The limit applies to POST /api/marks, POST /api/findings/{id}/ack, POST /api/findings/{id}/resolve and POST /api/sql, whose bodies are a name, a note or one statement, far below it. POST /mcp has the same limit and answers it with a JSON-RPC error (MCP). The bodies that hold telemetry have limits of their own: 64 MB for OTLP and 256 MB for an import.

  • A request whose Host is not a name of this machine, or whose Origin is not the server’s own, is 403. A web page open in the developer’s browser can reach 127.0.0.1 too, by a cross-origin request or by pointing a name of its own at it (DNS rebinding), and this API writes and reads without credentials. A loopback name (localhost, 127.0.0.1, [::1]) or the bind address is accepted as Host, and any Host once the bind address is a wildcard (0.0.0.0, ::). The CLI, an MCP client and an OpenTelemetry exporter send no Origin.

  • traceId is 32 lowercase hex characters, and spanId is 16. The group ids (queryId, errorId, endpointId) are opaque strings, a hash of the group key, stable for the life of the process.

Ingest (OTLP/HTTP)

POST /v1/traces
POST /v1/metrics
POST /v1/logs

The request Content-Type is application/x-protobuf or application/json, and Content-Encoding: gzip is accepted. The answer is 200 with an empty Export{Trace,Metrics,Logs}ServiceResponse in the request’s content type. An undecodable body is 400, another content type is 415, and a body of more than 64 MB, counted after gunzip, is 413. The receiver reads the body into the heap of the process it runs in, which in agent mode is the monitored application’s. Everything decodable is stored, except the spans the ingest cap drops (The ingest cap) and the two kinds of span Status and ingest names: the SERVER spans of requests to the embedded server’s own port, and the spans of H2’s internal management_db_ database. A trace export that loses spans to the cap is answered with a partial success, as OTLP asks of a request accepted in part: partial_success.rejected_spans counts the dropped spans, and error_message names spidersense.ingest.max-spans-per-second. An exporter does not send rejected spans again. A span received again, as an exporter sends an export whose answer it did not get, is stored once (How it is written). So is a tingle raised from it, which the live event stream publishes once as well. A log record carrying the attribute spidersense.schema.table is the index catalog of one table, as read by the extension. It is stored as a db_table row rather than as a log (Storage).

Status and control

Status

GET /api/status

{
  "name": "Spider Sense",
  "version": "0.1.0",
  "mode": "agent" | "standalone",
  "startedAt": 1758000000000,
  "now": 1758000900000,
  "endpoint": "http://127.0.0.1:4000",
  "otlp": { "traces": "http://127.0.0.1:4000/v1/traces", "metrics": "...", "logs": "..." },
  "embeddedService": "silk-bookstore" | null,
  "thresholds": { "slowRequestMs": 500, "slowQueryMs": 100, "responseBucketsMs": [125, 500, 2000] },
  "ignore": { "endpoints": ["/actuator/**", "/health", "/healthz", "/livez", "/readyz"] },
  "codeFrames": { "appPackages": [] | ["com.acme."], "frameworkPrefixes": ["java.", "javax.", …],
                  "generatedMarkers": ["$HibernateProxy", "$$SpringCGLIB$$", …] },
  "jar": "/home/me/tools/spider-sense-0.1.0.jar" | null,
  "retention": { "hours": 24, "spans": 1000000 },
  "ingest": { "maxSpansPerSecond": null | 5000 },
  "storage": { "url": "jdbc:h2:~/db/spider-sense/sense;AUTO_SERVER=TRUE", "path": "/home/me/db/spider-sense/sense.mv.db", "sizeBytes": 12345678, "fallback": false, "fallbackReason": null, "droppedBatches": 0, "droppedSpans": 0, "queued": 0 },
  "counts": { "spans": 12345, "traces": 2345, "logs": 456, "metricSeries": 78, "services": 2 },
  "services": ["spring-orders", "silk-bookstore"],
  "oldest": { "span": 1758000000000, "log": 1758000000000 }
}

endpoint is the base URL to connect to, and the OTLP URLs are built on it: a wildcard bind address (0.0.0.0, ::) is advertised as 127.0.0.1, as the startup banner prints it. embeddedService is the service whose JVM the server runs inside: spidersense.service when the launcher was given one, else the first service that reports the server’s own process id. It is always null in standalone mode, which runs inside no application, even when spidersense.service is set for the applications beside it. ignore.endpoints is the configured value of spidersense.ignore.endpoints, which Ignored endpoints describes. codeFrames carries the rules that make a frame the application’s (Code locations): appPackages is spidersense.app.packages as prefixes ending in a dot, empty when unset, frameworkPrefixes the prefixes that count as framework when it is unset, and generatedMarkers what a generated class’s frame holds, which is never the application’s either way. The error page folds its stack trace by them (Stack traces). services names the services the store has seen, the most recently seen first and then by name, at most 20 of them; counts.services is how many there are in all. A reader confirms that the application just started is sending by finding its name in services. jar is the absolute path of the distributable jar the server was started from, which the launcher passes to the server. It is null when it is not known, as when the server runs from exploded classes. The UI’s Copy CLI line names it (Copy as Markdown).

Delete and export

DELETE /api/data answers 204. It deletes every span, trace, log, metric point and metric series, tingle, mark, acknowledgement, resolution and index catalog (db_table). Services, metric metadata and each service’s newest start mark stay, so since=start still names the run of a process that keeps running. An index catalog comes back after the application restarts, because the extension looks each table up once per process (The index catalog).

GET /api/export?traceId answers one trace as an application/json download (Content-Disposition: attachment) of { "traces": [<trace as in GET /api/traces/{id}>] }.

GET /api/export?from&to&since&until&service without traceId answers the session document described in Export and import, streamed. POST /api/import takes that document back and answers the counts. It accepts Content-Encoding: gzip. A document of more than 256 MB, counted after gunzip, is 413.

Live events

GET /api/events answers text/event-stream. The events are:

event: tingle
data: {"kind":"slow-request"|"slow-query"|"error","at":1758000000000,"service":"spring-orders","title":"GET /orders/report","detail":"1,532 ms","traceId":"...","spanId":"...","durationMs":1532.4}

event: stats
data: {"at":1758000000000,"spans":12345,"traces":2345,"logs":456,"droppedSpans":0,"tracesIngested":2400,"perSecond":{"spans":12.5,"logs":3.0}}

event: service
data: {"name":"spring-orders","firstSeen":1758000000000}

stats is sent at most every second while data arrives, and a flush that commits while a frame is being counted is in the next frame, whatever the millisecond. A stats frame goes out after the tingle events of the traces it counts, so a client that waits for a count has their tingles by then. spans, traces and logs are the store’s row counts, which a retention sweep or a clear lowers; tracesIngested is the number of traces whose trace row this server’s writer inserted since it started, which nothing lowers, so a client that waits for new traces compares it. service is sent once for a service the store had no row of, when the row is stored, so /api/services lists the service by the time the event arrives; firstSeen is the row’s first_seen. The row is stored by a flush of an export or by an import (POST /api/import), whose service events go out once its transaction has committed, one for each service row it inserted. A : keepalive comment is sent every 15 s.

Overview

GET /api/overview?from&to&service

service narrows totals, series and tingles to one service. services stays the list of every service, so the Overview’s cards still offer the others.

{
  "window": { "from": 1758000000000, "to": 1758000900000, "bucketMs": 15000 },
  "totals": { "requests": 1200, "errors": 12, "errorRate": 0.01, "rps": 1.33, "p50Ms": 12.1, "p95Ms": 210.4, "p99Ms": 840.0, "maxMs": 1532.4,
              "apdex": 0.93, "histogram": [900, 200, 70, 18, 12] },
  "services": [ <ServiceSummary> ],
  "tingles": [ <Tingle> ],            // one per service, kind and title, newest first, at most 50, within window
  "series": {                          // one point per bucket, aligned across arrays, oldest first
    "t": [1758000000000, ...],
    "requests": [12, ...],
    "errors": [0, ...],
    "p95Ms": [120.5, ...],             // null where the bucket is empty
    "histogram": [[9, ...], [2, ...], [1, ...], [0, ...]]   // non-error requests per response-time bucket, one array per bucket
  }
}

Response-time buckets and Apdex

The response-time buckets and Apdex give a response summary, a load chart and an Apdex score. thresholds.responseBucketsMs is [T/4, T, 4T] with T = slowRequestMs, so the default buckets are ≤125 ms, ≤500 ms, ≤2 s and >2 s. Every histogram is five counts: the non-error requests in each of the four buckets, then the error count. The five sum to requests. apdex is (histogram[0] + histogram[1] + histogram[2] / 2) / requests, so a request is satisfied up to T, tolerating up to 4T, and an error is frustrated. It is rounded to three decimals, and null when there is no request. In a series, histogram is four aligned arrays, one per bucket. The errors of a time bucket are already in series.errors.

ServiceSummary

{
  "name": "spring-orders",
  "language": "java",              // telemetry.sdk.language or null
  "embedded": false,
  "firstSeen": 1758000000000,
  "lastSeen": 1758000900000,
  "requests": 800, "errors": 10, "errorRate": 0.0125, "rps": 0.9,
  "p50Ms": 10.0, "p95Ms": 300.0, "p99Ms": 900.0, "maxMs": 1532.4,
  "apdex": 0.91, "histogram": [600, 150, 30, 10, 10],
  "sparkline": [3, 5, 0, 8, ...],   // requests per bucket, oldest first, same buckets as overview.series.t
  "hasJvm": true                    // any jvm.* metric seen
}

Tingle

{ "kind": "slow-request" | "slow-query" | "error", "at": 1758000000000, "service": "…", "title": "GET /orders/report", "detail": "1,532 ms" | "SELECT … FROM …" | "IllegalStateException: …", "traceId": "…", "spanId": "…", "durationMs": 1532.4, "count": 12 }

count is on the rows of /api/overview alone. A tingle event is one occurrence and carries none (Events).

Services

GET /api/services?from&to answers { "services": [ <ServiceSummary> ] }. It lists every service the store knows, which is every service seen until the sweep forgets it (Retention), with zero counts and rates when nothing falls in the window, and null for its percentiles, its maxMs and its apdex.

GET /api/services/{name}?from&to answers the service, its resource attributes and its traffic in the window. Every resource value is a string: a string attribute as itself, any other as its JSON text, so process.pid reads "42" and an array such as process.command_args reads ["/usr/bin/java","-Dnames=a, b"], its elements apart however many commas they hold.

{
  "service": <ServiceSummary>,
  "resource": { "service.name": "…", "telemetry.sdk.name": "opentelemetry", "process.runtime.version": "21.0.4", ... },   // every value a string, sorted by key
  "window": { "from": ..., "to": ..., "bucketMs": ... },
  "series": { "t": [...], "requests": [...], "errors": [...], "p50Ms": [...], "p95Ms": [...], "p99Ms": [...], "histogram": [[...], [...], [...], [...]] },
  "endpoints": [ <EndpointStats> ],   // sorted by total time desc
  "queries": [ <QueryStats> ],        // top 10 by total time
  "errors": [ <ErrorGroup> ],         // top 10 by count
  "dependencies": [ { "kind": "http" | "db" | "messaging" | "rpc", "target": "localhost:8081" | "h2:orders", "calls": 120, "errors": 0, "avgMs": 4.2, "p95Ms": 9.1 } ]
}

EndpointStats

{ "endpointId": "…", "service": "…", "method": "GET" | null, "route": "/orders/{id}", "name": "GET /orders/{id}", "kind": "SERVER",
  "calls": 120, "errors": 2, "errorRate": 0.0167, "rps": 0.13,
  "avgMs": 12.0, "p50Ms": 9.0, "p95Ms": 40.0, "p99Ms": 90.0, "maxMs": 300.0, "totalMs": 1440.0,
  "apdex": 0.98, "histogram": [110, 6, 2, 0, 2],
  "statusCodes": { "200": 118, "500": 2 } }

Endpoints

GET /api/endpoints?from&to&service answers { "endpoints": [ <EndpointStats> ] } across services, sorted by total time descending.

GET /api/endpoints/{endpointId}?from&to answers { "endpoint": <EndpointStats>, "series": {…​as service series…​}, "queries": [<QueryStats>], "errors": [<ErrorGroup>], "traces": [<TraceSummary> + "matchMs" x 20 slowest], "recent": [<TraceSummary> x 20 newest], "breakdown": { "db": 0.44, "http": 0.21, "internal": 0.07, "self": 0.28 } }.

queries are the query groups this endpoint called and errors the error groups that occurred in it, sorted as /api/queries and /api/errors sort them. Both are read from every group of the endpoint’s service, never the top of a list, and matched by service as well as by name, so two services that expose the same route never share them.

traces are slowest by the endpoint’s own span in each, not by the trace’s duration, as a finding’s evidence is (Fields); for a query, its slowest call in each. A trace is in traces and recent when the endpoint’s span, or the query’s call, starts in the window, whenever the trace began, so a request under a job that was already running is listed with the requests it is counted among. Each of them carries matchMs beside the trace’s durationMs: the duration of that span, the endpoint’s slowest request in the trace or the query’s slowest call, which is what the list is ordered by. breakdown is where the endpoint’s time went over the 20 slowest traces, the same four shares a slow-endpoint finding carries (Where the time went). It is {} when those traces add up to nothing.

Traces

GET /api/traces?from&to&service&endpointId&minMs&maxMs&status=error|ok|all&by=trace|entry&q&limit=50&before=<epoch ms>&beforeId=<traceId>

minMs and maxMs

Whole milliseconds; a trace is listed when its duration is above minMs and at most maxMs. The lower bound is open and the upper closed, as the Response summary’s buckets are, so the lists behind two neighbouring bars never share a request on their common bound.

by

What from and to, minMs and maxMs, status, service and endpointId are read off. With trace, the default, they are the trace’s: its start, its duration, whether any of its spans failed, and any of its spans for the service and the endpoint. With entry they are one entry span’s: a trace is listed when one of its entry spans starts in the window, is of the service and the endpoint, lasts between the bounds, and has the status. That is what the Scatter draws and what the Response summary counts, so a downstream request, a request that answered while a statement under it failed and was handled, and a request that started after its trace did are listed behind the bar or the rectangle they are drawn in. q and the order, newest trace first, are the same either way.

q

A case-insensitive substring match over the root span name, every span name, and every string attribute value of the trace. It also matches the trace id, whole or by its first 8 digits or more (Free-text search).

before and beforeId

Page backwards from the last row of the previous page, its start and its traceId. With both, the next page holds the traces that start before before, and those that start in the same millisecond with a smaller traceId. With before alone, it holds the traces that start strictly before it.

{ "traces": [ <TraceSummary> ], "total": 2345, "window": {...} }

TraceSummary

{ "traceId": "…", "start": 1758000000000, "durationMs": 152.3,
  "rootName": "GET /orders/{id}", "rootSummary": "GET /orders/{id} → 200" | null, "rootService": "spring-orders", "rootKind": "SERVER",
  "services": ["spring-orders", "silk-bookstore"], "spanCount": 14, "errorCount": 0, "dbCount": 6, "httpStatus": 200,
  "slow": true, "error": false }

rootSummary is the root span’s summary (Span), and null when the root span is not stored. rootName is the root’s endpoint name, or its span name when it has none. OpenTelemetry names an HTTP client span by its method alone, so a trace that starts in a client has the rootName GET and the rootSummary GET http://localhost:8083/items/SKU-58 → 200. A TraceSummary carries rootSummary in every JSON answer, and the text renderings keep rootName.

One trace

GET /api/traces/{traceId}

With diff=<traceId> it answers the two traces aligned instead, as Trace diff specifies, in JSON or with format=text.

{
  "traceId": "…", "start": ..., "end": ..., "durationMs": ...,
  "services": ["…"],
  "spans": [ <Span> ],       // sorted by start then span id, parents before children; a parentSpanId not present in the trace is shown as a root, and so is the first member of a parent cycle
  "logs": [ <LogRecord> ]    // logs carrying this traceId, oldest first
}

Every span of the trace is listed once. A span that is its own parent, and spans that name each other as parents, are still listed: the first member of the cycle in the spans' order (start, then span id) is shown as a root, and the cycle’s other members hang under it. The text rendering draws the same tree.

Span

{ "spanId": "…", "parentSpanId": "…" | null, "service": "…", "name": "GET /orders/{id}", "kind": "SERVER",
  "start": 1758000000000, "startNs": 1758000000000123456, "durationMs": 152.3, "durationNs": 152300000,
  "status": "UNSET" | "OK" | "ERROR", "statusMessage": "…" | null,
  "attributes": { "http.request.method": "GET", "server.port": 8081, "db.statement": "…", ... },  // values: string | number | boolean | array of those
  "events": [ { "name": "exception", "time": 1758000000100, "attributes": { "exception.type": "…", "exception.message": "…", "exception.stacktrace": "…" } } ],
  "scope": "io.opentelemetry.spring-webmvc-6.0",
  "category": "http" | "db" | "messaging" | "rpc" | "internal",   // derived from attributes, for colouring
  "summary": "GET /orders/{id} → 200" | "SELECT orders" | "…",          // one line the waterfall shows
  "slow": false, "error": false,
  "endpointId": "…" | null, "queryId": "…" | null, "errorId": "…" | null }

endpointId, queryId and errorId name the groups the span belongs to, the ids GET /api/endpoints/{endpointId}, GET /api/queries/{queryId} and GET /api/errors/{errorId} answer. Each is null when the span has no such group. An entry span has an endpoint, a database span a query group, and a failed span an error group, so a failed statement has two of them. A failed span of an ignored endpoint’s request has no errorId, since no error group counts it (Ignored endpoints).

Service map

GET /api/map?from&to

The answer is the topology of the window. There is one node per service, per database, per external HTTP host and per messaging destination, plus one user node for the traffic that comes from outside every traced service.

{
  "window": {...},
  "nodes": [
    { "id": "user", "kind": "user", "name": "Clients" },
    { "id": "svc:spring-orders", "kind": "service", "name": "spring-orders",
      "requests": 800, "errors": 10, "errorRate": 0.0125, "rps": 0.9,
      "p50Ms": 10.0, "p95Ms": 300.0, "p99Ms": 900.0, "maxMs": 1532.4,
      "apdex": 0.91, "histogram": [600, 150, 30, 10, 10], "hasJvm": true },
    { "id": "db:h2:orders", "kind": "db", "name": "h2:orders", "calls": 2400, "errors": 0, "avgMs": 4.2, "p95Ms": 9.1 },
    { "id": "http:localhost:8081", "kind": "http", "name": "localhost:8081", "calls": 12, "errors": 0, "avgMs": 30.0, "p95Ms": 80.0 }
  ],
  "edges": [
    { "from": "user", "to": "svc:spring-orders", "calls": 780, "errors": 10, "avgMs": 42.0, "p95Ms": 300.0 },
    { "from": "svc:spring-orders", "to": "svc:silk-bookstore", "calls": 120, "errors": 0, "avgMs": 25.0, "p95Ms": 60.0 },
    { "from": "svc:spring-orders", "to": "db:h2:orders", "calls": 2400, "errors": 0, "avgMs": 4.2, "p95Ms": 9.1 }
  ]
}
  • A service node exists for every service with an entry span in the window. Its numbers are the ServiceSummary numbers.

  • A service → service edge is counted from the entry spans of the callee whose parent span, in the same trace, belongs to another service. calls, errors, avgMs and p95Ms are those entry spans'.

  • A user → service edge is counted from SERVER and CONSUMER entry spans whose parent is absent or not stored: the request came from something that is not traced. A span whose parent is not stored counts only once it ended more than 2.2 s before the server’s clock, because that parent may be a client span still on its way (Map).

  • Every other node is an outbound target, grouped as the dependencies of GET /api/services/{name} group them. kind is db, http, messaging or rpc, and name is the dependency’s target. An edge runs from each service that calls it. A root CLIENT or PRODUCER span, such as a traced load generator’s request, is a call too, so a service whose requests go to a host nobody traces is on the map with that host, and has it among its dependencies. An outbound span whose child is a SERVER or CONSUMER span called a traced service, so it is no external target. An http or rpc span counts only once it ended more than 2.2 s before the server’s clock, because that child may still be on its way, and the dependencies of a service do not wait. A call to another service counts as that service → service edge: a call to localhost:8081 therefore shows as a call to silk-bookstore when the bookstore is traced too. An HTTP or RPC call a service makes to itself, such as a job calling its own endpoint, counts as nothing, since no edge runs from a service to itself. A call to an ignored endpoint of a traced service (Ignored endpoints) counts as nothing too, since that endpoint answered no request. A message a service produces and consumes itself still went through the broker, so its PRODUCER span is a call to the messaging destination, and the service is on the map with it. An ignored endpoint’s own span is a request the service answered rather than a call it made, so it is neither a dependency nor an edge: a health check never shows as a call to the service’s own host and port.

  • A node with no edge is not listed, so a service whose only traffic is calls to itself does not appear.

  • A parent is "not stored" only when it is absent from the database, whatever the window. A parent that was traced but starts before the window still counts as a traced caller, not as a user.

Scatter (response-time scatter)

GET /api/scatter?from&to&service&endpointId&limit=5000

The answer is one point per entry span in the window, newest first, cut at limit. truncated says whether the list was cut, so the UI can shrink the window: it is true only when the window holds more than limit entry spans, never when it holds exactly limit.

{ "window": {...}, "truncated": false,
  "points": [ [1758000000123, 152.3, "spring-orders", "GET /orders/{id}", "<traceId>", 0], ... ] }

A point is [start, durationMs, service, endpointName, traceId, flags] with flags a bit set: 1 = error, 2 = slow, 4 = contains a slow query. The points are arrays rather than objects so that an answer of 5,000 points does not repeat six field names in each.

Queries

GET /api/queries?from&to&service&sort=total|avg|p95|max|calls&limit=100

{ "queries": [ <QueryStats> ] }

QueryStats

{ "queryId": "…", "service": "…", "system": "h2", "namespace": "orders" | null, "operation": "SELECT" | null, "table": "orders" | null,
  "statement": "select … from orders where … like ?", "statementCut": false,
  "calls": 240, "errors": 0, "avgMs": 45.0, "p50Ms": 40.0, "p95Ms": 120.0, "maxMs": 900.0, "totalMs": 10800.0,
  "slowCalls": 12,                       // calls over slowQueryMs
  "callers": [ { "endpoint": "GET /orders/report", "endpointId": "…" | null, "service": "spring-orders", "calls": 240 } ],
  "lastSeen": 1758000900000,
  "schema": { "tables": [...], "predicates": [...], "unindexed": [...] } | null }

statement is what the store kept, at most 2,000 characters (db_statement). statementCut is true when it is 2,000 characters long, or 1,999, which is where a cut inside a surrogate pair ends, since the store may then have cut it; nothing in the row says whether it did, so the UI and the text renderings mark such a statement as cut. schema is the index catalog of the statement’s tables and the columns it filters on that no index serves, as the schema block defines it. It is null when there is no catalog to read.

One query

GET /api/queries/{queryId}?from&to answers { "query": <QueryStats>, "code": [ "orders.ReportRepository.revenue(ReportRepository.java:27)" ], "series": { "t": […​], "calls": […​], "p95Ms": […​] }, "traces": [<TraceSummary> + "matchMs" x 20 slowest containing it] }. traces are slowest by the query’s slowest call in each, whose duration is matchMs (Endpoints). code is where the statement is issued: the application frames a slow-query finding on the group carries, read from the same span, the newest that has code.stacktrace (Code locations). It is empty when no span of the group in the window names an application frame. With format=text it answers the group as the queries rendering prints it (One finding), and a group with no call in the window is 404 in both JSON and text.

Errors

GET /api/errors?from&to&service&limit=100

{ "errors": [ <ErrorGroup> ] }

ErrorGroup

{ "errorId": "…", "service": "…", "type": "java.lang.IllegalStateException", "message": "Order ? is already shipped",
  "target": "GET localhost:8081/api/flaky" | null,
  "count": 12, "firstSeen": ..., "lastSeen": ...,
  "endpoints": [ { "name": "POST /orders/{id}/ship", "endpointId": "…" | null, "count": 12 } ],
  "sample": { "traceId": "…", "spanId": "…", "at": ..., "message": "Order 42 is already shipped", "stacktrace": "…" } | null,
  "series": [0, 2, 0, 1, ...] }

target is the outbound HTTP call the group’s occurrences mostly are, the call an error finding’s title names (error), and null for any other group. A failed call with no exception has a status for its type and an empty message, so target is the one field that names the call that failed.

series is the group’s occurrences per time bucket over the window, oldest first, which the Errors page draws as a sparkline. The buckets are the window’s (window.bucketMs, the Overview’s), merged ⌈n / 30⌉ at a time from the oldest, so there are at most 30 points and they sum to count. Only GET /api/errors carries it; an ErrorGroup inside another answer does not.

One error group

GET /api/errors/{errorId}?from&to answers { "error": <ErrorGroup>, "code": [ "orders.OrderService.load(OrderService.java:41)" ], "chain": [ <Cause> ], "series": { "t": […​], "count": […​] }, "traces": [<TraceSummary> x 20 newest] }. code is the sample stack trace’s application frames, reduced by the rules a finding’s code follows (Code locations). The root cause’s frames come first, then those of each exception wrapping it. code is empty when there is no sample or no application frame. chain is the sample stack trace read as its exceptions, innermost first: the root cause, then each exception that wraps it, out to the outer one. It is empty when there is no sample or no stack trace. With format=text it answers the group as the errors rendering prints it (One finding), and a group with no occurrence in the window is 404 in both JSON and text.

Cause

A Cause, one entry of chain:

{ "type": "org.h2.jdbc.JdbcSQLIntegrityConstraintViolationException", "message": "Unique index or primary key violation: …",
  "frames": [ "org.h2.message.DbException.get(DbException.java:223)", "orders.OrderRepository.save(OrderRepository.java:41)" ],
  "more": 42 }

frames are every frame the section prints, top first, written as code writes a frame, with no module or class-loader prefix. more is the count of the …​ n more line, the frames the cause shares with the exception wrapping it, and 0 when there is none. A Suppressed: block is not a cause and is left out. A trace without a header (no Type: message line) is one cause whose type is "". A message that spans lines keeps its line breaks.

Source

GET /api/source?frame=<code frame> answers the lines around a code frame’s line, read from the file when asked and never stored:

{ "frame": "orders.OrderService.load(OrderService.java:41)",
  "file": "/home/me/project/src/main/java/orders/OrderService.java",
  "line": 41, "start": 39,
  "lines": [ "…line 39…", "…line 40…", "…line 41…", "…line 42…", "…line 43…" ] }

frame is a frame as a finding’s code carries it. It resolves to the first <root>/<package as directories>/<file> that exists under the roots of spidersense.source.dirs (Source roots). file is that file’s absolute path with symbolic links resolved, line is the frame’s line, and lines runs from start to two lines past line, cut at the start and the end of the file. A file edited since the frame was recorded may therefore answer fewer lines, or none. A frame that does not resolve is 404, and so is one without a file and a line (Unknown Source, Native Method, a code.function frame) and one whose path would leave its root. A missing frame is 400. The path is built from the frame only when it parses as dotted Java identifiers, a method, and a plain file name with a .java, .kt, .groovy or .scala extension. The resolved file, symbolic links followed, must lie under its root. Nothing else is read.

Logs

GET /api/logs?from&to&service&severity=TRACE|DEBUG|INFO|WARN|ERROR&q&traceId&limit=200&before=<epoch ms>&beforeId=<id>

severity is a minimum, so WARN shows WARN and ERROR. A record’s own severity is the name of its OTLP severity range, and UNSET when the sender gave no severity number. before and beforeId are the last row’s at and id, and page backwards as they do on /api/traces.

{ "logs": [ <LogRecord> ], "total": 456 }

LogRecord

{ "id": 12345, "at": 1758000000000, "service": "…", "severity": "INFO", "severityNumber": 9,
  "body": "Started OrdersApplication in 2.1 seconds", "logger": "o.s.boot.StartupInfoLogger",   // logger from the scope name
  "traceId": "…" | null, "spanId": "…" | null,
  "attributes": { "thread.name": "main", "exception.stacktrace": "…" } }

Metrics

GET /api/metrics?service answers the catalog:

{ "metrics": [ { "name": "jvm.memory.used", "type": "gauge" | "sum" | "histogram", "unit": "By", "description": "…", "services": ["…"], "series": 6 } ] }

GET /api/metrics/series?name&service&from&to&attr.<key>=<value>&step=<ms>

{ "name": "jvm.memory.used", "type": "gauge", "unit": "By",
  "series": [ { "service": "…", "attributes": { "jvm.memory.type": "heap", "jvm.memory.pool.name": "G1 Eden Space", "process.pid": 12345 }, "t": [...], "v": [...] } ] }

A series is one process’s: its attributes carry the process.pid and the service.instance.id of the resource that exported it, so two processes of one service answer a series each, even two containers whose JVMs both run as pid 1 (The writer).

For a histogram, v is the per-point sum/count mean, and each series also carries "count": […​], "p95": […​] (estimated from buckets) and "max": […​]. v, p95 and max are in the metric’s unit and unrounded, so a duration histogram in seconds keeps its fractions of a millisecond. The p95 is interpolated inside the bucket that crosses it, narrowed to the point’s own min and max, so it never passes the max beside it. For a monotonic sum such as jvm.cpu.time, v is the rate per second between points when rate=true, and the cumulative value otherwise. A cumulative point is differenced from the one before it, and a point below the one before it, which is the counter resetting when the process restarted, has no rate; a DELTA point is already the increment, and is divided by the seconds since the one before it. A histogram is no sum, so rate=true leaves it as it is, its count included: the count of a cumulative jvm.gc.duration stays the collections since the JVM started.

JVM

GET /api/jvm?service&from&to answers the curated view, with empty arrays when the service sent no JVM metrics:

{
  "service": "…", "runtime": { "jvm": "OpenJDK 64-Bit Server VM 21.0.4", "pid": 12345, "host": "…", "cpuCount": 8 },
  "heap":    { "t": [...], "used": [...], "committed": [...], "limit": [...] },
  "nonHeap": { "t": [...], "used": [...], "committed": [...] },
  "pools":   [ { "name": "G1 Eden Space", "type": "heap", "t": [...], "used": [...] } ],
  "gc":      [ { "name": "G1 Young Generation", "action": "end of minor GC", "t": [...], "count": [...], "durationMs": [...] } ],   // per bucket
  "threads": { "t": [...], "count": [...], "daemon": [...] },
  "cpu":     { "t": [...], "utilization": [...], "systemLoad1m": [...] },
  "classes": { "t": [...], "loaded": [...] },
  "connectionPools": [ { "name": "HikariPool-1", "t": [...], "used": [...], "idle": [...], "max": [...], "pending": [...] } ]
}

A service that several processes export at once, an application and its tests or two instances of one application, is the sum of its processes. The gc counts and durations are each process’s own differences between consecutive points, added in the buckets. A gauge, such as heap, threads or a pool’s used, has a point at every instant of any process, at which each process counts with its latest value, from its first point to one export interval past its last. Two processes running together therefore add up rather than take turns, and a restarted process follows the one it replaced rather than being added to it. A process whose first point comes within one export interval of the earliest point of all was already running then, so it counts from there with its first value. systemLoad1m is the machine’s load, which every process reads alike, so it is the highest of the processes rather than their sum. The sums are what the page draws; the heap-pressure, thread-growth and pool-exhausted rules read each process’s heap, threads and pools on their own (Kinds).

connectionPools feeds the JVM page’s connection pool charts. It holds one entry per JDBC pool the agent instruments (HikariCP, Tomcat JDBC, c3p0, and so on), and is empty when the service reports none. It is read from db.client.connections.usage (attribute state = used or idle, pool from pool.name), db.client.connections.max and db.client.connections.pending_requests. It is also read from their stable-semconv names db.client.connection.count (db.client.connection.state, db.client.connection.pool.name), db.client.connection.max and db.client.connection.pending_requests. max and pending are null where the pool reports no such series.

Agent-facing endpoints

This section specifies only the wire shape. The semantics are specified elsewhere in this manual: the time selectors and verdicts in Marks and Compare, the finding rules in Findings, the rules of check in Check, and the text renderings in The CLI.

Time selectors

since and until are accepted by the endpoints below and by every windowed endpoint of this page, as an alternative to from and to. from and to win when both are given. A selector is a duration (30s, 5m, 2h, 1d), an ISO-8601 date-time (2026-10-08T05:50:00+09:00, or without an offset in the server’s time zone, the one its text renderings print), epoch milliseconds (13 or more digits), a mark name (the newest mark with that name), start (the newest automatic start mark, of service when given) or now. since defaults to 15m, and until to now. The ` of an offset is `%2B` in a query string, and a space in its place, which is what an unencoded ` arrives as, is read as one. An unknown mark name is 404, and a since after until is 400. So is a from after to, and the message names the parameters that were sent, such as from is 1970-01-01T09:00:00.005+09:00, which is after to 1970-01-01T09:00:00.003+09:00. An end that neither to nor until sent is named now, as in from is 2286-11-21T02:46:39.999+09:00, which is after now (2026-10-16T07:49:19.761+09:00).

Text rendering

format=text, or an Accept header whose first type is text/markdown or text/plain, answers text/markdown; charset=utf-8 instead of JSON. It applies to /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. full=true keeps statements whole, as far as the store kept them, and expands collapsed spans. The format of each rendering is given in The CLI.

Marks

GET /api/marks?limit=50 answers { "marks": [ <Mark> ] }, newest first.

POST /api/marks with { "name": "before", "note": "…" | null, "service": "…" | null, "at": <epoch ms> | absent } answers 201 and the <Mark>. name is required and matches [A-Za-z0-9._-]{1,64}, and is otherwise 400; so is a name a selector reads as something else, such as 5m, now or start (Marks). An at before the epoch or past the year 9999 is a 400 as it is for a window, since no selector could use the mark. service is cut to 255 characters and note to 1024, the widths of their columns, and the answer carries them as stored. A blank note is stored as null, here and in ack and resolve, and so is a blank service.

Mark:

{ "id": 12, "at": 1758000000000, "name": "before", "service": "spring-orders" | null, "note": "pid 12345" | null }

The writer inserts a mark named start when a service reports a process.pid that no start mark of that service names yet (Automatic start marks).

Findings

GET /api/findings?since&until&service&limit=20&hideAcked=false answers { "window": {…​}, "requests": 120, "acked": 2, "resolved": 1, "total": 54, "findings": [ <Finding> ] }. The findings are ranked as Findings specifies, with regressions first and acknowledged findings and resolved findings that have not come back last. hideAcked=true leaves the acknowledged and the resolved findings out. limit is at most 100. total is how many findings the list was cut from, counted before the limit and after hideAcked, so findings holding fewer than total means the limit cut it (The rules).

GET /api/findings/{id}?since&until&service answers { "window": {…​}, "requests": 120, "rank": 3, "finding": <Finding> }, or 404 when the rules do not produce that id over the window. rank is the finding’s place among every finding the list would answer over the same window and service, acknowledged and resolved ones included, whatever limit would have cut. Its text rendering is the list’s row and evidence block for it (One finding).

POST /api/findings/{id}/ack with { "note": "…" | null } answers 201 and { "findingId": "…", "at": …, "note": … }. It answers 400 when the id is not <kind>:<12 hex digits>, and 404 when it names no finding of the data kept (Acknowledgements). DELETE /api/findings/{id}/ack answers 204 or 404. GET /api/acks answers { "acks": [ { "findingId", "at", "note" } ] }, newest first. Acknowledgements describes what an acknowledgement means.

POST /api/findings/{id}/resolve with { "note": "…" | null } answers 201 and { "findingId": "…", "at": …, "note": … }, or 400 and 404 as ack does. DELETE /api/findings/{id}/resolve answers 204 or 404. Resolutions describes what a resolution means.

Finding:

{ "id": "n-plus-one:1a2b3c4d5e6f",
  "kind": "regression" | "error" | "log-error" | "n-plus-one" | "n-plus-one-http" | "slow-query" | "slow-endpoint" | "slow-job" | "slow-external" | "pool-exhausted" | "gc-pause" | "heap-pressure" | "thread-growth",
  "severity": "high" | "medium" | "low", "state": "new" | "ongoing" | "regressed", "service": "…", "title": "…", "why": "…",
  "subject": { "endpointId": "…" | null, "queryId": "…" | null, "errorId": "…" | null, "pool": "…" | null, "job": "…" | null,
               "target": "…" | null, "logger": "…" | null, "jvm": "…" | null },
  "numbers": { ...kind-specific... },
  "statement": "…" | null, "statementCut": false, "code": [ "orders.OrderService.load(OrderService.java:41)" ], "traces": [ "<traceId>" ],
  "schema": { "tables": [ { "table": "ITEMS", "schema": "PUBLIC" | null,
                            "indexes": [ { "name": "PRIMARY_KEY_8", "unique": true, "columns": [ "ID" ] } ] } ],
              "predicates": [ "items.name" ], "unindexed": [ "items.name" ] } | null,   // slow-query and n-plus-one
  "ack": { "at": …, "note": "…" | null } | null,
  "resolution": { "at": …, "note": "…" | null } | null }

numbers carries the fields of the finding’s kind, listed with each kind in Findings. statementCut is true when the store may have cut the statement, as on QueryStats. schema is the schema block, on a slow-query or n-plus-one finding and null everywhere else.

Compare

GET /api/compare?before=<selector>&after=<selector>&until=<selector>&service answers the two windows [before, after) and [after, until):

{ "before": { "from": …, "to": … }, "after": { "from": …, "to": … },
  "totals": { "before": <Totals>, "after": <Totals> },
  "endpoints": [ { "endpointId": "…", "service": "…", "name": "…", "before": <Side> | null, "after": <Side> | null, "verdict": "better" | "worse" | "same" | "new" | "gone" } ],
  "queries":   [ { "queryId": "…", "service": "…", "statement": "…", "statementCut": false, "before": <QuerySide> | null, "after": <QuerySide> | null, "verdict": "…" } ],
  "errors":    [ { "errorId": "…", "service": "…", "type": "…", "message": "…", "target": "…" | null, "before": 0, "after": 3, "verdict": "…" } ] }

Side is { "calls", "errors", "p50Ms", "p95Ms", "maxMs", "dbCallsPerRequest", "dbMsPerRequest" }. QuerySide is { "calls", "callsPerRequest", "p95Ms", "totalMs" }, with callsPerRequest null in a window that has no request (Verdicts). A query’s statementCut is the one of QueryStats. An error’s target is the one of ErrorGroup, read over the before window, then over the after window when the group is no failed call in the first. before and after are required, and a missing one is 400. In the answer, before.to and after.to are the last millisecond of each window, one before the after and the until that end them.

Check

GET /api/check?since&until&service&endpoint&maxP95Ms&maxErrors&maxErrorRate&maxQueriesPerRequest&maxSlowQueries&maxNPlusOne&maxLogErrors&maxRegressions&minApdex

{ "pass": true | false | null, "requests": 12, "reason": "no requests in the window" | "No service is named `nope`; …" | null,
  "checks": [ { "rule": "maxP95Ms", "limit": 500, "actual": 812.4, "pass": false, "detail": "GET /orders/report p95 812.4 ms over 3 calls" } ] }

With no rule given the defaults are maxErrors=0, maxNPlusOne=0, maxRegressions=0 and maxP95Ms=<slowRequestMs>. endpoint is an endpointId or an endpoint name, and one the window does not have, while the window has requests, is 400. The response also carries the verdict as the header X-Spider-Sense-Pass: true|false|none. The CLI can therefore ask once for the text rendering and still exit with a code, rather than parse prose for a word.

SQL

POST /api/sql with { "sql": "SELECT …", "limit": 200 }, and format=text as a query parameter when the Markdown rendering is wanted:

{ "columns": ["ENDPOINT", "STATEMENTS"], "rows": [ ["GET /orders/{id}", 42], ["GET /orders", 7] ],
  "rowCount": 2, "truncated": false, "elapsedMs": 3 }

columns are H2’s own labels, which upper-case an unquoted name. A cell is a JSON number, string, boolean or null, as the store holds it, and an H2 TIMESTAMP is an ISO string. An ARRAY or a row value is a JSON array of its elements, and a JSON value is its text, an element of an ARRAY such as ARRAY_AGG(JSON_OBJECT(…)) builds as much as a column. A CLOB is its text, and a BLOB or a BINARY value is its bytes in lowercase hex. A whole number is exact up to a long; one past it is the nearest double, and one past a double’s range is its decimal string. A double that is NaN or infinite, such as SQRT(-1) or POWER(10, 400), is the string NaN, Infinity or -Infinity, so a null cell is only ever a SQL NULL. limit defaults to 200 and is capped at 5000. A limit below 1 is a 400. truncated says whether the cap cut the rows off. The statement must be a single SELECT, WITH, TABLE, VALUES, EXPLAIN or SHOW, and it runs as an H2 user that has SELECT and nothing else (the CLI’s sql, the read-only user). A refused statement and a statement H2 would not run are both 400: { "error": "…" }, or the message on one line when the text rendering was asked for. A body of more than 1 MB is 413 with { "error": "…" } in either format, because no statement was read (Conventions).

MCP

POST /mcp takes one JSON-RPC 2.0 message as application/json. MCP specifies the semantics, the eight tools and their arguments.

  • A request (id present) is answered 200 with the JSON-RPC response as application/json. A notification is answered 202 with no body.

  • There is no session: no Mcp-Session-Id header is issued or read. GET /mcp and DELETE /mcp are 405.

  • A body that is not a JSON object, or is a JSON array, is 200 with a JSON-RPC error -32600. A body of more than 1 MB is 413 with a JSON-RPC error -32600 whose id is null, since the message was never read. A method the server does not have is -32601. A missing required argument or an unknown tool name is -32602.

  • A tool call that the CLI would report with exit code 4, or with a 400, is a 200 whose result carries isError: true and the message as its one text content.

  • tools/call for check also carries structuredContent: { "pass": true | false | null, "requests": 12 }.

Static UI

GET / and every path without an /api/ or /v1/ prefix that has no file answer the UI’s index.html. The UI’s router is hash-based, so in practice this path is almost always /.

GET /assets/** answers files under public/assets.

Clarifications

This section records the decisions the server made where the contract left room, so the UI can rely on them.

Endpoint identity

An entry span’s endpoint name is METHOD route when http.route is present and is not a servlet-mapping wildcard (/, /, or anything ending in /). Otherwise it is the span name. A wildcard mapping matches every path, so using it as the route would name every endpoint of a Spring Boot application GET /*. OpenTelemetry already names a server span METHOD route or just METHOD. An endpoint’s route follows the same rule: its http.route when that is a real route, and otherwise the path of its name, so GET /books/{id} gives /books/{id}. It is null when the name is not a path. A span whose endpoint name matches spidersense.ignore.endpoints (Ignored endpoints) is stored with entry false and no endpoint. Such a span still appears in its trace and in /api/traces, but in nothing that counts requests. endpointId is the first 12 hex characters of the SHA-256 of service + " " + name. queryId hashes service\0system\0statement the same way. errorId hashes service\0rootCauseType\0frame, the frame without its file position and with $<digits> made $?, or service\0type\0normalisedMessage when the trace has no application frame (Errors).

Callers and error endpoints

QueryStats.callers[].endpoint and ErrorGroup.endpoints[].name are the nearest entry span up the parent chain within the trace, not the trace’s root. A query issued by the second service of a two-service trace is therefore attributed to that service’s own endpoint. A span whose chain reaches no entry span but ends at a root span, as every span of a job’s trace does, is attributed to that root span’s name, which for a job is the job (Endpoint identity). It is a label only: a job is still no endpoint, counts no request, and no id hashes the label. A span whose chain leaves the window is reported as (no endpoint). So is a span whose chain runs into a parent cycle before it reaches an entry span: the walk stops when it comes round the cycle, so a malformed trace adds at most one pass round its cycle to the walk. endpointId is that entry span’s endpoint, the id GET /api/endpoints/{endpointId} answers, so the UI links the row to the endpoint’s page. It is null for (no endpoint), for a job named by its root span, and for an entry span that has no endpoint name, which the list names by its span name. Both lists are sorted by count descending, then by name, so the endpoint an error finding’s title names is the same on every call over the same window.

Nulls in series

Every duration that has no value is null, never 0. That covers a percentile in a bucket with no requests, the first point of a rate=true series and a point where its counter reset, and an estimated p95 for a histogram point that carries no buckets, or whose one bucket has no bound (a Micrometer timer bridged by the agent). It covers totals that counted no request too: those of the overview, of a ServiceSummary, of a service node of the map and of a side of compare have null for p50Ms, p95Ms, p99Ms and maxMs, as they have for apdex. jvm.nonHeap has no limit array, and cpu.systemLoad1m is an empty array on a platform that reports no load average.

Ordering and sorting

GET /api/metrics is sorted by metric name. GET /api/endpoints and the endpoints of GET /api/services/{name} are sorted by total time descending. queries defaults to sort=total, and errors is sorted by count descending. Lists paged with before are newest first, with the row id breaking a tie inside the same millisecond: a log’s id, a trace’s traceId. beforeId carries that id into the next page, so a burst of rows in one millisecond is never cut at a page boundary.

q on /api/traces matches, case-insensitively, any span name or any part of the span’s attribute JSON in that trace. It runs as the LOWER(name) LIKE ? ESCAPE '\' OR LOWER(attributes) LIKE ? ESCAPE '\' that Storage describes. A q of 8 to 32 hex digits matches the trace id as well, whole or by its start, so an id pasted from a log line, or cut to the 8 digits the UI shows, finds its trace in the window. A shorter q is matched as text alone, since 500 or add is more often a value than the start of an id. q is a plain substring on both endpoints: its %, _ and \ are escaped, so 100% matches the text "100%" and not every text that starts with "100". An attribute value is found as it reads, though the JSON holds its quotes, backslashes and control characters escaped: C:\Users\me finds the path the JSON holds as C:\\Users\\me, and from "ORDERS" finds a statement that quotes its identifiers. A q that holds such a character is matched against the attribute JSON both as it reads and as the JSON writes it, so it still finds the JSON text itself. Span event attributes, notably exception.message, are not searched. Search an error’s endpoint or type instead, or use /api/errors. q on /api/logs matches the body, the logger and the attribute JSON, so the logger a log-error finding names finds its records.

Metrics

The metadata of a metric is each service’s own, so every series of /api/metrics/series is read by the type and temporality of the service that exported it. A catalog entry for a name several services export takes its type, unit and description from the first of its services. step on /api/metrics/series is accepted and ignored. A series holds one point per export, 5 seconds apart under the launcher’s default otel.metric.export.interval, and combining them into longer steps would hide a spike that lasts one export. rate=true changes v only for a monotonic sum, and leaves other types unaffected. An exponential histogram is stored as a histogram with count, sum, min and max only, so its p95 is null. A histogram point whose sender did not report its max, which OTLP leaves optional, has a max of null rather than 0. A point flagged NO_RECORDED_VALUE, which is how a collector forwards a Prometheus staleness marker, and a number point with no value at all are not stored, so the series has no point at that instant rather than a 0. runtime.jvm is process.runtime.name + " " + process.runtime.version, falling back to process.runtime.description. GET /api/jvm without service answers for the first service that sent any jvm.* metric, which locally is usually the only one.

Errors

An error group is the root-cause type and the innermost application frame of the stack trace, or the type and the normalised message when there is no application frame (Errors). ErrorGroup.message is the normalised message, where digits become ? and quoted strings become '?'. sample.message is one real message as received. ErrorGroup.type is the exception type, else error.type, else the literal error. Both are the outer exception’s, as the span recorded it. The members of a group keyed by its frame may differ in them, and the group shows the greatest of each.

Status and ingest

For an in-memory database, /api/status.storage.path is null and sizeBytes is 0. The in-memory database is the fallback, and the one the tests use. counts.spans counts stored spans, so spans dropped by the self-monitoring rule are not in it. That rule drops only the SERVER spans on the server’s own port of the service it is embedded in, embeddedService. A standalone server is embedded in nothing, so it drops none, and an application on another host or in a container that serves on the same port keeps its requests. A CLIENT span calling that port is a call the application itself made to Spider Sense, and it stays in its trace. The spans of H2’s own bookkeeping are dropped at ingest as well, and they are not in counts.spans either. An application that opens H2 with AUTO_SERVER=TRUE starts a TCP server, and H2 runs that server’s statements on an internal database named management_db_ and the port, which nobody opened and which is renamed at every start. A span whose db.namespace, or older db.name, is exactly that, management_db_ and digits, is dropped before the ingest cap counts it, whatever sent it, so it raises no tingle and reaches no map, dependency, query or count. A database merely named alike, my_management_db_7 or management_db, is kept, and so is a span whose db.system.name or db.system names a system other than H2. A catalog record carries no database name for the ingest to read, so the extension never makes one for that database, and its SESSIONS table does not reach db_table (The index catalog). A span stored before this rule stays as it is, and leaves with the retention. A request body that is neither application/x-protobuf (also accepted as application/protobuf) nor application/json is 415. An undecodable body of an accepted type is 400. A span without a valid trace id and span id is skipped, and the rest of the request is stored. A valid trace id is 16 bytes and a valid span id 8, not all of them zero, as OTLP defines them. An invalid parent span id is read as none, and so are the invalid ids of a log record, so the span becomes a root and the log line stays uncorrelated. A parent span id equal to the span’s own id is read as none too. A resource with no service.name, or an empty or blank one, is the service unknown_service, the name OTLP gives an unset one. A start or end time of 0 or past 2^63 is no time: a span with a valid end starts at its end, one with a valid start ends at its start, and one with neither is skipped. The same holds for a log record, which then takes its observed time, or the time it arrived when that is none too, and for a metric point, which is skipped as a point with no value is. OTLP/JSON ids are accepted as hex, which is what the OTLP specification says, and as base64, which is what protobuf’s own JSON mapping produces. The two are told apart by length, since only a hex id is exactly 32 or 16 characters of [0-9a-f]. An OTLP/JSON id that is neither, such as one with a stray space or of a length no base64 has, or that is not a string, is no valid id either, so its span is skipped and the rest of the request is stored. The same holds for the proto field names (trace_id, span_id, parent_span_id), which protobuf’s JSON parser accepts beside the lowerCamelCase names the specification prescribes. An OTLP/JSON string escaping half of a surrogate pair on its own (\ud800) is stored with U+FFFD in its place, since UTF-8, and so every answer, has no form for it. The same holds for every other string that enters the store or the database from a request body or an imported document: the service and note of a mark, the note of an acknowledgement or a resolution, every string of an imported document, a member’s name included, and the statement of POST /api/sql, whose string cells carry U+FFFD for a lone surrogate the statement makes itself (CHAR(55296)). The JSON and the text renderings of one value then read the same character. A mark name holding one is refused as any name outside [A-Za-z0-9._-] is.

Apdex and the histogram

The bucket bounds come from the server’s slowRequestMs, not from the client, so every page and every service share one scale and the legend can be built from /api/status. An error request is counted in the fifth histogram slot only, whatever its duration, so a failing endpoint that answers fast still lowers the Apdex. apdex is null, never 0, when nothing was requested.

Tingles

Tingles are rows in the tingle table, so /api/overview.tingles survives a restart and is visible to every Spider Sense process sharing the database. That list folds the repeats of one service, kind and title into one entry: the newest of them, with count saying how many the window holds. The 50 entries are therefore 50 different combinations of service, kind and title, and one busy statement does not push a rarer one out of them. The server keeps no in-memory mirror of the last 500, because a mirror would be empty after a restart and would lack the tingles another process wrote to the shared database. A span has at most one tingle of each kind, so a span received again raises no second one, in the list or on the live event stream. An error tingle is raised for an entry span that failed, and for any other span carrying an exception event of its own, so a failure that propagated up a trace does not produce one tingle per frame. slow-query uses the span’s summary as its title and the statement as its detail.