Skip to content

threadmill-tracing

Optional OpenTelemetry tracing for Threadmill.

The module depends on opentelemetry-api only. Applications keep ownership of the OpenTelemetry SDK, exporter, sampling, and resource configuration.

var tracing = ThreadmillTracing.global();
var store = tracing.wrapStore(new PostgresJobStore(dataSource));
var node = ProcessingNode.builder(store)
.interceptor(tracing.asInterceptor())
.build();

In Spring Boot, expose tracing.asInterceptor() as a JobInterceptor bean. The auto-configuration adds user-provided interceptors to the ProcessingNode.

Processing spans are named threadmill.job.process and carry job id, queue, handler type, attempt, node id, final state, and failure cause when present. Store spans are named threadmill.store.* and carry the store description plus operation-specific attributes such as queue, job id, and claimed count.

The processing span scope intentionally spans the handler invocation. That relies on Threadmill’s JobRunner contract that interceptor start, handler execution, and interceptor success/failure callbacks run on the same execution thread.

The traced store is a full decorator: it extends the core ForwardingJobStore, so capability lookups such as describe(), supportsExternalTransactions(), and createRemoteWakeChannel(...) reach the wrapped store unchanged and delegate() returns the wrapped store. Wrapping a PostgreSQL store keeps its join_transaction support and LISTEN/NOTIFY wake channel.

Processing scopes are tied to each execution context and closed on the same thread by the engine’s guaranteed onProcessingFinished hook. Orphan recovery uses a separate span. threadmill.execution.completion_confirmed=false marks an execution exit without a confirmed persisted outcome notification, including stale terminal writes. Custom direct interceptor drivers must invoke the cleanup hook in finally, after success/failure notifications.