structured-coroutines-runtime/io.github.santimattius.structured.runtime/TraceEvent

TraceEvent

An observation emitted to a TraceSink. Sealed so subtypes can be added later; sinks must ignore subtypes they do not know.

Subclasses are final classes with explicit equals/hashCode/toString rather than data classes, so new fields can be added in later releases without breaking binary compatibility. coroutineName and thread are null unless TraceLevel.Coroutine is enabled and the platform supports it.

Example:

val sink = TraceSink { event ->
    if (event is TraceEvent.Finished) println("${event.dispatcher} ran ${event.runTimeNanos}ns")
}

Requires opting in to ExperimentalStructuredCoroutines.

Inheritors

Types

Finished

class Finished @JvmOverloads constructor(val dispatcher: String, val timestampNanos: Long, val runTimeNanos: Long, val outcome: TraceOutcome, val coroutineName: String?, val thread: ThreadInfo?, val spanId: Long? = null, val parentSpanId: Long? = null, val dispatchId: Long = 0, val spanName: String? = null) : TraceEvent

A block finished after running for runTimeNanos, with the given outcome.

PoolSample

class PoolSample(val dispatcher: String, val timestampNanos: Long, val queued: Long, val started: Long, val finished: Long, val pending: Long, val running: Int, val peakRunning: Int, val parallelism: Int?) : TraceEvent

A periodic snapshot of one dispatcher pool, produced by PoolSampler (never by TracingDispatcher) at TraceLevel.Pool. A series of samples shows how the pool behaves over time, which cumulative DispatcherMetrics cannot.

Queued

class Queued @JvmOverloads constructor(val dispatcher: String, val timestampNanos: Long, val coroutineName: String?, val spanId: Long? = null, val parentSpanId: Long? = null, val dispatchId: Long = 0, val spanName: String? = null) : TraceEvent

A block was handed to the dispatcher. dispatchId identifies this one dispatched runnable across its Queued, Started and Finished events. spanId, parentSpanId and spanName come from the TraceSpan in the dispatch context and are null when there is none (same on Started and Finished).

Started

class Started @JvmOverloads constructor(val dispatcher: String, val timestampNanos: Long, val queueDelayNanos: Long, val coroutineName: String?, val thread: ThreadInfo?, val spanId: Long? = null, val parentSpanId: Long? = null, val dispatchId: Long = 0, val spanName: String? = null) : TraceEvent

A block began running after waiting queueDelayNanos in the queue.

Properties

dispatcher

abstract val dispatcher: String

Label of the dispatcher that produced the event, such as "io" or "default".

level

abstract val level: TraceLevel

Lowest TraceLevel at which this event is produced.

timestampNanos

abstract val timestampNanos: Long

Monotonic timestamp in nanoseconds. Only differences between events are meaningful.

TraceEvent

See also

Inheritors

Types

Properties