Configuration

Every option of Spider Sense is a spidersense.* key. You set a key as a system property on the command line of the JVM that runs the application, or as a line of a properties file. The standalone jar also takes it as a --key=value argument. The sources in order of precedence, highest first, are the --key=value argument, the -Dspidersense.key system property, the environment variable of the same name, the properties file, and the default. The environment variable of a key is its name in upper case with every . and - made _, so spidersense.slow.query.ms is SPIDERSENSE_SLOW_QUERY_MS. An environment variable that is set but empty counts as unset, so it hides neither the properties file nor the default. An empty system property, such as the -Dspidersense.port= an unset shell variable leaves behind, counts as unset the same way, except for spidersense.ignore.endpoints, where an empty value ignores nothing, and spidersense.source.dirs, where it names no source root. So does an empty --key= argument of the standalone jar, with the same two exceptions. --host=$SPIDERSENSE_HOST with the variable unset binds the default address, and never reads as a wildcard bind that accepts any host name. --db=$SPIDERSENSE_DB_PATH with the variable unset opens the database the property, the variable or the properties file names, and the banner names that file. --port=$PORT with the variable unset takes the port the same way, rather than failing as a malformed number. A numeric key whose value is not a number, such as spidersense.slow.query.ms=1x, or spidersense.open set to something other than true or false, is a warning on stderr, and that key alone takes its default; every other key keeps its value. The launcher’s own arguments are the exception: the standalone jar answers a numeric --key=value argument that is not a number, such as --slow.query.ms=1x or --retention.spans=1x, as a usage error, printing spider-sense: --slow.query.ms is not a number: 1x on stderr and exiting 2 without starting. So is --open= with a value other than true or false, such as --open=yes. So is an argument whose key is not in the table below, such as --prot=4001, --mode=agent or --embedded-service=orders; java -jar spider-sense.jar --help lists the keys. A system property that starts with spidersense. but is not in the table, such as -Dspidersense.prot=4001, is a warning on stderr when the application or the standalone jar starts, naming the nearest key when one is close: [spider-sense] spidersense.prot is not a Spider Sense key (did you mean spidersense.port?). The application starts all the same, and the misspelt key has no effect.

Properties

Property Default Meaning

spidersense.port

4000

The UI and OTLP/HTTP port. 0 binds any free port, which the standalone banner names, and which under -javaagent the launcher prints on its UI: line and exports to.

spidersense.host

127.0.0.1

The bind address. Use 0.0.0.0 to reach it from another machine, which also accepts a request under any host name (API conventions).

spidersense.collector

unset

Agent mode: forward to this base URL instead of starting the embedded UI. A value without a scheme, such as 127.0.0.1:4000, is http://, as the CLI reads --url. See forwarding.

spidersense.service

unset

Agent mode: the default of otel.service.name. When both are set, otel.service.name names the service, for the exporter and for the embedded Spider Sense alike. Once either is set, the OpenTelemetry agent no longer reads Spring Boot’s spring.application.name, so the Gradle plugin, which sets this to the project’s name, wins over it; spiderSense { service = 'spring-orders' } names it otherwise (The block).

spidersense.db

~/db/spider-sense/sense

The H2 database path, or a jdbc:h2: URL. AUTO_SERVER=TRUE is appended to a path. See Storage.

spidersense.retention.hours

24

Rows older than this are deleted by the sweeper, and a service that has sent nothing for twice this is forgotten (Retention).

spidersense.retention.spans

1000000

The most span rows kept. The sweeper deletes the oldest hour of everything until the count is under it, and 0 means no cap. See Retention.

spidersense.ingest.max-spans-per-second

unset

Above this many spans in one second the receiver drops the spans of traces it has not seen yet, and counts them on /api/status. See the ingest cap.

spidersense.slow.request.ms

500

A server span slower than this is a tingle. It is also the Apdex scale.

spidersense.slow.query.ms

100

A database span slower than this is a tingle, and the one the extension captures a stack trace for.

spidersense.open

false

Agent mode: open the UI in the browser at startup (java.awt.Desktop), best effort; when forwarding, the collector’s UI.

spidersense.app.packages

unset

Comma-separated package prefixes that count as application code in a finding’s code frames. Unset means everything that is not a known framework. See the code frames.

spidersense.ignore.endpoints

/actuator/**,/health,/healthz,/livez,/readyz

Comma-separated glob patterns. An entry span whose endpoint matches one of them is not a request. An empty value ignores nothing. See Ignored endpoints.

spidersense.source.dirs

src/main/java and src/main/kotlin of the working directory and of each of its immediate subdirectories

Comma-separated source roots, relative ones against the working directory. A code frame resolves to the first file under them that matches its package and file name, which gives the UI its source lines and editor links and the CLI its suspect-change line. An empty value names no root and turns all three off. See Source roots.

On the command line

In agent mode the properties go on the same command line as -javaagent:, before -jar:

java -javaagent:"$SENSE" -Dspidersense.port=4001 -Dspidersense.slow.query.ms=50 -jar app.jar

The standalone jar accepts both forms, and --key=value is the shorter one:

java -jar "$SENSE" --port=4001 --host=0.0.0.0

From a build tool, the spiderSense { } block of the Gradle plugin has a line for every property in the table, and Maven passes them as JVM arguments.

In a properties file

The same keys go in a properties file, one per line, so the command line carries only -javaagent:

spider-sense.properties
spidersense.port=4001
spidersense.service=orders
spidersense.slow.query.ms=50
spidersense.ignore.endpoints=/actuator/**,/internal/**
java -javaagent:"$SENSE" -jar app.jar

Spider Sense reads spider-sense.properties from the working directory of the JVM, when that file exists. -Dspidersense.config=<path>, or the environment variable SPIDERSENSE_CONFIG, names another file. A named file that does not exist is a warning on stderr, and the application starts without it. The launcher names the file it read on stdout. The file is read as UTF-8, and a byte-order mark at its start, which Notepad and Windows PowerShell write, is skipped.

The launcher reads the file first, in premain, in the standalone main, and before it runs a CLI command. It applies every spidersense. key of the file as the system property of the same name, unless that property or its environment variable is already set. From then on the launcher, the server, the extension and the CLI read the system properties exactly as they do for -D, so the launcher is the only code that parses the file. A key given as a system property, or as an environment variable of the same name, therefore wins over the file. A value is trimmed, and an empty value counts: spidersense.ignore.endpoints= ignores nothing, as it does on the command line. Keys without the spidersense. prefix are left alone, so the same file can be handed to the OpenTelemetry agent with -Dotel.javaagent.configuration-file=spider-sense.properties and then carry otel. keys as well. A spidersense.* key that is not in the table is applied with a warning naming the nearest key, so a typo is visible.

The file is read in every mode: under -javaagent, by the standalone jar, and by the CLI. The CLI’s default --url is then the Spider Sense that the file’s spidersense.collector, or spidersense.host and spidersense.port with the defaults filled in, point to. A spidersense.port that is not a port from 0 to 65535 is a warning on the CLI’s stderr too, and the CLI asks the default port. A command run from the project’s directory therefore asks the Spider Sense that directory’s file points at. The environment variable SPIDERSENSE_URL still wins over what the file implies. Under the Gradle plugin or Maven the file is read as well, because the working directory of the forked JVM is the project’s. A -D property that the build tool adds wins over the file. The Gradle plugin’s configFile names another file, as -Dspidersense.config does.

Environment variables

Every key has the environment variable described at the top of this page. Two thresholds are also read from the environment by the OpenTelemetry agent extension itself, because the extension that captures stack traces is configured before the server is:

Variable Equivalent property

SPIDERSENSE_SLOW_QUERY_MS

spidersense.slow.query.ms

SPIDERSENSE_SLOW_REQUEST_MS

spidersense.slow.request.ms

Both are read once, when the extension is built.

OpenTelemetry properties

Every otel. system property and OTEL_ environment variable of the OpenTelemetry Java agent still works as that agent documents it. Spider Sense only fills in defaults, and only where you have set neither the property nor its environment variable. A key in the file -Dotel.javaagent.configuration-file names counts as set too, because the agent reads that file below the system properties Spider Sense would write. Spider Sense reads that file as the agent does: a leading ~ in its path stands for the home directory, and a byte that is not UTF-8 does not stop the read.

Table 1. What Spider Sense sets for the OpenTelemetry agent, unless you set it
Property Value Why

otel.exporter.otlp.protocol

http/protobuf

There is no gRPC receiver.

otel.exporter.otlp.endpoint

http://127.0.0.1:<port>;, or spidersense.collector when that is set

The literal address rather than localhost, which may resolve to ::1 while the UI binds 127.0.0.1.

otel.service.name

spidersense.service when given, otherwise unset

Left unset, the service is named by the OpenTelemetry agent’s detectors and then by the jar or the project, as The service name describes.

otel.bsp.schedule.delay, otel.blrp.schedule.delay

1000

A span or a log record is exported at most a second after it ends, so a request appears in the UI within a second or two. The Map waits for the other span of a call for a time reckoned from this delay, so a longer one can show a traced call as a host for a moment.

otel.metric.export.interval

5000

A metric is exported every five seconds, so the charts of the JVM and Metrics pages lag by about that much.

otel.metrics.exporter, otel.logs.exporter, otel.traces.exporter

otlp, or none when the embedded UI did not start and no Spider Sense answers at the port

All three signals go to the collector, and none goes to a port where nothing of Spider Sense’s receives them, where every export would fail (The Three Modes).

otel.javaagent.exclude-class-loaders

Spider Sense’s own server class loader, appended to a list you set

The agent skips every class the UI server defines, so the UI’s own requests never become spans.

otel.instrumentation.runtime-telemetry.enabled

true

The JVM metrics behind the JVM page. This is already the agent’s default.

otel.javaagent.extensions

The extension jar Spider Sense extracted, appended to a list you set

The extension records code.stacktrace on a slow query, on the fifth repeat of an N+1, and on a slow outbound call. It also reads the index catalog of the tables a slow statement touches, which is a finding’s schema block, and names a service nothing else named (The service name).

Beyond this table, Spider Sense sets in the application’s JVM only the spidersense.* keys of the properties file, each as the system property of the same name, and no other system property. Its own server logs at warn through a simplelogger.properties only its class loader sees, so an application that logs through slf4j-simple keeps its own level, and -Dorg.slf4j.simpleLogger.defaultLogLevel= still raises the server’s. In agent mode the embedded server touches no java.util.logging inside premain, so an application that names its own java.util.logging.manager in main, as JBoss Modules does, gets that manager. To that end the launcher sets org.eclipse.jetty.util.referencesPerCacheLine to 16 while the server starts, unless you set it, and removes it again before premain returns: without it Jetty would ask the platform MBean server, which initialises java.util.logging.

The service name

The first of these that names the service wins:

  1. otel.service.name, or the environment variable OTEL_SERVICE_NAME.

  2. spidersense.service, which the launcher hands on as otel.service.name when that is unset.

  3. service.name in otel.resource.attributes, or in OTEL_RESOURCE_ATTRIBUTES.

  4. spring.application.name of a Spring Boot application, which the OpenTelemetry agent reads from its configuration.

  5. Implementation-Title in the manifest of the jar java -jar runs, which a Spring Boot jar carries.

  6. The jar or the project the application was started from, which Spider Sense’s extension fills in.

The last one is Spider Sense’s own, and it applies only when the service would otherwise be unknown_service:java. java -jar build/libs/orders-0.1.0.jar is orders: the jar’s name without .jar and without a trailing version, so a release does not start a new service. The version is the numbers with what may follow them: a qualifier such as -SNAPSHOT, .RELEASE or -rc.1, a commit as git describe writes it with .dirty after it, as in -1.0.0-3-g1a2b3c4.dirty, and a classifier such as -all, -plain or Quarkus’s -runner. A number between two words is part of the name, so java-17-app.jar is java-17-app. A main class is named after the class path entry that holds it. A jar there is named the same way, which covers the start script of installDist, and a classes directory under build/ or target/ is named after its project, so orders/build/classes/java/main is orders. Failing both, the main class’s simple name is the service.

Set -Dotel.service.name= when the default is not the name you want, such as two applications started from jars of the same name. -Dspidersense.service= does the same thing in agent mode.

Ignored endpoints

spidersense.ignore.endpoints is a comma-separated list of glob patterns. An entry span whose endpoint matches one of them is written with entry false, exactly as a root INTERNAL span is (Endpoint identity). It is stored, is in its trace and is in the trace list, but it is not an endpoint, not a request, not in the Apdex, never a slow-request tingle, never a finding and never a check verdict. Neither is what it ran: its own failure, and every failure of a trace it is the root of, is in no error group, so the errors page, compare, findings and check all leave a 503 from a health check whose dependency is down locally out, and the statements and outbound calls of such a trace make no slow-query, slow-external or N+1 finding, although the queries page still lists the statements. Its ERROR log records, and those of a trace it is the root of, make no log-error finding and count to no --max-log-errors, although the logs page still lists them. An ignored span inside another request’s trace, a health check that request called, leaves out only its own failure and the log records written on it; what ran under it belongs to the request that made the call.

A health check polled every few seconds is the most frequent request of a typical Spring Boot application. It is fast and it never fails, so counted as a request it would raise the request count and the Apdex and lower the error rate and the Overview’s p95, and check --max-error-rate and --min-apdex would judge those numbers. The default is /actuator/**,/health,/healthz,/livez,/readyz, and an empty value ignores nothing:

java -javaagent:"$SENSE" -Dspidersense.ignore.endpoints= -jar app.jar

A pattern is matched against the endpoint name as Endpoint identity defines it, which is GET /actuator/health when the framework reports a route, and the span name when it does not.

  • A pattern that starts with / is matched against the name with its leading METHOD ` removed, so `/actuator/** covers every method.

  • A pattern with a method, such as GET /actuator/**, is matched against the whole name.

  • When neither matches and the span carries url.path, the same patterns are tried against METHOD url.path and against url.path, so a framework that reports no route is still covered.

* matches anything including /, matches anything but /, and ? matches one character that is not /. The match is case-sensitive and covers the whole name. /api/status shows the list in force as ignore.endpoints, and so does the text rendering of the status command.

Source roots

Spider Sense runs on the machine that holds the source tree, so it reads the file a code frame names and shows the lines the frame points at. A frame orders.OrderService.load(OrderService.java:41) resolves to the first <root>/orders/OrderService.java that exists under the roots of spidersense.source.dirs.

The default covers a single-module build and a multi-module one: src/main/java and src/main/kotlin of the working directory, then the same two under each of its immediate subdirectories. Under the Gradle plugin, Maven or java -jar from the project directory, the working directory is the project’s, so the default usually fits. Name the roots when the sources live elsewhere, or deeper:

java -javaagent:"$SENSE" -Dspidersense.source.dirs=services/orders/src/main/java,shared/src/main/java -jar app.jar

A root that does not exist is left out. A frame without a file and a line, such as Unknown Source, does not resolve. Neither does a frame whose path would leave its root: only dotted Java identifiers and a plain file name with a .java, .kt, .groovy or .scala extension make a path, and the file, symbolic links followed, must lie under its root. The CLI reads the same property, as -Dspidersense.source.dirs before -jar or from spider-sense.properties, to find a frame’s file for its suspect-change line. When no root has the file, the CLI also looks for it among the files of the repository it runs in, unless the property is empty.

How to send data

Data reaches the collector in three ways. The UI’s "How to send data" dialog prints all three with the port actually in use.

A JVM under the OpenTelemetry Java agent that Spider Sense carries:

java -javaagent:"$SENSE" -Dotel.service.name=my-app -jar app.jar

Any OpenTelemetry SDK, pointed at a standalone Spider Sense (Python, Node.js and Go):

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4000
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

The same two variables point a Java application under the stock OpenTelemetry Java agent, or any compatible agent, at it:

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4000 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
    java -javaagent:opentelemetry-javaagent.jar -Dotel.service.name=my-app -jar app.jar

It lacks the defaults and the extension the Spider Sense jar adds, as Standalone describes.

Anything that can post JSON, over OTLP/JSON:

curl -X POST http://127.0.0.1:4000/v1/traces \
     -H 'Content-Type: application/json' \
     -d @spans.json

/v1/traces, /v1/metrics and /v1/logs accept application/x-protobuf and application/json, with Content-Encoding: gzip. The HTTP API describes what each one answers.